Message Channels and Message Types Overview

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 channels enable coarse-grained categorization for messages sent by 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.

# 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 fine-grained categorization for messages sent by Iterable.

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 channel: Transactional Channel (transactional, email)
  • Message type: Transactional Message (opt out)
• Message channel: Marketing Channel (marketing, email)
  • Message type: Marketing Message (opt out)

# 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:

1. Navigate to Settings > Message Channels and Types.
2. 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.
3. Hover over the row associated with the new channel and click Edit.
4. Set the channel's Name and choose Marketing or Transactional.
5. Hover over the channel's row and click Save.

# Creating message types

To create an message type:

1. Navigate to Settings > Message Channels and Types.
2. 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.
3. Click Create New Message Type.
4. 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.

# Recipient counts

The recipient counts that Iterable displays for a campaign are impacted by its message type and the subscription preferences of the users it targets.

• Campaign recipient count estimate

  The Review & Launch screen, displayed while setting up a campaign (immediately before it is scheduled or sent), shows an estimate of the campaign's recipient count:

  

  This number is calculated by taking the send list, subtracting suppressed users, and subtracting users whose subscription preferences do not allow them to receive the campaign.

  If the campaign has an opt-in message type, users on the send list who have not opted in to that message type are not included in the estimate.

  NOTE

  This number is only an estimate. The size of the list may change before the campaign is sent (for example, if it is scheduled to be sent in the future).

• Campaign analytics recipient count

  After sending a campaign, open it to view its Campaign Analytics screen. Near the top of the screen, there is a list of various pieces of information about the campaign:

  

  Iterable calculates the List Size at Send Time by taking the send-time send list, subtracting suppressed users, and subtracting users whose subscription preferences did not allow them to receive the campaign.

  If the campaign was sent with an opt-in message type, the count does not include users on the send list who had not opted in to that message type at send time.

# 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.

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.

# Unsubscribe links

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

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

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

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).

# 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.

# Further reading

• Message Channels and Types Best Practices
• CAN-SPAM Act
• API Overview and Sample Payloads
• Creating a Subscription Preference Center
• Universal Merge Parameters