@spec campaigns_trigger_send_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

send-campaign-messages-via-api-triggered-delivery

Send Campaign Messages via API Triggered Delivery

Use this endpoint to send immediate, ad-hoc messages to designated users via API-triggered delivery.

API-triggered delivery allows you to house message content inside of the Braze dashboard while dictating when a message is sent, and to whom via your API.

If you are targeting a segment, a record of your request will be stored in the Developer Console. Note that to send messages with this endpoint, you must have a campaign ID created when you build an API-triggered campaign.

prerequisites

Prerequisites

To use this endpoint, you'll need to generate an API key with the campaigns.trigger.send permission.

rate-limit

Rate limit

When specifying a segment or Connected Audience in your request, we apply a rate limit of 250 requests per minute to this endpoint. Otherwise, if specifying an external_id, this endpoint has a default rate limit of 250,000 requests per hour, as documented in API rate limits.

Braze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:

• Up to 50 specific external_ids, each with individual message parameters
• A segment of any size created in the Braze dashboard, specified by its segment_id
• An ad-hoc audience segment of any size, defined in the request as a Connected Audience object

request-parameters

Request parameters

The recipients array may contain up to 50 objects, with each object containing a single external_user_id string and trigger_properties object.

When send_to_existing_only is true, Braze will only send the message to existing users. When send_to_existing_only is false and a user with the given id does not exist, Braze will create a user with that id and attributes before sending the message.

Important: A user’s subscription group status can be updated via the inclusion of a subscription_groups parameter within the attributes object. This is currently in early access. Contact your Braze customer success manager if you’re interested in participating in the early access. More details can be found in the User attributes object.

response-details

Response details

Message sending endpoint responses will include the message’s dispatch_id for reference back to the dispatch of the message. The dispatch_id is the ID of the message dispatch, a unique ID for each transmission sent from the Braze platform. When using this endpoint, you receive a single dispatch_id for an entire batched set of users. For more information on dispatch_id check out out our documentation on Dispatch ID Behavior.

create-send-endpoint

Create send endpoint

Using the attributes object in campaigns

Braze has a Messaging Object called Attributes that will allow you to add, create, or update attributes and values for a user before you send them an API-triggered campaigns using the campaign/trigger/send endpoint as this API call will process the User Attributes object before it processes and sends the campaign. This helps minimize the risk of there being issues caused by race conditions.

Important: Looking for the Canvas version of this endpoint? Check out Sending Canvas messages via API-triggered delivery.

parameters

Parameters

• connection (BrazeEx.Connection): Connection to server
• opts (keyword): Optional parameters
  • :"Content-Type" (String.t):
  • :Authorization (String.t):
  • :body (String.t):

returns

Returns

• {:ok, nil} on success
• {:error, Tesla.Env.t} on failure

@spec canvas_trigger_send_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

send-canvas-messages-via-api-triggered-delivery

Send Canvas Messages via API Triggered Delivery

Use this endpoint to send Canvas messages via API-triggered delivery.

To use this endpoint, you’ll need to generate an API key with the canvas.trigger.send permission.

API-triggered delivery allows you to house message content inside of the Braze dashboard while dictating when a message is sent, and to whom via your API.

Note that to send messages with this endpoint, you must have a Canvas ID created when you build a Canvas.

rate-limit

Rate limit

When specifying a segment or Connected Audience in your request, we apply a rate limit of 250 requests per minute to this endpoint. Otherwise, if specifying an external_id, this endpoint has a default rate limit of 250,000 requests per hour, as documented in API rate limits.

Braze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:

• Up to 50 specific external_ids, each with individual message parameters
• A segment of any size created in the Braze dashboard, specified by its segment_id
• An ad-hoc audience segment of any size, defined in the request as a Connected Audience object

request-parameters

Request parameters

Customers using the API for server-to-server calls may need to whitelist the appropriate API URL if they’re behind a firewall.

Note: If you include both specific users in your API call and a target segment in the dashboard, the message will send to specifically the user profiles that are in the API call and qualify for the segment filters.

response-details

Response details

Message sending endpoint responses will include the message’s dispatch_id for reference back to the dispatch of the message. The dispatch_id is the ID of the message dispatch (unique ID for each “transmission” sent from the Braze platform). Check out Dispatch ID behavior for more information.

create-send-endpoint

Create send endpoint

Using the Attributes Object in Canvas

Braze has a Messaging Object called Attributes that allows you to add, create, or update attributes and values for a user before sending them an API-Triggered Canvas using the canvas/trigger/send endpoint as this API call will process the User Attributes object before it processes and sends the Canvas. This helps minimize the risk of there being issues caused by race conditions.

Important: Looking for the camaigns version of this endpoint? Check out Sending campaign messages via API-triggered delivery.

parameters

Parameters

• connection (BrazeEx.Connection): Connection to server
• opts (keyword): Optional parameters
  • :"Content-Type" (String.t):
  • :Authorization (String.t):
  • :body (String.t):

returns

Returns

• {:ok, nil} on success
• {:error, Tesla.Env.t} on failure

@spec messages_send_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

send-messages-immediately-via-api-only

Send Messages Immediately via API Only

Use this endpoint to send immediate, ad-hoc messages to designated users via the Braze API.

Be sure to include Messaging Objects in your body to complete your requests.

If you are targeting a segment, a record of your request will be stored in the Developer Console.

prerequisites

Prerequisites

To use this endpoint, you'll need to generate an API key with the messages.send permission.

rate-limit

Rate limit

When specifying a segment or Connected Audience in your request, we apply a rate limit of 250 requests per minute to this endpoint. Otherwise, if specifying an external_id, this endpoint has a default rate limit of 250,000 requests per hour, as documented in API rate limits.

Braze endpoints support batching API requests. A single request to the messaging endpoints can reach any of the following:

• Up to 50 specific external_ids, each with individual message parameters
• A segment of any size created in the Braze dashboard, specified by its segment_id
• An ad-hoc audience segment of any size, defined in the request as a Connected Audience object

request-parameters

Request parameters

response-details

Response details

Message sending endpoint responses will include the message’s dispatch_id for reference back to the dispatch of the message. The dispatch_id is the id of the message dispatch (unique id for each ‘transmission’ sent from the Braze platform). For more, information refer to Dispatch ID behavior.

parameters

Parameters

• connection (BrazeEx.Connection): Connection to server
• opts (keyword): Optional parameters
  • :"Content-Type" (String.t):
  • :Authorization (String.t):
  • :body (String.t):

returns

Returns

• {:ok, nil} on success
• {:error, Tesla.Env.t} on failure

@spec sends_id_create_post(
  Tesla.Env.client(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

create-send-ids-for-message-send-tracking

Create Send IDs For Message Send Tracking

Use this endpoint to create send IDs that can be used to send messages and track message performance programatically, without campaign creation for each send.

Using the send identifier to track and send messages is useful if you are planning to programmatically generate and send content.

prerequisites

Prerequisites

To use this endpoint, you'll need to generate an API key with the sends.id.create permission.

rate-limit

Rate limit

The daily maximum number of custom send identifiers that can be created via this endpoint is 100 for a given app group. Each send_id and campaign_id combination that you create will count towards your daily limit. The response headers for any valid request include the current rate limit status, see API rate limits for details.

request-parameters

Request parameters

response

Response

example-success-response

Example success response

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
"message": "success",
"send_id" : (string) the send identifier
}

parameters

Parameters

• connection (BrazeEx.Connection): Connection to server
• opts (keyword): Optional parameters
  • :"Content-Type" (String.t):
  • :Authorization (String.t):
  • :body (String.t):

returns

Returns

• {:ok, nil} on success
• {:error, Tesla.Env.t} on failure

@spec transactional_v1_campaigns_campaign_id_send_post(
  Tesla.Env.client(),
  String.t(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

send-transactional-email-via-api-triggered-delivery

Send Transactional Email via API Triggered Delivery

Use this endpoint to send immediate, ad-hoc transactional messages to a designated user.

This endpoint is used alongside the creation of a Transactional Email campaign and corresponding campaign ID.

Important: Transactional Email is currently available as part of select Braze packages. Reach out to your Braze customer success manager for more details.

Similar to the Send triggered campaign endpoint, this campaign type allows you to house message content inside of the Braze dashboard while dictating when and to whom a message is sent via your API. Unlike the Send triggered campaign endpoint, which accepts an audience or segment to send messages to, a request to this endpoint must specify a single user either by external_user_id or user_alias, as this campaign type is purpose-built for 1:1 messaging of alerts like order confirmations or password resets.

prerequisites

Prerequisites

To use this endpoint, you'll need to generate an API key with the transactional.send permission.

rate-limit

Rate limit

Transactional Emails are not subject to a rate limit. Depending on your chosen package, a set number of Transactional Emails is covered per hour by SLA. Requests that exceed that rate will still send, but are not covered by SLA. 99.9% of emails will send in less than one minute.

path-parameters

Path parameters

request-parameters

Request Parameters

response

Response

The send transactional email endpoint will respond with the message’s dispatch_id which represents the instance of this message send. This identifier can be used along with events from the Transactional HTTP event postback to trace the status of an individual email sent to a single user.

example-response

Example response

{
  "dispatch_id": Out-of-the-box generated Unique ID of the instance of this send
  "status": Current status of the message
  "metadata": Object containing additional information about the send instance
}

troubleshooting

Troubleshooting

The endpoint may also return an error code and a human-readable message in some cases, most of which are validation errors. Here are some common errors you may get when making invalid requests.

Most endpoints at Braze have a rate limit implementation that will return a 429 response code if you have made too many requests. The transactional sending endpoint works differently -- if you exceed your allotted rate limit, our system will continue to ingest the API calls, return success codes, and send the messages, however those messages may not be subject to the contractual SLA for the feature. Please reach out if you need more information about this functionality.

transactional-http-event-postback

Transactional HTTP Event Postback

All transactional emails are complemented with event status postbacks sent as an HTTP request back to your specified URL. This will allow you to evaluate the message status in real-time and take action to reach the user on another channel if the message goes undelivered, or fallback to an internal system if Braze is experiencing latency.

In order to associate the incoming events to a particular instance of send, you can choose to either capture and store the Braze dispatch_id returned in the API response, or pass your own identifier to the external_send_id field. An example of a value you may choose to pass to that field may be an order ID, where after completing order 1234, an order confirmation message is triggered to the user through Braze, and external_send_id : 1234 is included in the request. All following event postbacks such as Sent and Delivered will include external_send_id : 1234 in the payload allowing you to confirm that user successfully received their order confirmation email.

To get started using the Transactional HTTP Event Postback, navigate to Settings > Workspace Settings > Email Preferences. in your Braze dashboard and input your desired URL to receive postbacks.

Note: If you are using our older navigation, Email Preferences can be found at **Manage Settings > Email Settings**.

postback-body

Postback body

// Sent Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "sent",
  "metadata": {
    "received_at": "2020-08-31T18:58:41.000+00:00",
    "enqueued_at": "2020-08-31T18:58:41.000+00:00",
    "executed_at": "2020-08-31T18:58:41.000+00:00",
    "sent_at": "2020-08-31T18:58:42.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Processed Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "processed",
  "metadata": {
    "processed_at": "2020-08-31T18:58:42.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Aborted
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "aborted",
  "metadata": {
    "reason": "User not emailable",
    "aborted_at": "2020-08-31T19:04:51.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Delivered Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "delivered",
  "metadata": {
    "delivered_at": "2020-08-31T18:27:32.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Bounced Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "bounced",
  "metadata": {
    "bounced_at": "2020-08-31T18:58:43.000+00:00",
    "reason": "550 5.1.1 The email account that you tried to reach does not exist",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}

Message status

example-postback

Example postback

// Sent Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "sent",
  "metadata": {
    "received_at": "2020-08-31T18:58:41.000+00:00",
    "enqueued_at": "2020-08-31T18:58:41.000+00:00",
    "executed_at": "2020-08-31T18:58:41.000+00:00",
    "sent_at": "2020-08-31T18:58:42.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Processed Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "processed",
  "metadata": {
    "processed_at": "2020-08-31T18:58:42.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Aborted
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "aborted",
  "metadata": {
    "reason": "User not emailable",
    "aborted_at": "2020-08-31T19:04:51.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Delivered Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "delivered",
  "metadata": {
    "delivered_at": "2020-08-31T18:27:32.000+00:00",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}
// Bounced Event
{
  "dispatch_id": "acf471119f7449d579e8089032003ded",
  "status": "bounced",
  "metadata": {
    "bounced_at": "2020-08-31T18:58:43.000+00:00",
    "reason": "550 5.1.1 The email account that you tried to reach does not exist",
    "campaign_api_id": "417220e4-5a2a-b634-7f7d-9ec891532368",
    "external_send_id" : "34a2ceb3cf6184132f3d816e9984269a"
  }
}

parameters

Parameters

• connection (BrazeEx.Connection): Connection to server
• campaign_id (String.t):
• opts (keyword): Optional parameters
  • :"Content-Type" (String.t):
  • :Authorization (String.t):
  • :body (String.t):

returns

Returns

• {:ok, nil} on success
• {:error, Tesla.Env.t} on failure