Skip to main content

Listrak Integration Guide

Updated

How Wunderkind Integrates With Listrak

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

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

Table of Contents:

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

1. Authentication

For Listrak, authentication is accomplished by using OAuth 2.0. An access token may be requested by making a POST request to the token endpoint https://auth.listrak.com/OAuth2/Token.

Once an access token has been obtained, the token can be included with all API requests using the Bearer scheme.

Requirements

  • We need an encoded Public key that is an identifier for the application
  • We need an encoded Private key that is a confidential identifier used for authentication
  • Parameter grant_type needs to be set to client_credentials
  • Content-Type in header needs to be set to application/x-www-form-urlencoded
  • Wunderkind IP Addresses need to be allowed for the Listrak application. See this page for Wunderkind IPs.

2. Writing New Subscribers

Email

New subscribers via email submission will be added to Listrak by making a POST request call to https://api.listrak.com/email/v1/List/{list_id}/Contact?eventIds={event_ids}&updateType={update_type}. 

We need the following information to write new subscribers to Listrak:

  • List ID where users will be written to in Listrak
  • Comma-separated list of event identifiers that should be raised after a user has been created or updated
  • (Optional) Field IDs for additional properties to be updated when writing/updating subscriber
    • ID can be found in Support > API > API ID Information in the Listrak UI
    • Additional properties will be sent in the API request body under segmentationFieldValues
  • Update Types: Update, Append, Overwrite
    • Will default to Update if no type is specified 

Before creating/updating a user in Listrak, Wunderkind will perform a duplicate check to ensure we are not attempting to create a record for an already-existing subscriber. This is done by making a GET request to https://api.listrak.com/email/v1/List/{list_id}/Contact/{email}. 

  • If the API response has a 200 HTTP status code and Subscribed is the value for the subscripionState field, then we will reject the email submission.
  • If the API response has a 200 HTTP status code and Subscribed is NOT the value for the subscripionState field, then we will re-subscribe the user if requested. 

Upon email submission, Wunderkind will use the API calls below to write new users to a Listrak list.

API Call for Access Token

Request
POST /OAuth2/Token HTTP/1.1
Host: https://auth.listrak.com
Content-Type: application/x-www-form-urlencoded

grant_type: client_credentials
client_id: {Public key}
client_secret: {Private key}


API Call for Writing New Subscribers
Request
POST /email/v1/List/{list_id}/Contact/ HTTP/1.1
Host: https://api.listrak.com/
Content-Type: application/json
Authorization: Bearer {token}


Body
{
   "emailAddress": "wkndtest@wunderkind.co",
   “segmentationFieldValues”: [{
“segmentationFieldId”: 0,
“value”; “string”
   }]
}

API Call for Duplicate Check
Request
GET /email/v1/List/{list_id}/Contact/{email} HTTP/1.1
Host: https://api.listrak.com/
Authorization: Bearer {token}

 

SMS

New subscribers via phone number submission may be added to Listrak by making a POST request call to https://api.listrak.com/sms/v1/ShortCode/{short_code}/PhoneList/{phone_list_id}/Contact}. 

We need the following information to write phone numbers to Listrak:

  • Short Code ID
  • Phone List ID
  • (Optional) Field IDs for additional properties used for user identification (e.g. first name, last name)
  • (Optional) Field IDs for additional properties to be used for segmentation
    • ID can be found in Support > API > API ID Information in the Listrak UI
    • These properties will be sent in the API request body under segmentationFieldValue

A duplicate check is done by making a GET request to: https://api.listrak.com/sms/v1/ShortCode/{short_code}/Contact/{phone_number}. 

  • If the API response has a 200 or 201 HTTP status code and unsubscribeDate is not available, then we will reject the phone submission.
  • If the API response has a 200 or 201 HTTP status code and unsubscribeDate IS available, then we will re-subscribe the user if requested. 

Upon phone submission, Wunderkind will use the API calls below to write new users to a Listrak list.

Wunderkind has the ability to capture email only, phone number only, email + phone number on the same campaign step, or email + phone number on different campaign steps.

 

API Call for Phone Number Subscription

Request
POST /sms/v1/ShortCode/ShortCode/{short_code}/PhoneList/{phone_list_id}/Contact  HTTP/1.1
Host: https://api.listrak.com/
Content-Type: application/json
Authorization: Bearer {token}

Body
{
   "phoneNumber": "11231231234",
   “segmentationFieldValues”: [{
“segmentationFieldId”: 0,
“value”; “string”
   }]
}
API Call for Duplicate Check
Request
GET /sms/v1/ShortCode/ShortCode/{short_code}/Contact/{phone_number} HTTP/1.1
Host: https://api.listrak.com/
Authorization: Bearer {token}

 

3. Checking Customer Status

To determine if a user is a customer or prospect, we rely on the Segmentation Field Customer Flag under the Segmentation Field Group FA Customer Metrics. We will need the information below to be able to check for a user’s customer status.

  • List ID where users will be written to in Listrak
  • Segmentation Field Group Name which is the group where we can find the main field we are checking. In most cases, we are checking Field Group FA Customer Metrics

Segmentation Field Value which is the field we are checking for customer status. In most cases, this is Customer Flag, which can be found under group FA Customer Metrics

 

API Calls for Retrieving Field Group ID

Request
GET /email/v1/List/{list_id}/SegmentationFieldGroup HTTP/1.1
Host: https://api.listrak.com/
Authorization: Bearer {token}

API Calls for Retrieving Field Id
Request
GET /email/v1/List/{list_id}/SegmentationFieldGroup/{fa_customer_metrics_group_id}/SegmentationField HTTP/1.1
Host: https://api.listrak.com/
Authorization: Bearer {token}

API Calls for Checking Customer Status
Request
GET /email/v1/List/{list_id}/Contact/{email}?segmentationFieldIds={customer_flag_field_id} HTTP/1.1
Host: https://api.listrak.com/
Authorization: Bearer {token}

 

4. Checking Mailability

We can check for a user’s mailable status by using the same API call that we use for duplicate check during email submission. To make this API request, we need the following information.

  • List ID where email can be found

Subscription Status Check 

Within a user’s profile, we can check the value of a user’s ‘subscriptionState’ property

  • If a user’s profile returns as "subscriptionState": "Unsubscribed", we consider them NOT mailable
  • If a user’s profile returns as "subscriptionState": "Subscribed", we consider them mailable
  • If the user does not exist in Listrak, we will receive a 404 Not Found HTTP status code
    • If we are doing a whitelist check, then users not found in Listrak will be deemed as NOT mailable.

API Call for Checking Mailability

Request
GET /email/v1/List/{list_id}/Contact/{email} HTTP/1.1
Host: https://api.listrak.com/
Authorization: Bearer {token}

 

5. Updating Unsubscribe Status

To mark a user as not mailable, we will use the same API call as the one previously used to create a new user. For this API call, we will need the following. 

  • List ID where email can be found

The field “subscriptionState” will be updated to “Unsubscribed” to signify that the user is not mailable. When making this update, no other segmentation field can be updated at the same time.  

If a user does not exist in Listrak when unsubscribing, a new contact will be created with “subscriptionState” set to ”Subscribed”. The new contact will subsequently be updated to “Unsubscribed”. 

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 Listrak API to update mailability.

 

API Call for Unsubscribing Users


Request
POST /email/v1/List/{list_id}/Contact/ HTTP/1.1
Host: https://api.listrak.com/
Content-Type: application/json
Authorization: Bearer {token}

Body
{
"emailAddress": "wkndtest@wunderkind.co",
“subscriptionState”: “Unsubscribed”
}

 

6. Sender Options

 

Wunderkind Sender

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

If Wunderkind sends to a user that does not exist in Listrak, a new user will be created upon send. The API call to create a new user with the email field can be found in section 2. 

Wunderkind has the ability to add email engagement information to Listrak in real time. After emailing a user, we will update the user with specified segmentation field values. If a user did not previously exist, they will be created with the segmentation fields. The most common request we receive is to update user timestamp, but additional fields can be updated as well. 

We need the following if an additional segmentation field is required.

  • List ID where users will be written to in Listrak
  • Field ID for segmentation field
    • ID can be found in Support > API > API ID Information in the Listrak UI

For updates to the timestamp, the value will be in UTC time.

 

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.

The API call to retrieve the email associated to a specific key is the same as the API call for the duplicate check done in Section 2. Instead of checking for an email address, we will check for the unique key (emailKey field) in the API endpoint as shown below.

If a record was found for the unique key, then a 200 HTTP status code will be returned along with the associated “emailAddress” field in the API response.

We need to ensure that all non-WKND marketing emails append the “emailKey” value to all emails. To do this: 

  • Navigate to the Web Analytics Integration section under List Settings
  • Toggle the option to "Yes" for Enable Custom URL Variables
  • Enter bxid for the URL key and #listrak\emailKey# for the Value.
    • You can enter your URL Key and Value on the List Settings Page or when creating a new message. The key is the name of the parameter in the message being sent and the value is what the key will equal. The value can be text or numerical.

API Call for URL Appending

Request
GET /email/v1/List/{list_id}/Contact/{key} HTTP/1.1
Host: https://api.listrak.com/
Authorization: Bearer {token}

 

8. Important Callouts

  • Field IDs are needed instead of field names when writing new subscribers to Listrak (see: Section 2 - Writing New Subscribers)
  • If a user does not exist in Listrak and we are doing an opt-in check, then they are deemed as NOT mailable (see: Section 3 - Checking Mailability)
  • If a user does not exist in the ESP when unsubscribing or updating an email after a send, we will create a new user within Listrak and then will subsequently be updated to “Unsubscribed” if needed.

 

Related articles

Powered by Zendesk