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

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.

Requisitos previos

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

Límite de velocidad

El punto final /transactional/v1/campaigns/{campaign_id}/send es un punto final de pago por unidades por hora (por ejemplo, 50 000 por hora, dependiendo de tu paquete). No hay un límite de velocidad por punto final independiente: puedes enviar más allá del volumen asignado, pero solo el volumen asignado está cubierto por el SLA. Las solicitudes a este punto final cuentan para tu límite de velocidad de API externa general. Si superas ese límite (por ejemplo, 250 000 solicitudes por hora en todos los puntos finales), Braze devuelve 429 y las solicitudes se limitan. El recuento del volumen transaccional se restablece cada hora, por lo que, transcurrida una hora, hay disponible otra asignación. Dentro del volumen cubierto por el SLA, el 99,9 % de los correos electrónicos se enviarán en menos de un minuto.

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 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 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 de envío de correo electrónico transaccional responde con el mensajedispatch_id que representa la instancia de envío de este 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 de Braze tienen una implementación de límite de velocidad que devuelve un código de respuesta 429 si realizas demasiadas solicitudes. El punto final de envío de transacciones tiene una asignación por hora de pago que se mide en unidades (por ejemplo, 50 000 unidades por hora, dependiendo de tu paquete). No hay un límite de velocidad por punto final independiente para este punto final: puedes enviar más allá del volumen asignado, pero solo el volumen asignado está cubierto por el SLA; las solicitudes que superen esa asignación se envían, pero no están cubiertas por el SLA. Las solicitudes a este punto final cuentan para tu límite de velocidad de API externa general. Si superas ese límite (por ejemplo, 250 000 solicitudes por hora en todos los puntos finales), Braze devuelve 429 y limita las solicitudes hasta que se restablece el límite. El recuento del volumen de transacciones se restablece cada hora. Ponte en contacto con el soporte de Braze 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"
    }
}