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 mais detalhes.
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
O endpoint /transactional/v1/campaigns/{campaign_id}/send é um endpoint pago em unidades por hora (por exemplo, 50.000 por hora, dependendo do seu pacote). Não há limite de taxa separado por endpoint: você pode enviar além do seu volume alocado, mas apenas o volume alocado é coberto pelo SLA. As solicitações para este endpoint contam para o seu limite geral de taxa da API externa. Se você exceder esse limite (por exemplo, 250.000 solicitações por hora em todos os endpoints), a Braze retorna 429 e as solicitações são limitadas. A contagem do volume transacional é redefinida a cada hora, então após uma hora, outra alocação está disponível. Dentro do volume coberto pelo SLA, 99,9% dos e-mails serão enviados em menos de um minuto.
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 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 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 are 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-_+\/=]+$/ Este campo opcional permite que você passe um identificador interno para este envio específico, que é incluído em eventos enviados do postback de evento HTTP Transacional. Quando passado, este identificador também é usado como uma chave de deduplicação, que a Braze armazena por 24 horas. Passar o mesmo identificador em outra solicitação não resulta em uma nova instância de envio pela Braze por 24 horas. |
trigger_properties |
Opcional | Objeto | Consulte propriedades do disparador. Pares de chave-valor de personalização que se aplicam ao usuário nesta 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.Observe que se você fornecer um ID de usuário externo que não existe na Braze, passar quaisquer campos para o objeto attributes cria este perfil de usuário na Braze e envia esta 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, os atributos first_name, last_name e email são atualizados de forma síncrona e templateados em 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 de envio de e-mail transacional responde com o dispatch_id da mensagem, que representa a instância deste envio de mensagem. 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 você pretende 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 na Braze tem uma implementação de limite de frequência que retorna um código de resposta 429 se você fizer muitas solicitações. O endpoint de envio transacional tem uma alocação horária paga medida em unidades (por exemplo, 50.000 unidades por hora, dependendo do seu pacote). Não há um limite de frequência separado por endpoint para este endpoint: você pode enviar além do seu volume alocado, mas apenas o volume alocado é coberto pelo SLA; solicitações acima dessa alocação ainda são enviadas, mas não são cobertas pelo SLA. As solicitações para este endpoint contam para o seu limite geral de taxa de API externa. Se você exceder esse limite (por exemplo, 250.000 solicitações por hora em todos os endpoints), a Braze retorna 429 e limita as solicitações até que o limite seja redefinido. A contagem de volume transacional é redefinida a cada hora. Entre em contato com o suporte da Braze se precisar de mais informações sobre essa funcionalidade.
Postback de evento HTTP transacional
Todos os e-mails de transação são complementados com postbacks de status de evento enviados como uma solicitação HTTP de volta ao URL especificado. Isso permite analisar o status da mensagem em tempo real e tomar providências para alcançar o usuário por outros canais se a mensagem não for entregue ou voltar para o sistema interno, caso a Braze esteja enfrentando um período com latência.
Você pode associar essas atualizações a mensagens individuais usando identificadores exclusivos:
dispatch_id: Um ID exclusivo que o Braze gera automaticamente para cada mensagem.external_send_id: Um identificador personalizado que você fornece, como um número de pedido, para combinar atualizações com seus sistemas internos.
Por exemplo, se você incluir external_send_id: 1234 na solicitação ao enviar um e-mail de confirmação de pedido, todos os postbacks de eventos subsequentes para esse e-mail—como Sent ou Delivered—incluirão external_send_id: 1234. Isso permite que você confirme se o cliente do pedido #1234 recebeu seu e-mail de confirmação de pedido.
Configurando postbacks
No seu painel do Braze:
- Acesse Configurações > Preferências de e-mail.
- Em Status do Evento Transacional Postback, insira a URL onde o Braze deve enviar atualizações de status para seus e-mails transacionais.
- Teste o postback.

Corpo do postback
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),
}
}
Status da mensagem
| Status | Descrição |
|---|---|
sent |
Mensagem enviada com sucesso para um parceiro de envio de e-mail do Braze |
processed |
O parceiro de envio de e-mail recebeu e preparou com êxito a mensagem para envio ao provedor da caixa de entrada do usuário |
aborted |
O Braze não conseguiu enviar a mensagem com êxito porque o usuário não tinha um endereço de e-mail ou a lógica de abortamento do Liquid foi chamada no corpo da mensagem. Todos os eventos abortados incluem um campo reason no objeto de metadados, indicando por que a mensagem foi abortada |
delivered |
A mensagem foi aceita pelo provedor da caixa de entrada de e-mail do usuário |
bounced |
A mensagem foi rejeitada pelo provedor da caixa de entrada de e-mail do usuário. Todos os eventos de bounce incluem um campo reason no objeto de metadados que reflete o código de erro de bounce fornecido pelo provedor da caixa de entrada |
Exemplo de 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"
}
}
Editar esta página no GitHub