Set User Subscriptions
Engage Premier requires a Business tier account and includes Engage Foundations and Unify.
See the available plans, or contact Support.
Segment associates a user subscription state with each email address and phone number in your Engage audiences. Subscription states give you insight into the level of consent a user has given you to receive your Engage campaigns.
You can set a user’s subscription state using a CSV file or, programmatically, using Reverse ETL or Segment’s APIs. On this page, you’ll learn how and when to use these processes.
Setting user subscriptions with a CSV file upload
Setting user subscriptions by uploading a CSV file proves useful when you’re importing batch contacts to Segment for the first time or when you need to change a specific user’s subscription status.
For example, you may want to add contacts to Segment using an audience list sourced from a third-party tool, or you may have gathered a large number of contacts from an in-person event.
Subscription state CSV fields
To learn how to upload a CSV file to Segment, view the Engage CSV Uploader page.
To change the subscription status of an email or phone number with a CSV file, include at least one of the following user subscription columns next to the contact column:
email_subscription_status
sms_subscription_status
These columns take the following values:
subscribed
; for users who opted in to your marketing campaignsunsubscribed
; for users who have unsubscribed from your marketing campaignsdid-not-subscribe
; for users who have neither subscribed nor unsubscribed from your marketing campaigns- Blank; for email addresses or phone numbers that Segment collected without the user explicitly providing them
Engage accepts both uppercase and lowercase subscription status values.
Refer to the User Subscription States documentation for detailed explanations of each subscription state.
Manage user subscriptions with Segment APIs
With Segment’s APIs, you can manage user subscriptions programmatically on a real-time basis. Use the APIs for ongoing subscription status updates, like when users subscribe to your marketing campaigns on a website form or modify their subscription from within a notification center.
Choosing between the Identify call and the Public API
To update Engage user subscriptions with Segment’s APIs, first choose between the Identify call, for non-critical subscription updates, or the Public API, for critical updates that require immediate confirmation, like unsubscribes.
When you use the Identify call, Segment replies with a standard HTTP 200 OK
status response code if it successfully received the request. Because the Identify call updates user traits asynchronously, though, the 200 OK
code indicates that Segment has received, but not yet processed, the request. As a result, use the Identify call for non-critical subscription updates, like form signups on your website or adding a subscription from within the user’s notification center.
When you update user subscriptions with Segment’s Public API, however, you’ll get an immediate response that confirms that Segment both received and processed the request. Use the Public API, then, for unsubscribes, so users immediately find out if their subscription updated.
Format the Identify call payload
For Segment to process the subscription status request, your Identify call payload must include at least one object that contains an email address or phone number, its subscription type, and its subscription status. Engage accepts both uppercase and lowercase subscription statuses in Identify calls.
The following example payload shows an Identify call with a context
object, which you’ll add to the Identify call to update user subscriptions. The context
object contains a messaging_subscriptions
array with three objects that update SMS, WhatsApp, and email subscription statuses:
{
"userId": "12aBCDeFg4hIjKlM5OPq67RS8Tu",
"context": {
"messaging_subscriptions": [
{
"key": "(123) 555-5555",
"type": "SMS",
"status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE"
},
{
"key": "(123) 555-5555",
"type": "WhatsApp",
"status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE"
},
{
"key": "test@example.com",
"type": "EMAIL",
"status": "SUBSCRIBED" | "UNSUBSCRIBED" | "DID_NOT_SUBSCRIBE"
}
],
"externalIds": [
{
"id": "(123) 555-5555",
"type": "phone",
"collection": "users",
"encoding": "none"
}
],
"traits": {
"email": "test@example.com"
}
},
"integrations": {},
"traits": {}
}
For successful requests, Segment instantly updates subscription states in your workspace. You can then display successful updates or error messages with users in your notification center.
While SMS and WhatsApp share the same number, you must add a separate subscription state for both of them.
Setting user subscriptions with Reverse ETL
Engage Premier Subscriptions users can use Reverse ETL to sync subscription data from warehouses to destinations. To get started with using Reverse ETL for managing subscriptions, see Reverse ETL for Engage Premier Subscriptions.
This page was last modified: 03 Jun 2024
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!