Skip to content

Update user’s subscription group status

post

/subscription/status/set

Use this endpoint to batch update the subscription state of up to 50 users on the Braze dashboard.

You can access a subscription group’s subscription_group_id by navigating to the Subscription Group page.

If you want to see examples or test this endpoint for Email Subscription Groups:

If you want to see examples or test this endpoint for SMS Subscription Groups:

Rate limit

For customers who onboarded with Braze on or after January 6, 2022, we apply a rate limit of 5,000 requests per minute shared across the /subscription/status/set and /v2/subscription/status/set endpoint as documented in API rate limits.

Request body

1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
4
5
6
7
{
   "subscription_group_id": (required, string) the id of your subscription group,
   "subscription_state": (required, string) available values are "unsubscribed" (not in subscription group) or "subscribed" (in subscription group),
   "external_id": (required*, array of strings) the external ID of the user or users, may include up to 50 IDs,
   "phone": (required*, array of strings in E.164 format) The phone number of the user (must include at least one phone number and at most 50 phone numbers),
   // SMS subscription group - one of external_id or phone is required
 }

* SMS subscription groups: Only external_id or phone is accepted.

This property should not be used for updating a user’s profile information. Use the /users/track property instead.

Request parameters

Parameter Required Data Type Description
subscription_group_id Required String The id of your subscription group.
subscription_state Required String Available values are unsubscribed (not in subscription group) or subscribed (in subscription group).
external_id Required* Array of strings The external_id of the user or users, may include up to 50 ids.
email Required* String or array of strings The email address of the user, can be passed as an array of strings. Must include at least one email address (with a maximum of 50).

If multiple users (external_id) in the same workspace share the same email address, then all users that share the email address are updated with the subscription group changes.
phone Required* String in E.164 format The phone number of the user, can be passed as an array of strings. Must include at least one phone number (with a maximum of 50).

Example requests

Email

1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_group_id": "subscription_group_identifier",
  "subscription_state": "unsubscribed",
  "external_id": "external_identifier",
  "email": ["[email protected]", "[email protected]"]
}
'

SMS

1
2
3
4
5
6
7
8
9
10
curl --location --request POST 'https://rest.iad-01.braze.com/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_group_id": "subscription_group_identifier",
  "subscription_state": "unsubscribed",
  "external_id": "external_identifier",
  "phone": ["+12223334444", "+11112223333"]
}
'

Example success response

The status code 201 could return the following response body.

1
2
3
{
    "message": "success"
}
HOW HELPFUL WAS THIS PAGE?
New Stuff!