Skip to main content

Fundamentals of building with Klaviyo

Course overview
Lesson
3 min read

Build your consent architecture

Now that we've looked at how Maya engages with Eastie, and the backend decisions that power a personalized experience, there's one more thing that determines whether she can actually receive that email or text: Consent.

Why consent architecture matters to developers

If you are building or maintaining a Klaviyo integration, you are deciding how consent moves between systems, which system is treated as the source of truth, and what happens when systems disagree.

If not done thoughtfully, you risk messaging someone who did not consent to receive communications from you, which is a compliance risk.

This is one of the few areas in this certificate where implementation decisions have direct compliance consequences.

What Klaviyo tracks, how it is collected, and where it lives

What is consent?

Consent is permission to receive marketing or other eligible communications through a specific channel. Consent should come from a subscriber action or from a consent record that your organization can reasonably support and trace back to the subscriber.

Klaviyo tracks consent by channel and message type. Email consent lives on each profile. Text messaging consent follows the phone number, so if one profile unsubscribes, every profile with that number is unsubscribed.

Depending on the channel, that can include email marketing, text messaging marketing, text messaging transactional, WhatsApp marketing, WhatsApp transactional, WhatsApp conversational, and push-related delivery state.

A marketer cannot infer consent from purchase history, page views, or the presence of a phone number. Channel requirements and regional rules differ, so your integration should make the intended consent action explicit and retain the supporting record.

Klaviyo multi-step form displaying separate consent fields for email and text messaging

Consent is channel specific

Email consent, text messaging consent, and WhatsApp consent are independent. Subscribing someone to email does not subscribe them to text messaging. Text messaging consent has to be collected with its own separate checkbox or action, even on a form that also collects email.

When writing consent through an API, explicitly identify the intended channel and message type. Do not assume that including an email address or phone number communicates the subscriber's intent.

Popup showing marketing a consent checkbox for text messages, along with terms of service and privacy policy links

How consent is collected

Consent can be collected through forms, prebuilt integrations, and SFTP/CSV uploads, including ongoing updates from a system that holds consent records. You can also write consent through the API in a few distinct ways:

  • Create Client Subscription: Use this for public, browser-facing sign-up forms.
  • Subscribe Profiles: Use this for server-side calls, backend jobs, migrations, or anything happening on your own infrastructure.
  • Add Profile to List: Use this when you want to add someone to a list without subscribing them. In that case, they remain NEVER_SUBSCRIBED.

One important nuance: if you omit the subscriptions object on a Subscribe Profiles call, Klaviyo subscribes the profile to each channel that matches an identifier you send. For example:

  • email address → email marketing subscription
  • phone number → text messaging marketing
  • both identifiers → email and text messaging marketing subscriptions

Failure example: a backend sends both an email address and a phone number to capture email consent, without a subscriptions object. Klaviyo can subscribe the profile to text messaging marketing too, even though the team only meant to capture email consent.

__wf_reserved_inherit

Consent, suppression, and delivery eligibility

Consent, suppression, and "can receive marketing" are three different concepts.

  • Consent is the permission state for a channel or message type.
  • Having a suppressed status for the email channel blocks non-transactional email messages. A profile can remain subscribed to email while also being suppressed.

For example, a profile can be subscribed to email but suppressed because of a hard bounce, spam complaint, or manual suppression. Unsuppressing a profile does not create consent. It only removes manual suppressions. If the profile hasn't unsubscribed, they can receive email marketing again.

  • Can receive marketing is the resolved delivery decision after consent, suppression, and other eligibility rules are evaluated.
json
{
  "data": [
    {
      "type": "profile",
      "id": "01EFPSGTVXBGERQPGM3VQ734KS",
      "attributes": {
        "email": "str",
        ...
        "subscriptions": {
          "email": {
            "marketing": {
              "can_receive_email_marketing": true,
              "consent": "NEVER_SUBSCRIBED",
              "consent_timestamp": null,
              "last_updated": null,
              "method": null,
              "method_detail": null,
              "custom_method_detail": null,
              "double_optin": null,
              "suppression": [],
              "list_suppressions": []
            }
          },
          "sms": {
            "marketing": {
              "can_receive_sms_marketing": true,
              "consent": "SUBSCRIBED",
              "consent_timestamp": "2023-07-28T13:26:48.852051+00:00",
              "method": "TEXT",
              "method_detail": "JOIN",
              "last_updated": "2023-07-28T13:26:48.852051+00:00"
            }
          }
        }
      },
      ...
    }
  ]
}

This profile never subscribed to email, but can still receive email marketing. That's the gap between consent and delivery eligibility. Text messaging, on the other hand, was explicitly subscribed by texting a keyword (method: TEXT, detail: JOIN).

Segment builder with the email marketing consent criteria

This table is not exhaustive but exposes you to some of the decisions that you may need to make when building your consent architecture.

Email

Text Messaging

WhatsApp

Push

Consent model

Consent lives on each profile. Suppression is applied using the email address.

Text messaging consent is associated with the specific phone number that opted in. If the phone number changes, the new number must subscribe separately.

Marketing, transactional, and conversational permissions are separate. Conversational permission can be time-limited and does not grant marketing permission.

Delivery depends on applicable consent and a valid push token. The token identifies the device.

How consent is collected

Forms, checkout, API, CSV/SFTP

Forms, checkout, API, CSV/SFTP; own checkbox required

Forms, API, list upload

API subscribe with a push token; token registers on subscribe

How it's unsubscribed

Unsubscribe link or API. Note that unsubscribe links (where a subscriber can unsubscribe from a specific set of emails, i.e. promotional emails, but stay subscribed to other emails, i.e. back-in-stock emails) and preference centers are common management paths.

Keyword (STOP-style) or API

Keyword or API

API unsubscribe; removes the token

Gotchas

Suppression is separate from consent. Regional rules may permit implied consent for some email use cases, but Klaviyo recommends caution with never-subscribed profiles. Never subscribed profiles can only receive email, not text messages or push. Implied consent never applies to text messaging. If you identify profiles by external ID, duplicate profiles with the same email can have different consent statuses.

Marketing and transactional are separate fields, but unsubscribing from one currently cascades to the other by default. It is possible to control one-by-one at the API level, but texting STOP unsubscribes the profile from both marketing and transactional text messages.

An eligible inbound WhatsApp message can create conversational permission for 24 hours. This permission is separate from marketing permission. WhatsApp unsubscribe can revoke marketing, transactional, and conversational permissions together.

A valid push token is required for delivery, but the token is not a substitute for consent. Token removal and marketing unsubscribe should be modeled as separate events.

Key nuances

Resubscribing someone should always be intentional and based on their current consent. When syncing historical data, only write consent states your source system can support, so you don't overwrite existing unsubscribes.

Select a topic to expand it.

Single opt-in vs. double opt-in

Opt-in is set at the list level. If the subscribe event doesn't include a list, the account's opt-in configuration applies instead. There are two types of opt-in:

  • Single opt-in: Someone is subscribed as soon as they submit a form or check a box.
  • Double opt-in: There is an additional confirmation step, usually clicking a link in a follow-up email, before consent is considered valid. Klaviyo recommends double opt-in as a best practice because it can help confirm that the subscriber provided a valid address and intended to subscribe. This filters out typos and fake addresses before they reach your list, helping protect sender reputation and improve list quality.

If your Subscribe Profiles calls are accepted but consent status isn't changing, check whether the list is double opt-in. The profile won't show as subscribed until they confirm. If no list is included, Klaviyo uses the account's opt-in configuration, which is double opt-in by default but can be updated to single opt-in.

Multi-region consent

Frameworks like GDPR generally require a clearer and more explicit consent action than many U.S. defaults assume. A form or workflow that is compliant in one market may not be compliant in another.

Treat the form language, Terms of Service, Privacy Policy, channel, message purpose, and unsubscribe instructions as a package that should be reviewed for the markets where the customer operates.

Email marketing consent and consent for onsite tracking are separate. Subscribing someone to email doesn't give you permission to track their browsing. In regions like the EU, EEA, UK, and Switzerland, Klaviyo may not track onsite events like Viewed Product and Added to Cart for visitors who haven't consented to onsite tracking.

External systems vs. Klaviyo: what syncs and what doesn't

Consent doesn’t automatically stay in sync between Klaviyo and your other systems.

For example, Klaviyo’s Shopify integration syncs subscribes from Shopify, but not unsubscribes. If you’re migrating, import suppressions manually, and treat Klaviyo as the source of truth for consent from then on.

To keep other systems up to date, poll Klaviyo on a schedule for profiles whose consent changed recently. Don’t expect Klaviyo to push every update automatically.

Ad platforms need extra care. Syncing a segment to a paid social audience doesn’t guarantee every privacy preference is honored, so build those exclusions into the segment itself. Relying on the sync alone is a compliance risk.

Consent requires a subscriber action

Consent has to come from the subscriber.

Even a well-intentioned workaround, like texting someone first to start a sign-up flow on their behalf, is not valid consent if the subscriber did not take the action themselves.

Activity: Match the scenario to the endpoint

Match the scenario to the endpoint
Scenario
Eastie's server runs a nightly job to subscribe new loyalty members who opted in
A shopper gives their email at checkout but doesn't check the marketing box
A customer asks Eastie's support team to stop sending marketing texts
Maya fills out the newsletter form on Eastie's site
Endpoint
Add Profile to List
Subscribe Profiles
Create Client Subscription
Unsubscribe Profiles
Build your consent architecture