HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides
ChangelogHelp CenterCommunityContact Us
These docs are for v2023-08-15. Click to read the latest docs for v2024-10-15.

Collect email and SMS consent via API

Learn how to collect consent and best practices

It's crucial to collect email and SMS consent properly to comply with necessary regulations and maintain a positive relationship with your customers. There are multiple ways to subscribe a profile in Klaviyo. Subscriptions can be created via our API, sign-up forms, native or third party integrations, a manual CSV import, and more. In this guide, we’ll focus on subscribing via API as well as covering the type of information you can get via API around consent and suppressions.

Obtaining email and SMS consent is essential for effective marketing, as it also allows businesses to communicate with their customers in a way that is both relevant and personalized, ultimately resulting in higher engagement rates and better return on investment.

🚧

This information is not legal advice. Klaviyo recommends that you consult with your legal counsel to make sure that you comply with applicable laws in connection with your marketing activities.

Relevant endpoints

At Klaviyo, consent status indicates whether or not someone requested to receive your SMS and/or email marketing. A profile can have a consent status of SUBSCRIBED, NEVER SUBSCRIBED, or UNSUBSCRIBED

The API endpoints we’ll cover in this article include:

  • Subscribe Profiles
    Used to subscribe a profile to email and/or SMS marketing.
  • Unsubscribe Profiles
    Used to unsubscribe a profile from email and/or SMS marketing.
  • Suppress Profiles
    Used to suppress a profile to prevent it from receiving email and/or SMS marketing regardless of consent status.
  • Unsuppress Profiles
    Used to unsuppress a profile to allow it to receive email and/or SMS marketing.
  • Add Profile to List
    Used to add a profile to a list with the given list ID.

In addition to reviewing this guide, we recommend that you make test calls to these endpoints to better understand how they work. Klaviyo maintains a Postman collection you can use to get familiar with these API calls.

Subscribe a profile via API

To subscribe a profile via API, follow these steps:

  1. Create new profiles or have existing profiles that you want to subscribe.
  2. If the profile gave consent, use the subscription endpoints to subscribe the profile to the appropriate channels (email and/or SMS).
  3. If a profile has not given explicit consent but you have implicit consent (see below for more information on implied consent) you can use the Add Profile to List endpoint to add a profile to a list without subscribing them. In this case, the profile would be added to your list, but would maintain a consent status of NEVER_SUBSCRIBED.

The example below is an API request to the Subscribe Profiles endpoint. Make sure to fill out placeholder information such as the private API key, etc.

curl --request POST \
     --url https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs/ \
     --header 'Authorization: Klaviyo-API-Key {your-private-api-key}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: {YYYY-MM-DD}' \
     --data '
{
    "data":{
       "type":"profile-subscription-bulk-create-job",
       "attributes":{
          "custom_source":"Marketing Event",
          "profiles":{
             "data":[
                {
                   "type":"profile",
                   "attributes":{
                      "email":"[email protected]",
                      "phone_number":"+15005550006",
                      "subscriptions":{
                         "email":[
                            "MARKETING"
                         ],
                         "sms":[
                            "MARKETING"
                         ]
                      }
                   }
                }
             ]
          }
       },
       "relationships":{
          "list":{
             "data":{
                "type":"list",
                "id":"Y6nRLr"
             }
          }
       }
    }
 }

📘

Due to the asynchronous nature of the API call, it may take a short amount of time for the result to display in Klaviyo or in a GET API call.

Single vs double opt-in

When subscribing a profile via API, if your list is single opt-in, your API response data will contain the subscribed profile_id along with the list of added records, such as email and phone number, in the API response.

If double opt-in is turned on, the profile being subscribed will be asked to confirm their subscription. In this case, you will not see the profile’s data in your API requests nor will you see an update to the Channel box in the Klaviyo UI until the subscriber has finished opting in.

If you don't want the double opt-in email or SMS to be sent, then make sure the list you're subscribing profiles to is set to single opt-in.

📘

If your API calls to the Subscribe Profiles endpoint are being accepted, but the consent status of a profile isn't changing, double check to see if the list they are being subscribed to is double opt-in.

About subscriptions and consent

Implicit consent is when someone gives you their contact information (e.g., email address, phone number, etc.) but does not explicitly say they want to receive marketing messages from your brand. These profiles will have the consent status NEVER_SUBSCRIBED. A common example of implicit consent is when a customer makes a purchase and provides their email at checkout. They have not explicitly said they want to receive marketing messages from the brand, but it can be inferred that they have an interest in relevant content. In this case, you have their information, but they haven’t agreed to receive marketing communications.

These profiles are able to receive emails, but you should exercise caution when contacting them. Depending on your local regulations, you may (or may not) be permitted to email these profiles if you believe they have implied consent. Read Understanding explicit vs. implicit consentto learn more, and make sure to check your local laws and regulations regarding implicit consent.

🚧

Klaviyo recommends that you only email profiles with express consent to protect your deliverability and sender reputation. Implied consent does not apply to SMS subscriptions. Consent must be explicit for SMS.

SMS-specific considerations

Configuring SMS

Before you can collect SMS consent, you must have:

  • Enabled SMS in Klaviyo.
  • Set up your sending number(s).

If you have not enabled SMS in your account or set up your sending number(s), you can learn more in How to turn on SMS in Klaviyo. If SMS setup is incomplete, you may receive a response like below when attempting to add consent data:

"SMS configuration is required to subscribe phone number only profiles."

If you receive this response from your API call, double check your account’s SMS configuration.

Phone number validation

After your Klaviyo account has been set up to collect consent, you’ll next need to validate each phone number passed via API, otherwise the API call may fail.

When passing in a phone number to our API, ensures that the phone number is:

  1. A valid (real) phone number.
  2. Your account’s sending number supports the country code.
  3. You have no spaces between numbers.

Get subscription information via API

The subscription object

Below is an example of a subscription object that would be returned when making a call to the Get Profile endpoint. Note that subscription objects are always associated with a profile object.

{
  "data": {
    "type": "profile",
    "id": str,
    "attributes": {
      "email": str,
      "phone_number": str,
      ...
      "location": {},
      "properties": {},
      "subscriptions": {
        "email": {
          "marketing": {
            "consent": Enum("SUBSCRIBED", "NEVER_SUBSCRIBED", "UNSUBSCRIBED")
            "timestamp": datetime,
            "method": Enum("KLAVIYO_FORM", "API", "SHOPIFY", etc…),
            "method_detail": Optional[str],
            "custom_method_detail": Optional[str],
            "double_optin": Optional[bool],
            "suppressions": [
              {
                "suppression_reason": Enum("USER_SUPPRESSED", "HARD_BOUNCE", 
                  "INVALID_EMAIL", "UNSUBSCRIBED", "SPAM_REPORT"),
                "timestamp": datetime,
              }
            ],
            "list_suppressions": [
              {
                "list_id": str,
                "reason": Enum("USER_SUPPRESSED", "UNSUBSCRIBED"),
                "timestamp": datetime,
              }
            ]
          }
        },
        "sms": {
          "marketing": {
            "consent": Enum("SUBSCRIBED", "NEVER_SUBSCRIBED", "UNSUBSCRIBED")
            "timestamp": datetime,
            "method": Enum("Klaviyo Form", "API", "Shopify", etc…),
            "method_detail": Optional[str],
          }
        }
      }
    }
  }
}

Note the following:

  • It is recommended to use the channels object to explicitly set the marketing channels you want the profile to subscribe to. This object is related to the “Channel Status” Box that exists in the Klaviyo UI. See Understanding consent in profiles to learn more and see associated visual indicators.
  • method_detail may contain additional information depending on the source used for the subscription.
  • custom_method_detail will contain any information passed into the optional custom_source field for Subscribe Profiles and Create Client Subscription
    • The custom_source field is equivalent to the $source parameter In the legacy v2 Subscribe API.
  • The double opt-in field, double_optin, is controlled by Klaviyo and is only set to true if the email recipient received a double opt-in message and confirmed it.

Unsubscribing a profile via API

Use the Unsubscribe Profiles endpoint to unsubscribe one or more profiles from email marketing, SMS marketing, or both.

To remove someone from a list without changing their subscription status, use the Remove Profile from List endpoint.

Suppressing a profile via API

Suppressions are separate concept from consent status. Suppression status tells you if a profile is to receive your email marketing. Suppression status does not yet exist for SMS. There may be situations where you will not want to send marketing to someone, even if they previously expressed interest in receiving it. For example, you may want to suppress a consented profile if they are no longer engaged.

Use the Suppress Profiles endpoint to manually suppress one or more profiles. Such profiles will have USER_SUPPRESSED as their suppression reason. Manually suppressed profiles will not receive email marketing.

Use the Unsuppress Profiles endpoint to unsuppress one or more profiles. This will remove any manual suppressions (USER_SUPPRESSED) on these profiles. A profile may receive email marketing after a manual suppression is removed, so long as they have not revoked consent, i.e. unsubscribed.

📘

Currently, you can only suppress or unsuppress a profile via an email identifier.

Learn more about suppressed profiles in Understanding suppressed email profiles.

Additional resources

Updated about 1 year ago

Power smarter
digital relationships
By entering your information and clicking “Sign up,” you consent to receive marketing emails (such as newsletters, blog posts, webinars, event invitations and new product updates) from Klaviyo from time to time. You can unsubscribe at any time by clicking on the “Unsubscribe” link at the bottom of our emails. For more information on how we process your personal information and what rights you have in this respect, please see our Privacy Policy.
Terms and Privacy Trademarks Security