Envie e-mails de transação usando a entrega disparada por API
/transactional/v1/campaigns/{campaign_id}/send
Use esse endpoint para enviar mensagens transacionais únicas e imediatas a um usuário designado.
Esse endpoint é usado juntamente com a criação de uma campanha de e-mail de transação do Braze e o ID de campanha correspondente.
O e-mail de transação está atualmente disponível como parte de alguns pacotes Braze. Entre em contato com seu gerente de sucesso do cliente da Braze para saber mais.
Semelhante ao endpoint Send triggered campaign (Enviar campanha disparada), esse tipo de campanha permite que você abrigue o conteúdo da mensagem dentro do dashboard do Braze e, ao mesmo tempo, dite quando e para quem a mensagem será enviada por meio de sua API. Ao contrário do ponto de extremidade Send triggered campaign (Enviar campanha disparada), que aceita um público ou segmento de mensagens para o qual enviar mensagens, uma solicitação a esse ponto de extremidade deve especificar um único usuário por meio de external_user_id
ou user_alias
, pois esse tipo de campanha foi criado para o envio de mensagens 1:1 de alertas, como confirmações de pedidos ou redefinições de senha.
Pré-requisitos
Para usar esse endpoint, você precisará gerar uma chave de API com a permissão transactional.send
.
Limite de taxa
Parâmetros da jornada
Parâmetro | Obrigatória | Tipo de dados | Descrição |
---|---|---|---|
campaign_id |
Obrigatória | String | ID da campanha |
Corpo da solicitação
1
2
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
1
2
3
4
5
6
7
8
9
10
11
{
"external_send_id": (optional, string) see the following request parameters,
"trigger_properties": (optional, object) personalization key-value pairs that will apply to the user in this request,
"recipient": (required, object)
{
// Either "external_user_id" or "user_alias" is required. Requests must specify only one.
"user_alias": (optional, User alias object) User alias of the user to receive message,
"external_user_id": (optional, string) External identifier of user to receive message,
"attributes": (optional, object) fields in the attributes object will create or update an attribute of that name with the given value on the specified user profile before the message is sent and existing values will be overwritten
}
}
Parâmetros de solicitação
Parâmetro | Obrigatória | Tipo de dados | Descrição |
---|---|---|---|
external_send_id |
Opcional | String | Uma string compatível com Base64. Validado com o seguinte regex:/^[a-zA-Z0-9-_+\/=]+$/ Esse campo opcional permite que você passe um identificador interno para esse envio específico, que será incluído nos eventos enviados a partir do postback de evento HTTP transacional. Quando passado, esse identificador também será usado como uma chave de deduplicação, que a Braze armazenará por 24 horas. Passar o mesmo identificador em outra solicitação não resultará em uma nova instância de um envio do Braze por 24 horas. |
trigger_properties |
Opcional | Objeto | Consulte propriedades do disparador. Pares de valores-chave de personalização que serão aplicados ao usuário nessa solicitação. |
recipient |
Obrigatória | Objeto | O usuário para o qual você está direcionando esta mensagem. Pode conter attributes e um único external_user_id ou user_alias .Note que, se você fornecer um ID de usuário externo que ainda não exista na Braze, a passagem de qualquer campo para o objeto attributes criará esse perfil de usuário na Braze e enviará essa mensagem para o usuário recém-criado. Se você enviar várias solicitações para o mesmo usuário com dados diferentes no objeto attributes , as atribuições first_name , last_name e email serão atualizadas de forma síncrona e modeladas na sua mensagem. Os atributos personalizados não têm essa mesma proteção, portanto, tenha cuidado ao atualizar um usuário por meio dessa API e ao passar diferentes valores de atributos personalizados em rápida sucessão. |
Exemplo de solicitação
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X POST \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer YOUR-REST-API-KEY' \
-d '{
"external_send_id" : YOUR_BASE64_COMPATIBLE_ID
"trigger_properties": {
"example_string_property": YOUR_EXAMPLE_STRING,
"example_integer_property": YOUR_EXAMPLE_INTEGER
},
"recipient": {
"external_user_id": TARGETED_USER_ID_STRING
}
}' \
https://rest.iad-01.braze.com/transactional/v1/campaigns/{campaign_id}/send
Resposta
O endpoint “Enviar e-mail transacional” responderá com a mensagem dispatch_id
, que representa a instância desse envio de mensagens. Esse identificador pode ser usado junto com eventos do postback do evento HTTP transacional para rastrear o status de um e-mail individual enviado a um único usuário.
Exemplos de respostas
1
2
3
4
5
{
"dispatch_id": A randomly-generated unique ID of the instance of this send
"status": Current status of the message
"metadata" : Object containing additional information about the send instance
}
Solução de problemas
O endpoint também pode retornar um código de erro e uma mensagem legível em alguns casos, a maioria dos quais são erros de validação. Aqui estão alguns erros comuns que você pode receber ao fazer solicitações inválidas.
Erro | Solução de problemas |
---|---|
The campaign is not a transactional campaign. Only transactional campaigns may use this endpoint |
O ID de campanha fornecido não é de uma campanha transacional. |
The external reference has been queued. Please retry to obtain send_id. |
O external_send_id foi criado recentemente, tente um novo external_send_id se estiver pretendendo enviar uma nova mensagem. |
Campaign does not exist |
O ID da campanha fornecido não corresponde a uma campanha existente. |
The campaign is archived. Unarchive the campaign in order for trigger requests to take effect. |
O ID da campanha fornecido corresponde a uma campanha arquivada. |
The campaign is paused. Resume the campaign in order for trigger requests to take effect. |
O ID da campanha fornecido corresponde a uma campanha pausada. |
campaign_id must be a string of the campaign api identifier |
O ID da campanha fornecido não é um formato válido. |
Error authenticating credentials |
A chave de API fornecida é inválida |
Invalid whitelisted IPs |
O endereço IP que está enviando a solicitação não está na lista de permissões de IP (se estiver sendo usada) |
You do not have permission to access this resource |
A chave de API usada não tem permissão para realizar essa ação |
A maioria dos endpoints no Braze tem uma implementação de limite de frequência que retornará um código de resposta 429 se você tiver feito muitas solicitações. O endpoint de envio transacional funciona de forma diferente - se você exceder o limite de frequência atribuído, nosso sistema continuará a ingerir as chamadas da API, retornará códigos de sucesso e enviará as mensagens; no entanto, essas mensagens podem não estar sujeitas ao SLA contratual do recurso. Entre em contato se precisar de mais informações sobre essa funcionalidade.
Postback de evento HTTP transacional
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.
You can associate these updates with individual messages using unique identifiers:
dispatch_id
: A unique ID Braze automatically generates for each message.external_send_id
: A custom identifier you provide, such as an order number, to match updates with your internal systems.
For example, If you include external_send_id: 1234
in the request when sending an order confirmation email, all subsequent event postbacks for that email—like Sent
or Delivered
—will include external_send_id: 1234
. This allows you to confirm whether the customer for order #1234 received their order confirmation email.
Setting up postbacks
In your Braze dashboard:
- Go to Settings > Email Preferences.
- Under Transactional Event Status Postback, enter the URL where Braze should send status updates for your transactional emails.
- Test the postback.
Postback body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"dispatch_id": (string, a randomly-generated unique ID of the instance of this send),
"status": (string, Current status of message from the following message status table,
"metadata" : (object, additional information relating to the execution of an event)
{
"external_send_id" : (string, If provided at the time of the request, Braze will pass your internal identifier for this send for all postbacks),
"campaign_api_id" : (string, API identifier of this transactional campaign),
"received_at": (ISO 8601 DateTime string, Timestamp of when the request was received by Braze, only included for events with "sent" status),
"enqueued_at": (ISO 8601 DateTime string, Timestamp of when the request was enqueued by Braze, only included for events with "sent" status),
"executed_at": (ISO 8601 DateTime string, Timestamp of when the request was processed by Braze, only included for events with "sent" status),
"sent_at": (ISO 8601 DateTime string, Timestamp of when the request was sent to the ESP by Braze, only included for events with "sent" status),
"processed_at" : (ISO 8601 DateTime string, Timestamp the event was processed by the ESP, only included for events with "processed" status),
"delivered_at" : (ISO 8601 DateTime string, Timestamp the event was delivered to the user's inbox provider, only included for events with "processed" status),
"bounced_at" : (ISO 8601 DateTime string, Timestamp the event was bounced by the user's inbox provider, only included for events with "bounced" status),
"aborted_at" : (ISO 8601 DateTime string, Timestamp the event was Aborted by Braze, only included for events with "aborted" status),
"reason" : (string, The reason Braze or the Inbox provider was unable to process this message to the user, only included for events with "aborted" or "bounced" status),
}
}
Message status
Status | Description |
---|---|
sent |
Message successfully dispatched to a Braze 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
// 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"
}
}