Update user’s subscription group status (V2)

post

/v2/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 Subscriptions Group 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

Prequisites

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

Rate limit

This endpoint has 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

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

{
  "subscription_groups":[
    {
      "subscription_group_id": (required, string),
      "subscription_state": (required, string)
      "external_ids": (required*, array of strings),
      "emails": (required*, array of strings),
      "phones": (required*, array of strings in E.164 format),
    }
  ]
}

* Note that you cannot include both emails and phones parameters. Also, emails, phones, and external_ids can all be sent individually.

tip:

When creating new users using the /users/track endpoint, you can set subscription groups within the user attributes object, which allows you to create a user and set the subscription group state in one API call.

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_ids Required* Array of strings The external_id of the user or users, may include up to 50 ids.

emails 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, all users that share the email address are updated with the subscription group changes.

phones Required* String in E.164 format The phone numbers of the user, can be passed as an array of strings. Must include at least one phone number (with a maximum of 50).

note:

Note that you cannot include both emails and phones parameters. Also, emails, phones, and external_ids can all be sent individually.

Example requests

The following example uses external_id to make one API call for email and SMS.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_groups":[
    {
      "subscription_group_id":"subscription_group_identifier",
      "subscription_state":"subscribed",
      "external_ids":["example-user","[email protected]"]
    },
    {
      "subscription_group_id":"subscription_group_identifier",
      "subscription_state":"subscribed",
      "external_ids":["example-user","[email protected]"]
    }
  ]
}

Email

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

SMS and WhatsApp

curl --location --request POST 'https://rest.iad-01.braze.com/v2/subscription/status/set' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "subscription_groups":[
    {
      "subscription_group_id":"subscription_group_identifier",
      "subscription_state":"subscribed",
      "phones":["+12223334444","+15556667777"]
    }
  ]
}
'

Edit this page on GitHub

HOW HELPFUL WAS THIS PAGE?

Edit this page on GitHub

New Stuff!