Klaviyo Integration Guide – Help Center

How Wunderkind Integrates With Klaviyo

The Klaviyo integration with Wunderkind will enable us to collect and send new email addresses to your ESP, verify subscription status before sending an email, and update a user’s subscriber status if they unsubscribe.

This guide includes an overview of everything that Wunderkind can and cannot support, considerations, requirements placed on us by Klaviyo, and more.

Wunderkind requires UI access to Klaviyo in order to build and test our integration with your Klaviyo instance.

1. Authentication

In order to authenticate our API calls, we use the Private API Key generated specifically for Wunderkind in your Klaviyo account. The Wunderkind team will create the API Key once an admin account is created for us.

Please create an admin user for Wunderkind.

To add a new user, navigate to Account > Settings > Users. Here, select “Add New User” and select the “Admin” role. Use esp+{brandname}@wunderkind.co as the email address, where {brandname} is your company name. For more details, see this Help Center article: Add Users & Manage Permissions.

2. Writing New Subscribers

Upon email submission, Wunderkind will subscribe users to a list if Klaviyo through the API call belows. Please let us know what list id(s) we should subscribe users to.

We may optionally send custom attributes in key:value pairs under data > attributes > properties in the Create or Update Profile API call.

Phone numbers can be subscribed with an email capture on the same step, or in a phone number-only campaign.

API Calls for Writing New Subscribers

We'll make 3 API calls upon submission:

1. Check Subscription Status
GET https://a.klaviyo.com/api/profiles?filter=equals(email,"<email_address>")

In order to determine a duplicate subscriber for email/SMS capture (eg, to avoid generating coupon codes for existing subscribers), we check the subscriptions object on the user’s profile. If the profile exists and the email marketing consent value is “SUBSCRIBED”, they are considered a duplicate.

2. Create or Update Profile
POST/PATCH https://a.klaviyo.com/api/profiles
{
"data": {
"type": "profile",
"attributes": {
"properties": {
"<key>": "<val>" // from opt_extra_fields
},
"email": "<email_address>",
"phone_number": "<phone_number>"
}
}
}

3. Subscribe Profile to List
POST https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs
{
 "data": {
   "type": "profile-subscription-bulk-create-job",
   "attributes": {
     "custom_source": "<custom_source>",
     "profiles": {
       "data": [
         {
           "type": "profile",
           "id": "<id from Create Profile>",
           "attributes": {
             "email": "<email>",
             "phone_number": "<phone_number>",
             "subscriptions": {
               "email": [
                 "MARKETING"
               ],
               "sms": [
                 "MARKETING"
               ]
             }
           }
         }
       ]
     }
   },
   "relationships": {
     "list": {
       "data": {
         "type": "list",
         "id": "<list id>"
       }
     }
   }
 }
}

Note: if capturing both email and phone number and SMS uses a separate list, phone subscription will be made in a separate API call.

3. Checking Customer Status

We confirm a user's customer status by checking for their presence on a segment in Klaviyo. Please set up a custom segment containing all previous purchasers (and only those profiles) and let your Wunderkind contact know the Segment Id.

If you don’t store customer or order information in Klaviyo, we’ll use our conversion pixel and/or historical data uploads to determine previous customer status.

Example segment settings for previous purchasers. Please also be sure to make sure your segment is “starred” so it does not become inactive.

API Calls for Checking Customer Status

Filter feature: https://developers.klaviyo.com/en/reference/api_overview#filtering

Get Segment Profiles: https://developers.klaviyo.com/en/reference/get_segment_profiles

GET https://a.klaviyo.com/api/segments{customer_segment_id}/profiles/ ?fields[profile]=id&filter=equals(email,"{emailaddress}")&page[size]=1
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15

4. Checking Mailability

We have several options for checking a user’s mailable status. Please let us know which approach you’d like to take for your Klaviyo setup.

Opt-In Segment Check: Requires a segment made up of subscribed users in Klaviyo. Only users present on this subscriber segment will be mailable. All other users will be considered unsubscribed (including users who do not exist in the ESP).
Opt-Out Segment Check: Requires a segment made up of unsubscribed users in Klaviyo. Users who are not present on this segment (including users who do not exist in the ESP) will be mailable.
Opt-Out Global Check: If a user’s email marketing consent status equals UNSUBSCRIBED, they will be considered unsubscribed. All other users (including users who do not exist in the ESP) will be mailable.
Opt-In Global Check: If a user does not exist in the ESP or their email marketing consent status equals UNSUBSCRIBED they will be considered unsubscribed.
List Check: Requires a list of users in Klaviyo. If user is present on list, this check returns true. We can use this approach for either an opt-in (list of subscribed users) or opt-out check (list of unsubscribed users)
Klaviyo Suppressions. Requires a Klaviyo Sender Integration and global unsubscribes enabled within Klaviyo. If a user’s email marketing consent status equals "UNSUBSCRIBED" they will be suppressed by Klaviyo. No API call is made by Wunderkind outside of the triggered send call.
1. Note that this approach means that we won’t have accurate send or unsubscribe data within Wunderkind’s reporting platform. This reporting will be available in Klaviyo.

API Calls for Checking Mailability

Options 1 and 2: Segment Check

GET https://a.klaviyo.com/api/segments{segment_id}/profiles/
?fields[profile]=id&filter=equals(email,"{emailaddress}")&page[size]=1
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15

Options 3 and 4: Global Check 
Get Profiles: https://developers.klaviyo.com/en/reference/get_profiles 

GET https://a.klaviyo.com/profiles/ ?fields[profile]=subscriptions.email.marketing.consent&filter=equals(email,"{emailaddress}")&page[size]=1
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15

Option 5: List Check
Get List Profiles: https://developers.klaviyo.com/en/reference/get_list_profiles

GET https://a.klaviyo.com/lists/{list_id}/profiles/ ?fields[profile]=id&filter=equals(email,"{emailaddress")&page[size]=1
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15

Example of option 2, Opt-Out Segment Check:

5. Updating Unsubscribe Status

We have a few options for updating a user’s unsubscribe status in Klaviyo after unsubscribing from a Wunderkind email. Please let us know which approach you’d like to take.

Globally + List Specific: Requires list where unsubscribe should take place. This method unsubscribes a user globally (setting their email marketing consent status to UNSUBSCRIBED) and removes them from the specified list. Must be a list ID, not a segment ID.
Globally: Unsubscribes a user globally, setting their email marketing consent status to UNSUBSCRIBED
Klaviyo Unsubscribes: If on a Klaviyo Sender Integration, it’s required that you use Klaviyo’s unsubscribe link. This gets added automatically to all emails deployed through Klaviyo’s platform. Global unsubscribe setting should be enabled so that the unsubscribe link sets a user's email marketing content status to UNSUBSCRIBED. More information on the Klaviyo Sender Integration is in Section 6.

API Calls for Updating Unsubscribe Status

Options 1 and 2
Unsubscribe Profiles: https://developers.klaviyo.com/en/reference/unsubscribe_profiles

POST https://a.klaviyo.com/api/profile-subscription-bulk-delete-jobs/
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15
Content-Type: application/json

[Global+List body]
{
"data": {
"type": "profile-subscription-bulk-delete-job",
"attributes": {
"profiles": {
"data":[{ 
"type": "profile",
"attributes": { 
"email": "{emailaddress}"
}
}]
}
},
"relationships": {
"list": { 
"data": {
"type": "list",
"id": "{list_id}"
}
}
}
}
}

[Global body]
{
"data": {
"type": "profile-subscription-bulk-delete-job",
"attributes": {
"profiles": {
"data":[{ 
"type": "profile",
"attributes": { 
"email": "{emailaddress}"
}
}]
}
}
}
}

6. Sender Options

Wunderkind is able to deploy an email in two ways: either through Wunderkind’s ESP, or through your Klaviyo account (this is called “Client Sender”).

Klaviyo Client Sender

With a Klaviyo Sender Integration, Wunderkind sends a fully-rendered email to Klaviyo for deployment, utilizing Klaviyo’s event API and setting up campaigns within Klaviyo as Flows.

The email content resides on Wunderkind’s platform and is transmitted via the API, containing all elements within the HTML body except for the footer. Klaviyo appends its standard footer, containing a global unsubscribe link, to all emails dispatched through its platform. This provides recipients with the option to unsubscribe from all marketing messages.

If a user does not exist at the time of send, they are created in Klaviyo with the status: Never subscribed

Please ensure that any Wunderkind Flows within Klaviyo have SmartSender turned OFF.

Wunderkind Sender

With the Wunderkind Sender, we deploy Wunderkind emails through our own Email Service Provider.

Included in this sender is the capability to update a user's profile in Klaviyo after sending. For instance, this could involve a request to Klaviyo to update a custom property like 'last-wunderkind-send-date' following our dispatch through the ESP. We only initiate this update to Klaviyo if the email successfully sends through our system and if the user already exists within Klaviyo. Therefore it requires two API calls: one to get a user’s profile and a second to update the user’s profile with the ID returned from the response in the first call.

API Calls for Sender

Klaviyo Client Sender 
POST https://a.klaviyo.com/api/events
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15
Content-Type: application/json
{
"data": {
"type": "event",
"attributes": {
"properties": {
"subject":"{subject}",
"body":"{body}",
"from_email":"{from}",
"from":"{fromname}"
},
"metric": {
"data": {
"type": "metric",
"attributes": {
"name": "{metric}"
}
}
},
"profile": {
"data": {
"type": "profile",
"attributes": {
"email": "{emailaddress}"
}
}
}
}
}
}

Wunderkind Sender

GET https://a.klaviyo.com/profiles/
?fields[profile]=id&filter=equals(email,"{emailaddress}")&page[size]=1
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15

Update Profile: https://developers.klaviyo.com/en/reference/update_profile 

PATCH https://a.klaviyo.com/profiles/{unique_user_id}
Accept: application/json
Content-Type: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15
{
"data": {
"attributes": {
"properties": {
"source": "wunderkind"
}
},
"id": "{unique_user_id}",
"type": "profile"
}
}

7. URL Appending

URL Appending is one of Wunderkind’s most impactful identification methods. It allows us to identify users returning to your site from marketing messages (non-WKND marketing emails). It is a reverse lookup that we're able to do using a key (unique identifier) that maps to a plaintext email address and appended to all clickout email links.

Within Klaviyo, please:

Enable UTM Tracking in account settings.
Add a new UTM Parameter:
1. UTM Parameter field name: “bxid”
2. Campaign Email Value: “Klaviyo profile id”
3. Flow Email Value: “Klaviyo profile id”
4. Make sure Automatically add UTM parameters to links is enabled
For all new and existing campaigns: The default setting is “Use Account Defaults”. Please change this to “Use Custom Value” so the newly created bxid UTM parameter is appended to the email.

API Calls for URL Appending

GET https://a.klaviyo.com/profiles/?fields[profile]=email&filter=equals(id,"{profileid")
Accept: application/json
Authorization: Klaviyo-API-Key {private_api_key}
revision: 2023-09-15

8. Confirm Dedicated Sending Domain

Klaviyo recommends that all its clients set up a dedicated sending domain in order to optimize email deliverability.

If you’ve already done this, please provide Wunderkind with your dedicated email sending domain. We will use the same email address in our sends. You can find this under Account > Settings > Domains and Hosting. Look for “Sending Domain”

If you don’t have this set up already, please do so! You can find instructions here: How to Set Up a Dedicated Sending Domain. Once completed, please let Wunderkind know your sending domain.