Update users’ subscription group status
Use the endpoints below to batch update the subscription state of up to 50 users 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:
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.
1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
4
5
6
7
8
{
"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*, array of strings) 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
// Please note that sending an email address that is linked to multiple profiles will update all relevant profiles
}
* Email subscription groups: Either email or external_id is required.
This property should not be used for updating a user’s profile information. Please use the /users/track property instead.
When creating new users via the /users/track endpoint, you should leave a delay of around 2 minutes before adding users to the relevant Subscription Group to allow Braze time to fully create the user profile.
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 | The email address of the user, can be passed as an array of strings. Must include at least one email address (with a max of 50). If multiple users ( external_id) in the same app group 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 max 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": "example-user",
"email": ["example1@email.com", "example2@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": "subscription_group_identifier",
"subscription_state": "unsubscribed",
"external_id": "external_identifier",
"phone": ["+12223334444", "+11112223333"]
}
'
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