​
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.
Subscription Groups Page
To create a new subscription group, click the (+) button. Then edit the subscription group name, and press save.
Subscription Groups Configuration Page

​
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,action
d1bdf186-7dd9-485e-9f93-6e0e3f3e6b8a,[email protected],John,Doe,subscribe
f5c5d1e5-d1f5-4d65-8b8f-7d4d153c4a51,[email protected],Jane,Doe,unsubscribe
a4ef2311-cd4c-4e5d-9d21-7c3e8b29c7b1,[email protected],Alice,Johnson,subscribe
b8c5cd71-214d-4d62-92a4-85e9e4d4efbe,[email protected],Bob,Smith,
7b73a62c-bfd2-4a8a-ba9f-bfcbfd234c89,[email protected],Charlie,Brown

​
Required Fields

Either id or email field must be present to identify the user, otherwise the upload will fail.

​
Optional Fields

  • 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.
  • action field controls the subscription action for each user:
    • subscribe - subscribes the user to the subscription group
    • unsubscribe - unsubscribes the user from the subscription group
    • If the action column is missing, empty, or null, users will be subscribed by default
    • Any other value will result in a 400 error

​
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.
Subscription Management Page
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.
Subscription Management Preview

​
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.
Subscription Groups in User Journeys
It also allows unsubscribe links to be rendered in 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 %}
Unsubscribe Link in Email
You can also use the unsubscribe_url liquid tag to just render the unsubscribe url, without the link element. This can be useful if you want to customize the unsubscribe link styling. 
<a class="custom-unsubscribe-link" href="{% unsubscribe_url %}"
  >custom unsubscribe link</a
>
On loading the Subscription Management page via unsubscribe links, users will be automatically unsubscribed from the specific subscription group. For cases where you want to provide users with access to subscription management without automatically unsubscribing them, you can use the subscription_management_link liquid tag. 
{% subscription_management_link %}
This creates a link that directs users to the subscription management page without performing any automatic subscription changes on page load. Users can then manually manage their subscription preferences. You can also use the subscription_management_url liquid tag to just render the subscription management url, without the link element. 
<a class="custom-subscription-management-link" href="{% subscription_management_url %}"
  >manage your subscription preferences</a
>
These tags are useful when you want to give users control over their subscription preferences without forcing an immediate unsubscribe action.

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

​
Opt-in Tutorial Video