Message Channels and Message Types Overview

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

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

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

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

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

3. Hover over the new channel's row and click Edit.

4. Set the channel's Name, and choose Marketing or Transactional.

5. Hover over the new 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. 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.

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

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

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

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