Skip to content

Envía correos electrónicos transaccionales utilizando la entrega desencadenada por la API

post

/transactional/v1/campaigns/{campaign_id}/send

Utiliza este punto final para enviar mensajes transaccionales inmediatos y puntuales a un usuario designado.

Este punto final se utiliza junto con la creación de una campaña de correo electrónico transaccional Braze y el ID de campaña correspondiente.

Similar al punto final Enviar campaña desencadenada, este tipo de campaña te permite alojar contenido de mensajes dentro del panel de Braze, al tiempo que dicta cuándo y a quién se envía un mensaje a través de tu API. A diferencia del punto final Enviar campaña desencadenada, que acepta una audiencia o segmento al que enviar mensajes, una solicitud a este punto final debe especificar un único usuario, ya sea mediante external_user_id o user_alias, ya que este tipo de campaña está diseñada para la mensajería 1:1 de alertas como confirmaciones de pedidos o restablecimiento de contraseñas.

See me in Postman

Requisitos previos

Para utilizar este punto final, deberás generar una clave de API con el permiso transactional.send.

Límite de velocidad

Parámetros de la ruta

Cuerpo de la solicitud

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 la solicitud

Ejemplo de solicitud

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

Respuesta

El punto final Enviar correo electrónico transaccional responderá con el dispatch_id del mensaje que representa la instancia de este envío de mensaje. Este identificador puede utilizarse junto con los eventos del postback de eventos HTTP transaccionales para rastrear el estado de un correo electrónico individual enviado a un único usuario.

Ejemplos de respuestas

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
}

Solución de problemas

El punto final también puede devolver un código de error y un mensaje legible por humanos en algunos casos, la mayoría de los cuales son errores de validación. Estos son algunos errores comunes que puedes obtener al realizar solicitudes no válidas.

La mayoría de los puntos finales en Braze tienen una implementación de límite de velocidad que devolverá un código de respuesta 429 si has hecho demasiadas peticiones. El punto final de envío transaccional funciona de forma diferente: si superas el límite de tasa asignado, nuestro sistema seguirá ingiriendo las llamadas a la API, devolviendo códigos de éxito y enviando los mensajes; sin embargo, es posible que esos mensajes no estén sujetos al SLA contractual de la característica. Ponte en contacto con nosotros si necesitas más información sobre esta funcionalidad.

Postback de eventos HTTP transaccionales

Todos los correos electrónicos transaccionales se complementan con devoluciones del estado del evento enviadas como una petición HTTP de vuelta a tu URL especificada. Eso te permitirá evaluar el estado del mensaje en tiempo real y tomar medidas para llegar al usuario en otro canal si el mensaje no se acaba entregando, o usar un sistema interno alternativo en caso de que Braze esté experimentando latencia.

Puedes asociar estas actualizaciones a mensajes individuales utilizando identificadores únicos:

  • dispatch_id: Braze genera automáticamente un ID único para cada mensaje.
  • external_send_id: Un identificador personalizado que proporciones, como un número de pedido, para cotejar las actualizaciones con tus sistemas internos.

Por ejemplo, si incluyes external_send_id: 1234 en la solicitud al enviar un correo electrónico de confirmación de pedido, todos los eventos posteriores de ese correo electrónico -como Sent o Delivered- incluirán external_send_id: 1234. Esto te permite confirmar si el cliente del pedido nº 1234 recibió su correo electrónico de confirmación del pedido.

Configuración de los postbacks

En tu panel de Braze:

  1. Vaya a Configuración > Preferencias de correo electrónico.
  2. En Postback de estado de evento transaccional, introduce la URL a la que Braze debe enviar las actualizaciones de estado de tus correos electrónicos transaccionales.
  3. Prueba el postback.

Cuerpo de la devolución

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),
   }
}

Estado del mensaje

Ejemplo de devolución

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"
    }
}
Github   Editar esta página en GitHub
¿QUÉ TAN ÚTIL FUE ESTA PÁGINA?
New Stuff!