Message Channels and Message Types Overview

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

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.

# 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 from Newsletters, Product Suggestions, or Promotional emails.
• Subscribing users to the Marketing Channel but unsubscribing them from Newsletters and Product Suggestions means they only receive Promotional emails.

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

# Create message channels

To create a message channel:

1. Go to Settings > Message Channels and Types.
2. In the left hand menu, choose the message medium for the new channel (email, in-app, push, SMS, web push).
3. Click New Subscription Channel.
4. Enter details for your new channel:
   • Name - For display in Iterable
   • Type - Marketing or Transactional (you can't change this later)
5. 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:

1. Go to Settings > Sending Platforms.
2. Select the sending platform you wish to update.
3. 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:

1. Go to Settings > Message Channels and Types.

2. Find the email channel you wish to update.

3. Click the overflow menu (three dots) and select Edit Subscription Channel

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

1. Go to Settings > Message Channels and Types.
2. In the left hand menu, select the message medium for the new message type (email, SMS, push, in-app, web push).
3. Below the message channel you're creating a type for, click Add Message Type.
4. 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.
5. 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.

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

• userListIds: Static lists of subscribed users, used by userID-based and
  hybrid projects

• unsubscribedChannelIds: IDs of message channels from which the user unsubscribed

• unsubscribedMessageTypeIds: IDs of message types from which the user 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 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.

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:

Creates a link that users can click to unsubscribe from the message type associated with the message they're reading.

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.

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

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

  POST /api/subscriptions/subscribeToDoubleOptIn

# APIs for overwriting subscriptions

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:

  POST /api/users/updateSubscriptions

• Overwriting subscription information for multiple users:

  POST /api/users/bulkUpdateSubscriptions

# Breaking API change

Iterable's Subscriptions API and opt-in message types are enabled by default for all organizations created after September 2019.

Because of a breaking API change, organizations created before September 2019 don't have Iterable's Subscriptions API or opt-in message types enabled by default. If your organization was created before this date, your customer success manager must enable this feature.

To learn more about the impact of this update, read Breaking API Change.

After opt-in message types are enabled, you can no longer set values for the following arrays by including them in the dataFields object of an API request body:

• emailListIds or userListIds
• 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).

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

1. Add a Yes/No Split tile onto the canvas

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

• Foundations: Message Channels and Message Types