Parameters

App Group REST API Key

The api_key indicates the app title with which the data in this request is associated and authenticates the requester as someone who is allowed to send messages to the app. It must be included with every request as a HTTP Authorization header. It can be found in the Developer Console section of the Braze dashboard.

App Identifier

If you want to send push to a set of device tokens (instead of users), you need to indicate on behalf of which specific app you are messaging. In that case, you will provide the appropriate App Identifier in a Tokens Object. It can be found in the Developer Console section of the Braze dashboard.

Broadcast

When sending a message to a segment or campaign audience using an API endpoint, Braze requires you to explicitly define whether or not your message is a "broadcast" to a large group of users by including a broadcast boolean in the API call. That is, if you intend to send an API message to the entire segment that a campaign or Canvas targets, you must include broadcast: true in your API call.

Broadcast is a required field and the default value set by Braze when a campaign or Canvas is made is broadcast: false. You can't have both broadcast: true and a recipients list specified. If the broadcast flag is set to true and an explicit list of recipients is provided, the API endpoint will return an error. Similarly, including broadcast: false and not providing a recipient list will return an error.

Use caution when setting broadcast: true, as unintentionally setting this flag may cause you to send your campaign or Canvas to a larger than expected audience. The broadcast flag is required to protect against accidental sends to large groups of users.

Campaign Identifier

For messaging endpoints, the campaign_id indicates the API Campaign under which the analytics for a message should be tracked. A Campaign Identifier for each of the campaigns you have created can be found in the Developer Console section of the Braze dashboard. If you provide a Campaign Identifier in the request body, you must provide a message_variation_id in each of the message objects indicating the represented variant of your campaign.

For campaign trigger endpoints, the campaign_id indicates the API ID of the campaign to be triggered. This field is required for all trigger endpoint requests.

Canvas Entry Properties

When using one of the endpoints for triggering or scheduling a Canvas via the API, you may provide a map of keys and values to customize messages sent by the first steps of your Canvas, in the "canvas_entry_properties" namespace.

For example, a request with "canvas_entry_properties" : {"product_name" : "shoes", "product_price" : 79.99} could add the word "shoes" to a message by adding {{canvas_entry_properties.${product_name}}}.

Canvas Identifier

For Canvas triggering endpoints, the canvas_id indicates the identifier of the Canvas to be triggered or scheduled. This field is required for all trigger endpoint requests.

External User ID

A unique identifier for sending a message to specific users. This identifier should be the same as the one you set in the Braze SDK. You can only target users for messaging who have already been identified through the SDK or the User API. A maximum of 50 External User IDs are allowed in a request.

For campaign trigger endpoints, if you provide this field, the criteria will be layered with the campaign's segments and only users who are in the list of External User IDs and the campaign's segment will receive the message.

Segment Identifier

The segment_id indicates the segment to which the message should be sent. A Segment Identifier for each of the segments you have created can be found in the Developer Console section of the Braze dashboard.

For message endpoints, if you provide both a Segment Identifier and a list of External User IDs in a single messaging request, the criteria will be layered and only users who are in both the list of External User IDs and the provided segment will receive the message.

Send Identifier

For messaging endpoints, the send_id indicates the send under which the analytics for a message should be tracked. The send_id allows you to pull back analytics for a specific instance of a campaign send via the sends/data_series endpoint. API and API trigger campaigns that are sent as a broadcast will automatically generate a send identifier if a send identifier is not provided.

If you want to specify your own send_id, you'd have to first create one via the sends/id/create endpoint. The send_id must be all ASCII characters and at most 64 characters long. You can reuse a send identifier across multiple sends of the same campaign if you want to group analytics of those sends together.

Note that send_id tracking is not available for emails sent via Mailjet.

Campaign conversions are attributed to the last tracked send_id that the user received from that campaign, unless the last send the user received was untracked.

Trigger Properties

When using one of the endpoints for sending a campaign with API-Triggered Delivery, you may provide a map of keys and values to customize your message. If you make an API request that contains an object in "trigger_properties", the values in that object can then be referenced in your message template under the api_trigger_properties namespace.

For example, a request with "trigger_properties" : {"product_name" : "shoes", "product_price" : 79.99} could add the word "shoes" to the message by adding {{api_trigger_properties.${product_name}}}.