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

Prerequisites

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

note:

If you’re interested in using this endpoint with LINE subscription groups, contact your customer success manager.

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 (up to 50).

If multiple users (external_id) in the same workspace share the same phone number, then all users that share the phone number are updated with the same subscription group changes.

use_double_opt_in_logic Optional Boolean If this parameter is omitted or set to false, users won’t be entered into the SMS double opt-in workflow.

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

New Stuff!