Skip to main content

Iterable Integration Guide

Updated

How Wunderkind Integrates With Iterable

The Iterable 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 Iterable, and more.

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

Table of Contents:

  1. Authentication
  2. Writing New Subscribers
  3. Checking Customer Status
  4. Checking Mailability
  5. Updating Unsubscribe Status
  6. Sender Options
  7. URL Appending
  8. Important Callouts

1. Authentication

We use a Private API key to authenticate our calls to Iterable.

Requirements

  • Your Private API Key is used in the header of our API calls, as well as in the URL path.
  • The base endpoint URL is https://api.iterable.com:443

 

2. Writing New Subscribers

Upon email submission, Wunderkind will write new subscribers to Iterable through the API call below. We can write new subscribers in the following ways:

  • Adding a new subscriber to a list requires a list ID. We can not add subscribers “globally.”
  • Optionally, we may include additional properties (eg “name”, “campaignName”, “userId”).
  • Optionally, we may pass a phone number instead of an email address. We may pass email address and phone number if they’re captured on the same campaign step.
  • Wunderkind will perform a duplicate check to ensure we are not attempting to create a record for an already-existing subscriber. 
    • We’ll make a global check to determine whether the user already exists in Iterable. For any users who are re-subscribing, we can remove the user from specific unsubscribedChannelIds

API Call for Writing New Subscribers

Request
POST /api/lists/subscribe?api_key={api_key}
Host: https://api.iterable.com:443
Authorization: Api_Key: {api_key}

Sample Body - Email Address with userId
{
   "listId": {list_id},
   "subscribers": [{
       "email": "iterabletest@blackhole.ibx2.net",
“userId”: “{hashed_email}”
   }]
}


Sample Body - Phone Number
{
   "listId": {list_id},
   "subscribers": [{
       "email": "2025554343@placeholder.email",
“dataFields”: {
“phoneNumber”:”2025554343”
}
   }]
}

 

3. Checking Customer Status

Wunderkind can make a GET request to Iterable to determine if a user is a Customer vs. a Prospect.

  • To identify customers, we check for the existence of ListMemberCriteria or DataFieldNames such as “order_count” or “has_active_subscription”. 
  • Please let us know what we should reference in Iterable. DataFieldNames and their associated values are going to be unique for each client. 

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

 

API Calls for Checking Customer Status

Request
GET //api/users/getByEmail?email={emailAddress}
HTTP/1.1
Host: https://api.iterable.com
Authorization: Api_Key: {api_key}

Sample Response Body:
{}

Sample Response Code:
200

Sample Wunderkind Logic:
{
   "EspName": "iterable",
   "EspCredsId": "1234/iterable",
   "EspExtraFields": {
     "Iterable": {
       "ListMemberCriteria": [
              {
               "DataFieldName": "has_active_subscription",
               "Type": "bool",
               "Presence": "true",
               "Comparison": "=",
               "CompareTo": "true"
              }
           ]
     }
   }
}

 

4. Checking Mailability

Wunderkind will evaluable mailable status based on several attributes in dataFields of the API user response JSON. We can check for an opted-in or opted-out user.

We can use comparison checks from the Iterable user response to compare a users dataFields values to those needed to determine unsubscribe status. We can check if the user is on an array of lists by checking unsubscribedChannelIds or we may check specific keys like accepts_marketing = false.

 

API Call for Checking Mailability

{
   "user": {
     "email": "wkndtest101@blackhole.ibx2.net",
     "userId": "b5e4bae962d849f2abf080c79d206e46",
     "dataFields": {
       "email": "wkndtest101@blackhole.ibx2.net",
       "signupSource": "ListAPI",
       "signupDate": "2024-02-21 13:23:21 +00:00",
       "profileUpdatedAt": "2024-02-21 13:25:19 +00:00",
       "utm_campaign": "search_us_brand_core_exact",
       "utm_source": "google",
       "utm_medium": "cpc",
       "userId": "b5e4bae962d849f2abf080c79d206e46",
       "emailListIds": [
          {list_id}
       ],
       "unsubscribedChannelIds": [12345],
       "unsubscribedMessageTypeIds": [],
       "subscribedMessageTypeIds": [],
       "itblInternal": {
          "documentCreatedAt": "2024-02-21 13:23:21 +00:00",
          "emailDomain": "ibx2.net",
          "documentUpdatedAt": "2024-02-21 13:25:19 +00:00"
       },
       "ip": "104.28.55.555",
       "page": {
...

 

5. Updating Unsubscribe Status

Our preferred API to use to update unsubscribe status is /lists/subscribe. This API will subscribe a user to a list and allow for the update of a user’s dataFields. Wunderkind will leverage this API to subscribe a user to a list that has workflow in place to unsubscribe a user from the appropriate channel (unsubscribedChannelIds). 

Client Requirements

  • Create a list called “Wunderkind Unsubscribes”. Then, set up a journey that takes anyone from the “Wunderkind Unsubscribes” list and unsubscribes them from the appropriate Marketing Channel. Please provide Wunderkind with the list_id for “Wunderkind Unsubscribes.”

If you would like to link to a client-hosted preference center instead, we support linking to a static URL only. This means that the user would be required to input their email address on the page before updating their email preferences. Wunderkind is not able to track unsubscribe metrics with this approach. Because of this, we recommend using the Iterable API to update mailability. 

 

API Call for Unsubscribing Users

Request
POST /api/lists/subscribe
Host: https://api.iterable.com
Authorization: Api_Key: {api_key}

Body
{
  "listId": {list_id},
  "subscribers": [
    {
      "email": "iterabletest@blackhole.ibx2.net",
      "userId": "{hashed_email}"
    }
],
"campaignId": 0,
"channelUnsubscribe": true
}

 

6. Sender Options

 

Wunderkind Sender

Wunderkind will deploy triggered emails on your behalf through our own ESP. 

Iterable Client Sender

With a Client Sender Integration, Wunderkind will pass a fully-rendered email to Iterable for deployment, through the /email/target API. We do this by building Triggered Email campaigns in Iterable, through which each Wunderkind campaign will deploy out of. If we send to a user that does not already exist in Iterable, a contact will be created in Iterable upon email send.

Note that we do not support Iterable’s dynamic scripting language, Handlebars. This means that our emails cannot leverage additional dynamic content hosted by Iterable.

 

API Call for Client Sender

Request
POST /api/email/target
Host: https://api.iterable.com:443
Authorization: Api_Key: {api_key}


Body
{
"campaignId": {campaign_id},
"recipientEmail": "iterabletest@blackhole.ibx2.net",
"recipientUserId": "{hashed_email}",
"dataFields": {},
"sendAt": "string",
"allowRepeatMarketingSends": true,
"metadata": {}
}

 

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.

We do this by looking up the Iterable userId and ask that this be appended to all marketing email links. Iterable’s system does not generate a userId for all contacts by default, so clients must ensure that a userId value is set for all contacts. It should be a unique, PII safe identifier for that user (eg, you may elect to set email sha256 hash as the userId). This can be done either via API call to bulk update, or through a file upload.

 

API Call for URL Appending

Request
GET /api/users/byUserId/{hashed_email}?api_key={api_key}
Host: https://api.iterable.com:443
Authorization: Api_Key: {api_key}

Body
{
  "user": {
     "email": "wkndtest101@blackhole.ibx2.net",
     "userId": "b5e4bae962d849f2abf080c79d206e46",
     "dataFields": {
     "email": "wkndtest101@blackhole.ibx2.net",
     "signupSource": "ListAPI",
     "signupDate": "2024-02-21 13:23:21 +00:00",
     "profileUpdatedAt": "2024-02-21 13:25:19 +00:00",
     "utm_campaign": "search_us_brand_core_exact",
     "utm_source": "google",
     "utm_medium": "cpc",
     "userId": "b5e4bae962d849f2abf080c79d206e46",
     "emailListIds": [
        {list_id}
     ],
     "unsubscribedChannelIds": [],
     "unsubscribedMessageTypeIds": [],
     "subscribedMessageTypeIds": [],
     "itblInternal": {
       "documentCreatedAt": "2024-02-21 13:23:21 +00:00",
       "emailDomain": "ibx2.net",
       "documentUpdatedAt": "2024-02-21 13:25:19 +00:00"
     },
     "ip": "104.28.55.555",
     "page": {
...

 

8. Important Callouts

  • Our integration requires an {api_key} in order to make API requests (see: Authentication)
  • Our integration requires a {list_id} for some requests. Some of our member checks / updates are list-specific.
  • We have the option to pass phone numbers instead of email addresses (see: Writing New Subscribers)
  • Clients must set up a workflow in Iterable to process Wunderkind unsubscribes (see: Updating Unsubscribe Status)
  • Please ensure that all emails have a unique userId (see: URL Appending)

 

Related articles

Powered by Zendesk