Subscription Groups

Manage groups of specific users, and their messaging preferences.

Introduction

Subscription groups help you manage groups of specific end users, and their messaging preferences. They are important both for obtaining end users’ trust, as well as achieving regulatory compliance.

Subscription groups are associated with a specific channel e.g. email, SMS, or push. One can have multiple subscription groups per channel. Subscription groups can be assigned to journey message nodes, to allow those messages to render unsubscribe links, and to ensure that users are not messaged unless they are subscribed to the relevant subscription group.

Creating a Subscription Group

By default, workspaces are populated with one subscription group per channel. Additional subscription groups can be created via /dashboard/subscription-groups page.

To create a new subscription group, click the (+) button. Then edit the subscription group name, and press save.

Opt-In vs Opt-Out Subscription Groups

There are two types of subscription groups, opt-in, and opt-out.

Opt-In Subscription Groups

Opt-in subscription groups require end users to explicitly subscribe to the subscription group.

They are a great option for newsletters, and other marketing messages, where you want to ensure that users are actively interested in receiving messages.

Opt-Out Subscription Groups

Opt-out subscription groups automatically include all users, unless they explicitly unsubscribe. They are great for messages which users are likely to want to receive. For example, an email notifying user of new friend invitations on a social network.

Adding and Removing Users from a Subscription Group

Users can be added and removed from subscription groups either programmatically, or manually via the dashboard. It’s important to understand how to add users to opt-in subscription groups, which are empty by default.

CSV Upload

Users can be added to subscription groups with manual csv uploads from the dashboard. To do so navigate to a particular subscription group’s upload page /dashboard/subscription-groups/upload/[id].

The provided CSV file should have the following format.

users.csv

id,email,firstName,lastName
d1bdf186-7dd9-485e-9f93-6e0e3f3e6b8a,[e-mail],John,Doe
f5c5d1e5-d1f5-4d65-8b8f-7d4d153c4a51,[e-mail],Jane,Doe
a4ef2311-cd4c-4e5d-9d21-7c3e8b29c7b1,[e-mail],Alice,Johnson
b8c5cd71-214d-4d62-92a4-85e9e4d4efbe,[e-mail],Bob,Smith
7b73a62c-bfd2-4a8a-ba9f-bfcbfd234c89,[e-mail],Charlie,Brown

Either the id or email field must be present. If both are present, the id field will be used to identify the user. If neither are present, the upload will fail.

Non-identifying fields such as firstName and lastName are optional and will map to and update user traits. Users will be created if they do not already exist.

Submit a Track Event

Users’ subscription state can also be updated programmatically, by submitting user events. For more information on how sumit user events, see Submitting User Events.

Subscribe Track Event

{
    "userId": "4f40e10c-2a45-4215-8f6b-51c01c06beb7",
    "timestamp": "2023-05-19T00:48:43.494Z",
    "messageId": "550700ed-f92a-4b9f-86dd-40e76e03fb6f",
    "type": "track",
    "event": "DFSubscriptionChange",
    "properties": {
      "subscriptionId": "225c4f51-9137-417e-9ce1-c537c761bd9a",
      "action": "Subscribe",
    },

}

Unsubscribe Track Event

{
    "userId": "4f40e10c-2a45-4215-8f6b-51c01c06beb7",
    "timestamp": "2023-05-19T00:48:43.494Z",
    "messageId": "550700ed-f92a-4b9f-86dd-40e76e03fb6f",
    "type": "track",
    "event": "DFSubscriptionChange",
    "properties": {
      "subscriptionId": "225c4f51-9137-417e-9ce1-c537c761bd9a",
      "action": "Unsubscribe",
    },
}

Note that users’ subscription state will be updated asynchronously, and will not be updated immediately with this method.

Loading the Subscription Management Page

Users have access to the dashboard’s subscription management page, which allows them to manage their subscription state.

The subscription management will either unsubscribe, or subscribe the user to a specific users to a subscription group on page load. Unsubscribe links direct users to the subscription management page,performing the unsubscribe action.”

Note that this subscription state change occurs synchronously, and will be reflected immediately. This is in contrast to the asynchronous subscription state change that occurs when submitting a track event.

This page is exempt from the dashboard’s standard authentication requirements, and can be accessed by any user. Instead, it is authenticated by a cryptographically signed hash, which is generated on the backend and included in the link to the page.

The subscription management page can be previewed from the dashboard’s settings page /dashboard/settings.

Adding Subscription Groups to a User Journey

In order to use a subscription group, it must be added to a user journey. This ensures that users are not messaged from message nodes unless they are in the subscription group at the time of send.

It also allows unsubscribe links to be rendered in emails.

Adding Unsubscribe Links to Emails

When journey message nodes have subscription groups associated with them, unsubscribe links can be added to emails with the unsubscribe_link liquid tag.

{% unsubscribe_link %}

On loading the Subscription Management page, users will be either subscribed or unsubscribed to a specific subscription group.

The Importance of Subscription Groups for Regulatory Compliance

Subscription groups are important for regulatory compliance. Regulations like CAN-SPAM require that users be able to unsubscribe from marketing messages. Providing unsubscribe links is also important for ensuring email deliverability.

Viewing Users in a Subscription Group

You can view which users are in a subscription group by navigating to the subscription group’s user page in the dashboard /dashboard/subscription-groups/users/[id].