IMPORTANT
This document discusses (among other topics) opt-in message types. To use opt-in message types or the associated new subscription-related APIs in an existing Iterable project, you must have your Iterable CSM enable the feature for your project or organization. Before doing so, please read about an associated breaking API change and verify that it will not impact you.
Message channels and message types are categories to which Iterable campaigns can associate messages. Users can subscribe and unsubscribe to and from channels and types to make sure they receive only the content they're interested in.
This document describes how to work with message channels and message types in Iterable.
Table of contents
- Message channels
- Message types
- Default channels and types
- Precedence
- Creating message channels and types
- Selecting a message type for a template
- Send skip events
- How Iterable stores subscription information
- Viewing a user's subscriptions with Iterable's API
- Subscribing and unsubscribing
- Segmenting users and filtering workflows based on message type
- Further reading
Message channels
Message channels provide a high-level way to categorize the messages you send with Iterable.
A message channel has a name, an indication as to whether it is marketing or transactional, and a medium (email, in-app, push, SMS, or web push), and as many child message types as necessary.
By default, users in an Iterable project can receive messages from any of its
channels, but they can unsubscribe as necessary. For example, a user who
unsubscribes from a Push Marketing Channel
will still receive messages from a
Transactional Channel
from which they have not unsubscribed.
Marketing channels
Use marketing message channels to send marketing-related campaigns.
Messages sent from a marketing message channel must have a prominent unsubscribe block containing an unsubscribe link and your company's physical address.
Iterable prevents a single marketing channel message template from being sent to the same user more than once per 18 hours.
NOTE
Promotional emails must adhere to the CAN-SPAM Act.
Transactional channels
Use transactional message channels to send business-critical transactional messages such as order and shipping confirmations.
Since transactional messages don't carry promotional content, they do not need an unsubscribe block.
Iterable processes transactional messages separately from marketing messages.
Message types
Message types provide more of a low-level, focused way to categorize messages. Each message type belongs to a message channel and has its own name and subscription policy (opt in or opt out).
For example, an Iterable project might add Weekly Deals
and New Products
message types to its Push Marketing Channel
message channel. With this
configuration, users can choose to receive all push marketing messages, only push
marketing messages about weekly deals, only push marketing messages about new
products, or no push marketing messages at all.
Every message type has an opt-in or an opt-out subscripton policy:
- Iterable sends campaigns having opt-in message types to users who have explicitly subscribed to those types.
- Iterable sends campaigns having opt-out message types to users who have not explicitly unsubscribed from those types.
Previously existing users and new message types
Previously existing users in an Iterable project:
- Are eligible to receive messages from new opt-out message types.
- Must explicitly subscribe to new opt-in message types in order to receive their messages.
New users and previously existing message types
New users added to an Iterable project:
- Are eligible to receive messages from previously-existing opt-out message types.
- Must explicitly subscribe to previously existing opt-in message types in order to receive their messages.
Default channels and types
By default, an Iterable project has three message channels, each of which has a single message type:
- Message channel:
Push Marketing Channel
(marketing, push notifications)- Message type:
Push Marketing Message
(opt out)
- Message type:
- Message channel:
Transactional Channel
(transactional, email)- Message type:
Transactional Message
(opt out)
- Message type:
- Message channel:
Marketing Channel
(marketing, email)- Message type:
Marketing Message
(opt out)
- Message type:
Precedence
Iterable sends messages to users based on a combination of their message channel, message type, and list subscription settings.
-
If a user is subscribed to a channel:
For that channel, they will only receive messages from opt-in message types to which they have subscribed and opt-out message types from which they have not unsubscribed.
-
If a user is not subscribed to a channel:
They will not receive messages from any message type associated with that channel, regardless of their specific message type subscriptions.
-
If a user is subscribed to a list:
They will receive messages sent to that list based on their message channel and type subscription preferences, as described above.
-
If a user is not subscribed to a list:
They will receive no messages sent to that list.
Creating message channels and types
Adding channels and types to an Iterable project gives recipients the flexibility to decide which of your content they'd like to receive.
For example, if a project's Marketing Channel
message channel has a
Weekly Newsletter
message type and a Daily Deals
message type, users can
unsubscribe from daily deals while staying subscribed to the weekly
newsletter.
Creating message channels
To create a message channel:
- Navigate to Settings > Message Channels and Types.
- Click a button: Create New Email Channel, Create New In-App Channel, Create New Push Channel, Create New SMS Channel, or Create New Web Push Chanel.
- Hover over the row associated with the new channel and click Edit.
- Set the channel's Name and choose Marketing or Transactional.
- Hover over the channel's row and click Save.
Creating message types
To create an message type:
- Navigate to Settings > Message Channels and Types.
- In the Message Types section, use the drop-down menu to select the channel to which you'd like to add a new message type.
- Click Create New Message Type.
- On the Create New Message Type window that appears:
- Specify a Message Type Name.
- For Subscription Policy, select Opt In or Opt Out. The subscription policy cannot be modified after the type has been created.
Selecting a message type for a template
To choose the message type for a message:
- When creating a template, select a Message Type.
- When creating a campaign or workflow, modify the Message Type of the selected template as necessary.
Send skip events
When Iterable does not send a message to a user because of their subscription preferences, it does not create a Send Skip event in the user's event history.
How Iterable stores subscription information
Iterable uses the following user profile fields to store information about a user's subscriptions:
-
emailListIds
: Subscribed email lists -
unsubscribedChannelIds
: IDs of message channels to which the user is unsubscribed -
unsubscribedMessageTypeIds
: IDs of message types to which the user has unsubscribed -
subscribedMessageTypeIds
: IDs of message types to which the user has subscribed (this array is available only if your account or project has enabled the opt-in message types feature; please contact your CSM to do so).
When looking at a user's unsubscribedMessTypeIds
and subscribedMessageTypeIds
arrays, you may notice that they each contain opt-in and opt-out message type
IDs:
The presence of an opt-in message type ID in the
unsubscribedMessageTypeIds
array indicates that the user had opted in to the message type at one point, but then unsubscribed.The presence of an opt-out message type ID in the
subscribedMessageTypeIds
array indicates that the user had opted out of the message type at one point, but then re-subscribed.
Viewing a user's subscriptions with Iterable's API
To use Iterable's API to view a user's subscriptions, use the following endpoints:
GET /api/users/{email}
GET /api/users/getByEmail
GET /api/users/byUserId/{userId}
GET /api/users/byUserId
The responses for these APIs include the emailListIds
,
unsubscribedChannelIds
, unsubscribedMessageTypeIds
, and
subscribedMessageTypeIds
arrays only if any one of those values has been
modified for the user in question.
NOTE
For more information about Iterable's APIs, read API Overview and Sample Payloads.
For example, GET /api/users/{email}
returns data similar to the following:
{ "user": { "email": "docs@iterable.com", "dataFields": { "email": "docs@iterable.com", "unsubscribedChannelIds": [], "subscribedMessageTypeIds": [ 24201 ], "emailListIds": [], "signupDate": "2019-08-13 20:09:24 +00:00", "profileUpdatedAt": "2019-08-13 20:50:24 +00:00", "signupSource": "API", "unsubscribedMessageTypeIds": [ 25346 ], "itblInternal": { "emailDomain": "iterable.com", "documentUpdatedAt": "2019-08-13 20:50:24 +00:00", "documentCreatedAt": "2019-08-13 20:09:24 +00:00" } } } }
Subscribing and unsubscribing
There are various ways for users to subscribe and unsubscribe from a message type or channel, described below.
TIP
Consider using the APIs described in this section with a subscription preference center.
Unsubscribe links
When inserted in a message, the following Handlebars templates generate unsubscribe links that allow users to unsubscribe at various levels of granularity:
-
{{unsubscribeMessageTypeUrl}}
Creates a link that unsubscribes the user from the message's associated message type.
Since this link unsubscribes the user from a single message type, it may confuse users who are trying to unsubscribe from all marketing messages. Because of this, it is best to use a subscription preference center
to manage individual message type unsubscriptions. -
{{unsubscribeUrl}}
Creates a link that unsubscribes the user from the message's associated message channel.
-
{{hostedUnsubscribeUrl}}
Creates a link that navigates to your subscription preference center
.
For more details, see Universal Merge Parameters.
APIs
Various APIs can be used to subscribe and unsubscribe from channels, types, and messages, as described below.
Breaking API change
DANGER
When enabled for an existing Iterable account or project, the opt-in message types feature comes with a breaking API change, described in this section. Before having your CSM enable this feature, please make sure that this API change will not impact you.
After opt-in message types have been enabled for your account, you can no
longer set values for the following arrays by including them in the
dataFields
object of an API request body:
emailListIds
unsubscribedChannelIds
unsubscribedMessageTypeIds
subscribedMessageTypeIds
This change impacts all APIs that use dataFields
to update a user profile:
POST /api/users/update
POST /api/lists/subscribe
POST /api/users/bulkUpdate
POST /api/commerce/updateCart
-
POST /api/commerce/trackPurchase
:::
APIs for updating subscriptions
IMPORTANT
The APIs described in this section are only available after the opt-in message types feature has been enabled on your Iterable project or account. To do this, contact your CSM.
After the opt-in message types feature has been enabled on your account or project, you can also use the following new APIs to subscribe and unsubscribe single users or multiple users from message channels, types, and lists:
- Subscribing a user to a single channel, message type, or list:
PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
- Unsubscribing a user from a single channel, message type, or list:
DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
- Subscribing multiple users to the same channel, message type, or list:
PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe
- Unsubscribing multiple users from the same single channel, message type, or list:
PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=unsubscribe
APIs for overwriting subscriptions
NOTE
The APIs described in this section are available for all Iterable projects and accounts, regardless of whether the opt-in message types feature has been enabled.
The following APIs can be used to subscribe users to message channels, types, and lists.
However, note that message channel, message type, and list-related arrays passed to these APIs will completely overwrite the existing values for those arrays—they are not merged. Because of this, any time you use these APIs to modify one of these arrays, be sure to supply all the data it should contain. Arrays not included in the request body are not modified.
- Overwriting a single user's channel, message type, or list subscriptions:
POST /api/users/updateSubscriptions
- Overwriting subscription information for multiple users:
POST /api/users/bulkUpdateSubscriptions
Workflows
Workflows can be used to subscribe or unsubscribe a user from an opt-in or opt-out message type.
To manage message type, channel, or list subscriptions with an Iterable workflow:
Navigate to Messaging > Workflows and create or open a workflow.
-
At the point in the workflow at which you'd like to modify a user's subscription settings for a message channel, message type, or email list, drag a Modify Message Type node onto the workflow canvas:
-
This will create an Unsubscribe from Message Type node (which can be modified so that it subscribes rather than unsubscribes):
-
Double-click the node to configure it:
The node can be used to modify a channel subscription, a message type subscription, or add/remove a user from a list, depending on how you configure it. This example will update a user's message type subscription:
- Using the top drop-down menu, select Modify Message Type Subscription.
- Select Subscribe User To or Unsubscribe User From, as necessary.
- From the Select a Message Type drop-down menu, select a message type.
- Click Update Node to save it and return to the workflow canvas.
- Click Save to save the workflow, and use the toggle in the upper-left corner to enable it if necessary.
When users reach this node in the workflow, their subscription settings will be adjusted according to the configuration of the workflow node just created.
Segmenting users and filtering workflows based on message type
Iterable's segmentation and workflow filter interfaces provide a new Is Eligible To Receive Message Types selector that determines if a user is eligible to receive a particular message type (has opted in to an opt-in message type or hasn't opted out of an opt-out message type).
IMPORTANT
- The Is Eligible To Receive Message Type selector replaces the previously existing Unsubscribed Message Types selector. The new selector is backwards-compatible with the old one and does not require any manual changes.
- The Is Eligible To Receive Message Type selector evaluates whether a user is eligible to receive a specific message type, but it doesn't consider whether or not that user has unsubscribed from the channel associated with the message type.
- If a user is eligible to receive a particular message type (has opted in or hasn't opted out, depending on the message type), but has unsubscribed from the channel associated with that type, they will not receive its messages.
- To account for channel unsubscriptions in segmentation or workflow filters, include an Unsubscribed Channels selector.
Segmenting users on message type eligibility
Use the Is Eligible To Receive Message Types selector to segment on users who are (or are not) eligible to receive a particular message type, based on their subscription preferences.
For opt-in message types, this selector returns users who have opted in; for opt-out message types, it returns users who have not opted out.
For example, the following example segments on users who are eligible to receive the Iterable Docs Opt-In Type message type (which is an opt-in message type):
To search instead for users who are not eligible to receive this type, use the drop-down menu to change Equals to Does Not Equal.
Accounting for unsubscribed channels
To account for unsubscribed channels in a message type segmentation query, add an Unsubscribed Channels selector.
For example, the following query segments on users that are opted in to the Iterable Docs Opt-In Type and have not unsubscribed from its channel, Marketing Channel:
Filtering workflows on message type eligibility
To filter a workflow based on a user's message type eligibility:
-
Drag a Fields Match filter node on to the workflow canvas:
-
This creates a Matches Query node:
Double-click the node to configure it, adding Is Eligible To Receive Message Types and Unsubscribed Channels (if necessary) selectors, as described in the previous section.
Comments
0 comments
Please sign in to leave a comment.