Update Users’ Subscription Group Status
Use the endpoints below to update the subscription state of a user on the Braze dashboard. You can access a subscription groups subscription_group_id by navigating to it on 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:
Looking for the api_key parameter?
As of May 2020, Braze has changed how we read API keys to be more secure. Now API keys must be passed as a request header, please see YOUR_REST_API_KEY within the Example Request below.
Braze will continue to support the api_key being passed through the request body and URL parameters, but will eventually be sunset. Please update your API calls accordingly.
Request Body
1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY
1
2
3
4
5
6
7
8
9
10
11
12
{
"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*, string) the external_id of the user,
"email": (required*, array of string) the email address of the user (must include at least one email and at most 50 emails),
// Email subscription group - one of external_id or email is required
// Endpoint only accepts email or phone value, not both
// Please note that sending an email address that is linked to multiple profiles will update all relevant profiles
"phone": (required*, array of string 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
// Endpoint only accepts email or phone value, not both
}
* SMS subscription groups: Only external_id or phone is accepted.
* Email subscription groups: Either email or external_id is required.
Request Parameters
| Parameter | Required | Data Type | Description |
|---|---|---|---|
subscription_group_id |
Yes | String | The id of your subscription group, |
subscription_state |
Yes | String | Available values are “unsubscribed” (not in subscription group) or “subscribed” (in subscription group) |
external_id |
Yes* | String | The external_id of the user |
email |
Yes* | String | The email address of the user, can be passed as an array of strings (must include at least one address and at most 50 addresses). |
phone |
Yes* | String in E.164 format | Tags must already exist. |
Using Email
1
2
3
4
5
6
{
"subscription_group_id": "pto81fff-734f-80e5-b7b2-b880562888ww",
"subscription_state": "unsubscribed",
"email": "your.user@email.com",
}
This property should not be used for updating a user’s profile information. Please use the /users/track property instead.
Using Phone Number
1
2
3
4
5
6
{
"subscription_group_id": "pto81fff-734f-80e5-b7b2-b880562888ww",
"subscription_state": "unsubscribed",
"phone": "+12223334444",
}
This property should not be used for updating a user’s profile information. Please use the /users/track property instead.
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": "pto81fff-734f-80e5-b7b2-b880562888ww",
"subscription_state": "unsubscribed",
"external_id": "user123",
"email": ["your.user@email.com", "your.user2@email.com"]
}
'
Example Requests 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": "pto81fff-734f-80e5-b7b2-b880562888ww",
"subscription_state": "unsubscribed",
"external_id": "user123",
"phone": ["+12223334444", "+13334445555"]
}
'
Example Successful Response
Response: (status 201)
1
2
3
{
"message": "success"
}
The endpoint only accepts the email or phone value, not both. If given both, you will receive this response: {"message":"Either an email address or a phone number should be provided, but not both."}
Edit this page on GitHub