Creating a Subscription Preference Center

To help your contacts manage their subscription preferences, you can build a custom subscription preference center and link to it from messages sent from Iterable. This guide describes how to use Iterable's API to integrate a custom subscription preference center.

# Table of contents

# Make API calls from your server, not the browser

# Instructions

# 1. Set up message channels and types

First, set up your project's message channels and types.

Generally, contacts should only manage subscription preferences related to marketing messages, since they'll need to receive all transactional messages (password resets, accounts updates, etc.).

It's common to set up a single marketing channel per message medium (email, push, SMS, etc.) and specific message types within each of those channels.

For example, this screenshot shows an example subscription preference center that allows contacts to manage their subscriptions for various types of marketing emails:

# 2. Build a subscription preference center

A subscription preference center should allow users to view and update their subscription preferences.

# 2.1 Displaying a user's subscription preferences

When rendering a subscription preference center, your web server should populate the screen with data about a specific user's subscription preferences. To determine which user's data to display, use a URL parameter (as described below).

Your web server can retrieve the user's current subscription preferences by calling Iterable's GET /api/users/{email} API.

For example, consider the following subscription preferences:

To represent this data, the response from GET /api/users/{email} might look similar to the following:

{
  "user": {
    "email": "user@example.com",
    "dataFields": {
      "emailListIds": [5, 6, 7],
      "unsubscribedMessageTypeIds": [1, 2]
    }
  }
}

This data indicates that the user is unsubscribed from message types 1 and 2, which in this example correspond to Daily Promotional and Weekly Promotional marketing emails.

# 2.2 Updating a user's subscription preferences

The above user might update their subscription preferences as follows:

When the user submits these updates, your web server should pass them to the POST /api/users/updateSubscriptions API, with a request body similar to the following:

{
  "email": "user@example.com",
  "unsubscribedMessageTypeIds": [2, 4]
}

In this example, if the user selected Unsubscribe Me From All Marketing Emails, the request body might instead look something like this

{
  "email": "user@example.com",
  "unsubscribedChannelIds": [100],
  "unsubscribedMessageTypeIds": [1, 2, 3, 4, 5]
}

This request body unsubscribes the user from the channel and the individual message types.

# 3. Configure your project's hosted unsubscribe URL

Once your subscription preference center is ready, provide its URL to Iterable by navigating to Settings > Project Settings and entering it in the Hosted Unsubscribe URL input.

https://www.example.com/accounts/preferences?email={{#urlEncode}}{{email}}{{/urlEncode}}

# 4. Use the hostedUnsubscribeUrl merge parameter

# 5. Attribute unsubscribes to a specific campaign and template

• URL parameters

  You can append campaignId and/or templateId query parameters to your hosted preference center URL (on the Settings > Project Settings screen), and use these parameters to determine the campaign and template to associate with the unsubscribe event.

  For example, your preference center's URL might be something like:

  https://www.example.com/accounts/preferences?email={{#urlEncode}}{{email}}{{/urlEncode}}&campaignId={{campaignId}}&templateId={{templateId}}
  

  Your server can then access campaignId and templateId as needed.

• Cookies

  When a user clicks a link in an email sent by an Iterable campaign, Iterable sets browser cookies for your project's link tracking domain. These cookies describe who clicked the link and the associated campaign and template IDs.

  If your hosted subscription preference center shares a root domain with your Iterable project's link tracking domain, it can use the values stored in these cookies to find the campaign and template to associate with the unsubscribe.

  For example, if a project's link tracking domain were links.example.com and its subscription preference center URL were unsubscribe.example.com, the web server for the subscription preference center could access these cookies to get the relevant campaignId and templateId.

  Iterable sets the following cookies:

  • iterableEndUserId - The recipient's e-mail address. This cookie expires in one year.

    NOTE

    This cookie is only created for email-based projects and will be deprecated in a future release. We recommend passing parameters in the URL using Handlebars to identify users instead of relying on this cookie. Read Project Types and Unique Identifiers to learn more.

  • iterableEmailCampaignId - The unique ID associated with the email's Iterable campaign. This cookie expires in 24 hours.

  • iterableTemplateId - The unique ID associated with the email's Iterable template. This cookie expires in 24 hours.

  • iterableMessageId - A unique ID associated with a specific send of a specific campaign to a specific user. If the same user ever receives the same campaign more than once, each message will have a unique iterableMessageId. This cookie expires in 24 hours.

Once you have the campaignId and/or templateId, your web server should include them in its call to POST /api/users/updateSubscriptions. For example, the request body might look similar to this:

{
  "email": "user@example.com",
  "unsubscribedChannelIds": [100],
  "unsubscribedMessageTypeIds": [1, 2, 3, 4, 5],
  "campaignId": 123,
  "templateId": 456
}