Message channels and message types are categories you can associate with your messages:
Message channels are broad message categories (for example, you might have a channel called "Promotional Emails"). Each message channel has a medium (such as email) and a type (either marketing or transactional).
Every message channel has one or more message types. Each message type represents a particular subset of the overall channel (for example, in the "Promotional Emails" just described, you might have a "Seasonal Sales" message type). Message types have a max send rate (so you can limit how fast Iterable sends messages of that type) and a subscription policy (opt-in, or opt-out).
BETA FEATURE
Max send rates are in beta. To access this feature, talk to your Iterable customer success manager.
Your contacts can subscribe and unsubscribe to and from message channels and message types to make sure they receive only the content they're interested in.
Table of contents
- Message channels
- Message types
- Default channels and types
- How message channels, message types, and lists work together
- Creating message channels and types
- Selecting a message type for a template
- How Iterable stores subscription information
- Viewing a user's subscriptions with Iterable's API
- Subscribing and unsubscribing
- Segmenting users and filtering journeys based on message type
Message channels
Message channels provide a high-level way to categorize the messages you send with Iterable. Message channels have:
- An ID.
- A name.
- A type (marketing or transactional).
- A medium (email, in-app push, SMS, or web push).
- ESP bindings.
- One or more message types, which you use to attach a fine-grained category for each campaign that you send.
By default, users in an Iterable project can receive messages from any of its
channels, but they can unsubscribe to individual channels as they like. For example,
a user who unsubscribes from a Push Marketing Channel
will still receive messages
from a Push Transactional Channel
from which they have not unsubscribed.
Channel types: marketing and transactional
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. Marketing messages must adhere to the CAN-SPAM Act.
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 a more fine-grained way to categorize the messages within a message channel. Message types have:
- An ID.
- A parent message channel.
- A name.
- A max send rate, which Iterable uses as the default send rate limit on new campapigns associated with this message type. You can override this setting on a campaign-by-campaign basis. (This feature is in beta; to access it, talk to your Iterable customer success manager.)
- A 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.
- No push marketing messages at all.
Every message type has an opt-in or an opt-out subscripton policy.
- To receive messages from opt-in message types, users must subscribe to those types.
- To receive messages from opt-out message types, users must not unsubscribe from those types.
IMPORTANT
To use opt-in message types or the associated new subscription-related APIs in an existing Iterable project, you must have your Iterable customer success manager 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.
Previously existing users and new message types
When you add a new message type to an Iterable project, previously existing users:
- Will receive messages from new opt-out message types until they unsubscribe.
- Will not receive messages from new opt-in message types until they subscribe.
New users and previously existing message types
When you add a new user to an Iterable project, they:
- Will receive messages from the project's opt-out message types until they unsubscribe.
- Will not receive messages from the project's opt-in message types, until they subscribe.
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:
How message channels, message types, and lists work together
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.
NOTE
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.
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.
In the Message Channels section, click 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 new channel's row and click Edit.
Set the channel's Name, and choose Marketing or Transactional.
Hover over the new 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.
-
In the Create New Message Type window that appears:
Specify a Message Type Name.
Enter a Max send rate (messages per minute). This is the default send rate limit for new campaigns associated with this message type (you can override this setting on a campaign-by-campaign basis). Leave this input blank to indicate that new campaigns associated with this message type should, by default, send as fast as possible. (Max send rate is a beta feature. To access it, talk to your Iterable Customer Success Manager.)
- 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
When you're creating a template or campaign, use the Message type drop-down menu to choose a message type to associate with it.
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 customer success manager 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 expressions generate unsubscribe links that allow users to unsubscribe from your messages, at various levels of granularity:
-
{{unsubscribeMessageTypeUrl}}
Creates a link that users can click to unsubscribe from the message type associated with the message they're reading.
TIP
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 users can click to unsubscribe from the message's associated message channel (so they will no longer receive messages from any message type associated with the message channel).
-
{{hostedUnsubscribeUrl}}
Creates a link that users can click to navigate 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 opt-in message types are enabled on an older Iterable project, there is a breaking API change. Read this section for more details, and verify that this API change will not impact you before enabling this feature.
After opt-in message types are enabled on an older Iterable project (created before
the existence of opt-in message types), 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
If you rely on these APIs, do not enable this feature.
APIs for updating subscriptions
IMPORTANT
If your Iterable project was created before the existence of opt-in message types as an Iterable feature, your customer success manager must enable opt-in message types on your project before you can use the four APIs described in this section to update subscriptions.
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
IMPORTANT
The APIs described in this section are available in all Iterable projects.
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:
-
Overwriting subscription information for multiple users:
Journeys
You can use journeys to subscribe or unsubscribe a user from an opt-in or opt-out message type. To do this:
Navigate to Messaging > Journeys and create or open a journey.
-
At the point in the journey 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 tile onto the canvas:
-
This will create an Unsubscribe from Message Type tile (which can be modified so that it subscribes rather than unsubscribes):
-
To open and configure the tile, double-click it:
The tile 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 to save it and return to the canvas.
- Click Save to save the journey, and use the toggle in the upper-left corner to enable it if necessary.
When users reach this tile in the journey, their subscription settings will be adjusted according to the configuration of the journey tile just created.
Segmenting users and filtering journeys based on message type
Iterable's segmentation and journey filter interfaces provide an Is Eligible To Receive Message Types selector that checks whether 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 journey filters, include an Unsubscribed Channels selector.
Segmenting users on message type eligibility
Use the Is Eligible To Receive Message Types selector to segment 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 returns users who are eligible to receive the Iterable Docs Opt-In Type message type (which is an opt-in message type):
To search 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 journeys based on message type eligibility
To filter a journey based on a user's message type eligibility:
-
Drag a Yes/No Split tile onto the canvas:
-
To configure the tile, double-click it. Add Is Eligible To Receive Message Types and Unsubscribed Channels (if necessary) selectors (as described above):
Comments
0 comments
Please sign in to leave a comment.