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.
NOTE
Push Planet offers a subscription preference center solution that's integrated with Iterable, designed for marketers and requires no software development. It can be added to your existing Iterable contract for easy billing. If you're interested, contact your customer success manager.
Table of contents
Make API calls from your server, not the browser
DANGER
The APIs that fetch and update a user's subscription preferences require authentication with a server-side API key. Since they can be used to access all of your project's data, it's never safe to embed a server-side API key in client-side code (whether JavaScript, a mobile app or otherwise). Instead, use a server-side API key to make API calls from your server. Then, use the data returned from those calls to display a web page that has no knowledge of the API key.
Instructions
1. Set up message channels and types
First, set up your project's message channels and types.
TIP
For more information about message channels and types, read Message Channels and Types Overview and Message Channels and Types Best Practices
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 prefence center should allow users to view and update their subscription preferences.
DANGER
Use your server (not client-side JavaScript) to make API calls that fetch and modify a user's subscription preferences. For more information, read Make API calls from your server, not the browser.
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.
NOTE
If your account or project has enabled opt-in message types, you can also use the following APIs to modify user subscriptions to message channels, message types and lists:
PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe
PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=unsubscribe
To enable opt-in message types, contact your Iterable customer success manager.
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.
NOTE
Your subscription preference center needs to know the email address of the
user for which it should display subscription preferences. To facilitate this, pass
an email
merge parameter in the preference center's URL, URL-encoding it with
the #urlEncode
Handlebars helper:
https://www.example.com/accounts/preferences?email={{#urlEncode}}{{email}}{{/urlEncode}}
4. Use the hostedUnsubscribeUrl merge parameter
When building an email template, use a {{hostedUnsubscribeUrl}}
merge parameter
to generate an unsubscribe link that directs users to your custom subscription
preference center.
5. Attribute unsubscribes to a specific campaign and template
If a user navigates to your email preference center through a {{hostedUnsubscribeUrl}}
link, you may want to attribute unsubscribe events back to the campaign or template
in which they clicked the link. To determine the relevant campaign and template
ID, look at one of the following things:
-
URL parameters
You can append
campaignId
and/ortemplateId
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
andtemplateId
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 wereunsubscribe.example.com
, the web server for the subscription preference center could access these cookies to get the relevantcampaignId
andtemplateId
.Iterable sets the following cookies:
iterableEndUserId
- The recipient's e-mail address. This cookie expires in one year.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 uniqueiterableMessageId
. 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 }
DANGER
Use your server (not client-side JavaScript) to make API calls that fetch and modify a user's subscription preferences. For more information, read Make API calls from your server, not the browser.
Comments
0 comments
Please sign in to leave a comment.