Skip to content

List user’s subscription group status

get

/subscription/status/get

Use this endpoint to get the subscription state of a user in a subscription group.

These groups will be available on the Subscription Group page. The response from this endpoint will include the external ID and either subscribed, unsubscribed, or unknown for the specific subscription group requested in the API call. This can be used to update the subscription group state in subsequent API calls or to be displayed on a hosted web page.

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

See me in Postman

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

See me in Postman

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

See me in Postman

Prerequisites

To use this endpoint, you’ll need an API key with the subscription.status.get permission.

Rate limit

We apply the default Braze rate limit of 250,000 requests per hour to this endpoint, as documented in API rate limits.

Request parameters

Parameter Required Data Type Description
subscription_group_id Required String The id of your subscription group.
external_id Required* String The external_id of the user (must include at least one and at most 50 external_ids).

When both an external_id and email/phone are submitted, only the external_id(s) provided will be applied to the result query.
email Required* String The email address of the user. It can be passed as an array of strings with a maximum of 50.

Submitting both an email address and phone number (with no external_id) will result in an error.
phone Required* String in E.164 format The phone number of the user. If email is not included, you must include at least one phone number (with a maximum of 50).

Submitting both an email address and phone number (with no external_id) will result in an error.

*One of external_id or email or phone is required for each user.

  • For SMS and WhatsApp subscription groups, either external_id or phone is required. When both are submitted, only the external_id is used for querying and the phone number is applied to that user.
  • For email subscription groups, either external_id or email is required. When both are submitted, only the external_id is used for the query and the email address is applied to that user.

Example request

1

https://rest.iad-03.braze.com/subscription/status/get?subscription_group_id={{subscription_group_id}}&external_id[]=1&external_id[]=2

1
2

curl --location -g --request GET 'https://rest.iad-01.braze.com/subscription/status/get?subscription_group_id={{subscription_group_id}}&phone=+11112223333' \
--header 'Authorization: Bearer YOUR-REST-API-KEY'

Response

All successful responses will return Subscribed, Unsubscribed, or Unknown depending on status and user history with the subscription group.

1
2
3
4
5
6
7
8
9

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "status": {
    "1": "Unsubscribed",
    "2": "Subscribed"
  },
  "message": "success"
}
  Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!