Enviar correos electrónicos transaccionales utilizando la entrega desencadenada por la API

Utiliza este punto de conexión para enviar mensajes transaccionales inmediatos y puntuales a un usuario designado.

Este punto de conexión se utiliza junto con la creación de una Campaign de correo electrónico transaccional de Braze y el ID de Campaign correspondiente.

Importante

El correo electrónico transaccional está disponible actualmente como parte de determinados paquetes de Braze. Ponte en contacto con tu administrador del éxito del cliente de Braze para obtener más detalles.

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

Requisitos previos

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

Límite de velocidad

El punto de conexión /transactional/v1/campaigns/{campaign_id}/send es un punto de conexión 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 de conexión independiente: puedes enviar más allá del volumen asignado, pero solo el volumen asignado está cubierto por el SLA. Las solicitudes a este punto de conexión 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 de conexión de envío de correo electrónico transaccional responde con el dispatch_id del mensaje, 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 de conexión 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 de conexión 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 de conexión de envío transaccional 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 de conexión independiente para este punto de conexión: 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 de conexión 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 de conexión), 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 postbacks de estado de eventos enviados como una solicitud HTTP de vuelta a tu URL especificada. Esto te permitirá evaluar el estado del mensaje en tiempo real y tomar medidas para contactar al usuario a través de otro canal si el mensaje no se entrega, o recurrir a un sistema interno alternativo en caso de que Braze esté experimentando latencia.

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

• dispatch_id: un ID único que Braze genera automáticamente para cada mensaje.
• external_send_id: un identificador personalizado que proporcionas, 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 postbacks de 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. Ve a Settings > Email Preferences.
2. En Transactional Event Status Postback, introduce la URL a la que Braze debe enviar las actualizaciones de estado de tus correos electrónicos transaccionales.
3. Prueba el postback.

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

Estado del mensaje

Ejemplo 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"
    }
}