Message channels and message types categorize messages so that users can subscribe and unsubscribe to receive the content they prefer.
Message channels combine a message medium (email, push notification, SMS, web push, or in-app message) with a marketing or transactional designation. Every message channel has one or more message types.
Message types specialize message channels, providing users with fine-grained control over which specific messages in a category they want to receive: weekly newsletter, daily deals, etc. Message types have a subscription policy (opt-in, opt-out, or double opt-in for SMS), and can also have a max send rate (so you can limit how fast Iterable sends messages of that type).
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.
# In this article
# Overview
# Message channels
Message channels, also called subscription channels or just channels, offer a high-level way to categorize the messages you send with Iterable.
Message channels have:
- An ID.
- A name.
- A channel type (marketing or transactional).
- A medium (email, in-app, push, SMS, or web push).
- One or more associated sending platforms (email channels only).
- One or more message type (useful for categorizing campaign messages).
By default, an Iterable project opts-in users to all channels. This
means they can receive messages from any channel, but can unsubscribe to
individual channels as they like. For example, a user who unsubscribes from a
Push Marketing Channel
still receives messages from a
Push Transactional Channel
from which they haven't unsubscribed.
# Channel types: marketing and transactional
Use marketing message channels to send marketing-related campaigns. Marketing messages must adhere to the CAN-SPAM Act. 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 certain marketing channel message template from sending to the same user more than once every 18 hours.
Use transactional message channels to send business-related messages such as order receipts and shipping confirmations. Since transactional messages don't carry promotional content, they don't need an unsubscribe block.
Iterable processes transactional messages separate from marketing messages.
# Message types
Message types are categories of messages within a message channel.
Message types have:
- An ID.
- A name.
- A parent message channel.
- A subscription policy (opt-in, opt-out, or double opt-in for SMS).
- To receive messages from opt-in message types, users must actively subscribe to those types before they receive that content.
- Users receive messages from opt-out message types by default, and must unsubscribe if they don't want those communications.
- A double opt-in message type requires users to confirm their
subscription by replying to a SMS confirmation.
- An override to ignore frequency caps (optional).
- A max send rate (beta), which Iterable uses as the default send rate limit on new campaigns associated with this message type. You can override this setting on a campaign-by-campaign basis. (For access to this beta feature, talk to your Iterable customer success manager.)
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.
IMPORTANT
To use opt-in message types or the associated Subscription APIs in an existing Iterable project, ask your Iterable customer success manager to enable the feature for your project or organization. Before doing so, please read about an associated breaking API change and review for impacts to your implementation.
# Existing users and new message types
When you add a new message type to an Iterable project, your existing users:
- Receive messages from new opt-out message types until they unsubscribe.
- Don't receive messages from new opt-in message types until they subscribe.
- Don't receive messages from new double opt-in message types until they confirm their subscription (SMS only).
# New users and existing message types
When you add a new user to an Iterable project, they:
- Receive messages from the project's opt-out message types until they unsubscribe.
- Don't receive messages from the project's opt-in message types until they subscribe.
- Don't receive messages from the project's double opt-in message types until they confirm their subscription (SMS only).
# 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 subscribes to a channel:
For that channel, they only receive messages from opt-in message types to which they've subscribed and opt-out message types from which they haven't unsubscribed.
-
If a user isn't subscribed to a channel:
They don't receive messages from any message type associated with that channel, regardless of their specific message type subscriptions.
-
If a user subscribes to a list:
They can receive messages sent to that list, and messages send based on their subscription preferences as they relate to the message channel and message type selected for each campaign.
-
If a user isn't subscribed to a list:
They don't receive any messages sent to that list.
# Example
The image below shows a Marketing Channel
with three message types:
Newsletters
, Product Suggestions
, and Promotional
(as viewed on the
Settings > Message Channels and Types screen):
- Unsubscribing users from the
Marketing Channel
prevents them from receiving emails fromNewsletters
,Product Suggestions
, orPromotional
emails. - Subscribing users to the
Marketing Channel
but unsubscribing them fromNewsletters
andProduct Suggestions
means they only receivePromotional
emails.
NOTE
When Iterable doesn't send a message to a user because of their subscription preferences, it doesn't create a send skip event in the user's event history.
# 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:
# Create message channels
To create a message channel:
- Go to Settings > Message Channels and Types.
- In the left hand menu, choose the message medium for the new channel (email, in-app, push, SMS, web push).
- Click New Subscription Channel.
- Enter details for your new channel:
- Name - For display in Iterable
- Type - Marketing or Transactional (you can't change this later)
- Save the new message channel by clicking Create Channel.
# Select email platforms for your channels
New email channels are automatically set to send from the default sending platform for your project.
You can have more than one email sending platform in your Iterable project. If you do, you're able to choose the platform(s) you want to use for each message channel.
You may want to use a different account for transactional vs marketing messages, for example, to isolate deliverability problems.
You can customize your email sending platforms by channel in two ways:
To send messages from all email channels using the same account, set a default email sending platform to the account you wish to use.
To send messages from different sending platforms depending on the channel for the message, update each channel's settings to use one or more of your available sending platforms. You can also split a message channel to send messages through more than one email sending platform.
# Update a project's default email sending platform
When you change the default sending platform for your project, all message channels that use the default account update to use the new default.
To change the default sending platform for your project:
- Go to Settings > Sending Platforms.
- Select the sending platform you wish to update.
- Click on the overflow menu, and choose Use as Default Account.
# Iterable Shared Pool
For a new Iterable project, the default sending platform is Iterable's Shared Pool (sending from a group of shared IPs by Amazon SES).
You can't choose Iterable Shared Pool as a default sending platform. It's used as a fallback email sending platform when you haven't selected a default.
# Update a message channel's email sending platform
You can update the sending platforms for a channel at any time. To do this:
Go to Settings > Message Channels and Types.
Find the email channel you wish to update.
Click the overflow menu (three dots) and select Edit Subscription Channel
-
Under Sending Platforms, use the radio buttons to select your default account or another third-party account.
To send from multiple accounts, select Add New Binding and distribute the percentage for each platform. This determines how many emails a given platform sends per campaign. Make sure that your percentages add up to 100%, or you won't be able to save.
# Create message types
For each of your message channels, you can add message types as needed. Each channel needs at least one message type. This enables you to assign the channel and message type to campaigns.
To create a message type:
- Go to Settings > Message Channels and Types.
- In the left hand menu, select the message medium for the new message type (email, SMS, push, in-app, web push).
- Below the message channel you're creating a type for, click Add Message Type.
- In the Create Message Type window that appears:
- Specify a Name.
- For Subscription Policy, select Opt-In or Opt-Out. For SMS, you can also select the Double Opt-In policy. To learn more, read SMS Double Opt-In. You can't change a message type's subscription policy later, so make sure you're selecting the right option.
- Click Save Changes
# Ignore frequency caps for a message type
Marketing messages may be subject to sending limits based on your project's Frequency Management settings.
You can set a marketing message type to ignore the frequency cap. When ignored, campaigns with this message type skip Frequency Management rules. Campaigns sent from this message type also do not count towards frequency cap limits.
Frequency Management doesn't apply to transactional message types.
To learn more, read Frequency Management.
# Select a template's message type
When you're creating a template or campaign, use the Message type dropdown menu to choose a message type to associate with it.
# Subscribes and unsubscribes
There are various ways for users to subscribe and unsubscribe from a message type or channel. This section reviews what information Iterable stores, how to view it, and how to update it.
TIP
Consider using the APIs described in this section with a subscription preference center.
# How Iterable stores subscription information
Iterable uses the following user profile fields to store information about a user's subscriptions:
emailListIds
: Static lists of subscribed users, used by email-based projectsuserListIds
: Static lists of subscribed users, used by userID-based and
hybrid projectsunsubscribedChannelIds
: IDs of message channels from which the user unsubscribedunsubscribedMessageTypeIds
: IDs of message types from which the user unsubscribedsubscribedMessageTypeIds
: 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 unsubscribedMessageTypeIds
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.
# View 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
or userListIds
,
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": "user@example.com", "dataFields": { "email": "user@example.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" } } } }
# Create 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's best to use a subscription preference center to manage individual message type unsubscribes.
{{unsubscribeUrl}}
Creates a link that users can click to unsubscribe from the message's associated message channel. Users don't receive any message types associated with the message channel from which they've unsubscribed.
{{hostedUnsubscribeUrl}}
Creates a link that users can click to navigate to your subscription preference center.
For more details, see Universal Merge Parameters.
# Subscribe or unsubscribe via APIs
Various APIs can subscribe and unsubscribe users.
# APIs for updating subscriptions
IMPORTANT
If your Iterable project was created before opt-in message type was released as an Iterable feature (September 2019), 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. It's important to know that this update contains a breaking change.
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
-
Triggering a double opt-in confirmation message for a user (SMS only):
# APIs for overwriting subscriptions
IMPORTANT
The APIs described in this section are available in all Iterable projects.
You can use the following APIs 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're 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 aren't modified.
-
Overwriting a single user's channel, message type, or list subscriptions:
-
Overwriting subscription information for multiple users:
# 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
oruserListIds
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, don't enable this feature.
# Manage subscriptions with journeys
There are two journey tiles you can use to update a user's subscription preferences: Subscription Preferences and List Membership.
When a user enters one of these tiles, their preferences update according to the tile's settings.
Note that the double opt-in message type is not supported by these tiles.
# Subscription preferences journey tile
This tile can subscribe or unsubscribe a user from a message channel or type, as selected. To learn more about how to use this tile, see Parts of a Journey.
# List membership journey tile
A list membership tile adds or removes users from static lists. To learn how this tile works, see Parts of a Journey.
# SMS unsubscribes
The SMS channel works a bit differently for unsubscribing and re-subscribing than other marketing channels. To learn more about unsubscribing and resubscribing via SMS, read SMS Unsubscribes and Resubscribes.
You can also customize opt-out management for SMS using message types. To find out how, read Managing SMS Opt-Outs by Message Type.
# Segment users and filter journeys based on message type
Iterable's segmentation and journey filters have 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 doesn't 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 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 don't receive its messages.
- To account for channel unsubscribes in segmentation or journey filters, include an Unsubscribed Channels selector.
# Segment users on message type eligibility
Use the Is Eligible To Receive Message Types selector to segment users who are (or aren't) 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 haven't 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 aren't eligible to receive this type, use the drop-down menu to change Equals to Does Not Equal.
# Account 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 have opted in to the Iterable Docs Opt-In Type and haven't unsubscribed from its channel, Marketing Channel:
# Filter journeys based on message type eligibility
To filter a journey based on a user's message type eligibility:
Add 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:
# Want to learn more?
For more information about some of the topics in this article, check out this Iterable Academy course. Iterable Academy is open to everyone — you don't need to be an Iterable customer!