BrazeEx.Api.MessagingSendMessages (braze_ex v1.0.1)
API calls for all endpoints tagged MessagingSendMessages
.
Link to this section Summary
Functions
Sending Campaign Messages 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.
Sending Canvas Messages 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.
Sending Messages Immediately via API Only
This endpoint allows you send your messages using our API. Be sure to include Messaging Objects in your body to complete your requests.
Create Send IDs For Message Send Tracking
Braze’s Send Identifier adds the ability to send messages and track message performance entirely programmatically, 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.
Sending Transactional Email via API Triggered Delivery
The Send Transactional Email endpoint allows you to send immediate, ad-hoc messages to a designated user. This endpoint is used alongside the creation of a Transactional Email campaign and corresponding campaign ID.
Link to this section Functions
campaigns_trigger_send_post(connection, opts \\ [])
@spec campaigns_trigger_send_post( Tesla.Env.client(), keyword() ) :: {:ok, nil} | {:error, Tesla.Env.t()}
sending-campaign-messages-via-api-triggered-delivery
Sending Campaign Messages 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.
The send endpoint allows you to send immediate, ad-hoc messages to designated users. 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.
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
Parameter | Required | Data Type | Description |
---|---|---|---|
campaign_id | Required | String | See campaign identifier. |
send_id | Optional | String | See send identifier. |
trigger_properties | Optional | Object | See trigger properties. Personalization key-value pairs that will apply to all users in this request. |
broadcast | Optional | Boolean | See broadcast. This parameter defaults to false (as of August 31, 2017). <br> <br>If recipients is omitted, broadcast must be set to true. However, use caution when setting broadcast: true , as unintentionally setting this flag may cause you to send your campaign to a larger than expected audience. |
audience | Optional | Connected audience object | See connected audience. |
recipients | Optional | Array | See recipients object. If not provided and broadcast is set to true, the message will send to the entire segment targeted by the campaign. |
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.
For more information on the "broadcast" flag, check out Broadcast within our API Parameters documentation.
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 serveropts
(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
canvas_trigger_send_post(connection, opts \\ [])
@spec canvas_trigger_send_post( Tesla.Env.client(), keyword() ) :: {:ok, nil} | {:error, Tesla.Env.t()}
sending-canvas-messages-via-api-triggered-delivery
Sending Canvas Messages 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.
This endpoint allows you to send Canvas messages via API-Triggered delivery, allowing you to decide what action should trigger the message to be sent. 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
Parameter | Required | Data Type | Description |
---|---|---|---|
canvas_id | Required | String | See Canvas identifier. |
canvas_entry_properties | Optional | Object | See Canvas entry properties. Personalization key-value pairs that will apply to all users in this request. The Canvas entry properties object has a maximum size limit of 50 KB. |
broadcast | Optional | Boolean | See Broadcast. This parameter defaults to false (as of August 31, 2017). <br> <br>If recipients is omitted, broadcast must be set to true. However, use caution when setting broadcast: true , as unintentionally setting this flag may cause you to send your Canvas to a larger than expected audience. |
audience | Optional | Connected audience object | See Connected audience. |
recipients | Optional | Array | See Recipients object. If not provided and broadcast is set to true, the message will send to the entire segment targeted by the Canvas. <br> <br>The recipients array may contain up to 50 objects, with each object containing a single external_user_id string and canvas_entry_properties object. Either external_user_id or user_alias is required for this call. Requests must specify only one. <br> <br>When send_to_existing_only is true, Braze will only send the message to existing users—however this flag can’t be used with user aliases. 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. |
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 serveropts
(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
messages_send_post(connection, opts \\ [])
@spec messages_send_post( Tesla.Env.client(), keyword() ) :: {:ok, nil} | {:error, Tesla.Env.t()}
sending-messages-immediately-via-api-only
Sending Messages Immediately via API Only
This endpoint allows you send your messages using our API. Be sure to include Messaging Objects in your body to complete your requests.
The send endpoint allows you to send immediate, ad-hoc messages to designated users. If you are targeting a segment, a record of your request will be stored in the Developer Console.
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
Parameter | Required | Data Type | Description |
---|---|---|---|
broadcast | Optional | Boolean | See broadcast. This parameter defaults to false (as of August 31, 2017). <br> <br>If recipients is omitted, broadcast must be set to true. However, use caution when setting broadcast: true , as unintentionally setting this flag may cause you to send your messages to a larger than expected audience. |
external_user_ids | Optional | Array of strings | See external user ID. |
user_aliases | Optional | Array of user alias objects | See user alias object. |
segment_id | Optional | String | See segment identifier. |
audience | Optional | Connected audience object | See connected audience. |
campaign_id | Optional* | String | See campaign identifier for more information. <br> <br>*Required if you wish to track campaign stats (e.g. sends, clicks, bounces, etc) on the Braze dashboard. |
send_id | Optional | String | See send identifier |
override_frequency_capping | Optional | Boolean | Ignore frequency_capping for campaigns, defaults to false. |
recipient_subscription_state | Optional | String | Use this to send messages to only users who have opted in (opted_in ), only users who have subscribed or are opted in (subscribed ) or to all users, including unsubscribed users (all ). <br> <br>Using all users is useful for transactional email messaging. Defaults to subscribed . |
messages | Optional | Messaging objects | See available messaging objects. |
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 serveropts
(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
sends_id_create_post(connection, opts \\ [])
@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
Braze’s Send Identifier adds the ability to send messages and track message performance entirely programmatically, 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.
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
Parameter | Required | Data Type | Description |
---|---|---|---|
campaign_id | Required | String | See campaign identifier. |
send_id | Optional | String | See send identifier. |
response
Response
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
"message": "success",
"send_id" : "example_send_id"
}
parameters
Parameters
connection
(BrazeEx.Connection): Connection to serveropts
(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
transactional_v1_campaigns_yourcampaignidhere_send_post(connection, opts \\ [])
@spec transactional_v1_campaigns_yourcampaignidhere_send_post( Tesla.Env.client(), keyword() ) :: {:ok, nil} | {:error, Tesla.Env.t()}
sending-transactional-email-via-api-triggered-delivery
Sending Transactional Email via API Triggered Delivery
The Send Transactional Email endpoint allows you to send immediate, ad-hoc 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.
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.
request-parameters
Request Parameters
Parameter | Required | Data Type | Description |
---|---|---|---|
external_send_id | Optional | String | A Base64 compatible string. Validated against the following regex /^[a-zA-Z0-9-_+/=]+$/ . This optional field allows you to pass an internal identifier for this particular send which will be included in events sent from the Transactional HTTP event postback. When passed, this identifier will also be used as a deduplication key, which Braze will store for 24 hours. Passing the same identifier in another request will not result in a new instance of a send by Braze for 24 hours. |
trigger_properties | Optional | Object | See trigger properties. Personalization key-value pairs that will apply to the user in this request. |
recipients | Required | Object | The user you are targeting this message to. Can contain attributes and a single external_user_id or user_alias . <br> <br>Note that if you provide an external user ID that doesn’t already exist in Braze, passing any fields to the attributes object will create this user profile in Braze and send this message to the newly created user. <br> <br>If you send multiple requests to the same user with different data in the attributes object, Braze will ensure that first_name , last_name , and email attributes will be updated synchronously and templated into your message. Custom attributes don’t have this same protection, so proceed with caution when updating a user through this API and passing different custom attribute values in quick succession. |
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
}
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 Manage Settings > Email Settings > Transactional Webpush URL in your Braze dashboard and input your desired URL to receive postbacks.
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
Status | Description |
---|---|
sent | Message successfully dispatched to Braze’s email sending partner |
processed | Email sending partner has successfully received and prepared the message for sending to the user’s inbox provider |
aborted | Braze was unable to successfully dispatch the message due to the user not having an emailable address, or Liquid abort logic was called in the message body. All aborted events include a reason field within the metadata object indicating why the message was aborted |
delivered | Message was accepted by the user’s email inbox provider |
bounced | Message was rejected by the user’s email inbox provider. All bounced events include a reason field within the metadata object reflecting the bounce error code provided by the inbox provider |
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 serveropts
(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