Envoyer des e-mails transactionnels via la distribution déclenchée par l’API

Utilisez cet endpoint pour envoyer des messages transactionnels immédiats et ponctuels à un utilisateur désigné.

Cet endpoint est utilisé parallèlement à la création d’une campagne d’e-mails transactionnels Braze et de l’ID de campagne correspondant.

Important

L’e-mail transactionnel est actuellement disponible dans certains forfaits Braze. Contactez votre gestionnaire de la satisfaction client Braze pour plus de détails.

Similaire à l’endpoint d’envoi de campagne déclenchée, ce type de campagne vous permet d’héberger le contenu du message dans le tableau de bord de Braze tout en dictant quand et à qui un message est envoyé via votre API. Contrairement à l’endpoint d’envoi de campagne déclenchée, qui accepte une audience ou un segment auquel envoyer des messages, une requête à cet endpoint doit spécifier un utilisateur unique par external_user_id ou user_alias, car ce type de campagne est conçu pour l’envoi de messages 1:1 d’alertes telles que des confirmations de commande ou des réinitialisations de mot de passe.

Conditions préalables

Pour utiliser cet endpoint, vous devrez générer une clé API avec l’autorisation transactional.send.

Limite de débit

L’endpoint /transactional/v1/campaigns/{campaign_id}/send est un endpoint payant facturé en unités par heure (par exemple, 50 000 par heure selon votre forfait). Il n’existe pas de limite de débit distincte par endpoint : vous pouvez envoyer au-delà du volume qui vous est alloué, mais seul le volume alloué est couvert par le SLA. Les requêtes adressées à cet endpoint sont prises en compte dans votre limite de débit globale de l’API externe. Si vous dépassez cette limite (par exemple, 250 000 requêtes par heure sur l’ensemble des endpoints), Braze renvoie une erreur 429 et les requêtes sont limitées. Le compteur de volume transactionnel est réinitialisé toutes les heures, de sorte qu’après une heure, un nouveau contingent est disponible. Dans le cadre du volume couvert par le SLA, 99,9 % des e-mails seront envoyés en moins d’une minute.

Paramètres de chemin

Corps de la requête

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

Paramètres de requête

Exemple de requête

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

Réponse

L’endpoint d’envoi d’e-mails transactionnels répond avec le dispatch_id du message, qui représente l’instance de cet envoi de message. Cet identifiant peut être utilisé avec les événements du postback d’événement HTTP transactionnel pour suivre le statut d’un e-mail individuel envoyé à un utilisateur unique.

Exemples de réponses

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
}

Résolution des problèmes

L’endpoint peut également renvoyer, dans certains cas, un code d’erreur et un message lisible par un être humain, qui sont le plus souvent des erreurs de validation. Voici quelques erreurs courantes que vous pouvez obtenir lorsque vous effectuez des requêtes invalides.

La plupart des endpoints de Braze disposent d’une implémentation de limite de débit qui renvoie un code de réponse 429 si vous effectuez un nombre excessif de requêtes. L’endpoint d’envoi transactionnel dispose d’un quota horaire payant mesuré en unités (par exemple, 50 000 unités par heure, selon votre forfait). Il n’existe pas de limite de débit distincte par endpoint pour cet endpoint : vous pouvez envoyer au-delà du volume qui vous est alloué, mais seul ce volume est couvert par le SLA ; les requêtes dépassant cette allocation sont toujours envoyées, mais ne sont pas couvertes par le SLA. Les requêtes adressées à cet endpoint sont prises en compte dans votre limite de débit globale de l’API externe. Si vous dépassez cette limite (par exemple, 250 000 requêtes par heure sur l’ensemble des endpoints), Braze renvoie un code 429 et limite les requêtes jusqu’à ce que la limite soit réinitialisée. Le compteur de volume transactionnel est réinitialisé toutes les heures. Contactez l’assistance Braze si vous avez besoin de plus amples informations sur cette fonctionnalité.

Postback d’événement HTTP transactionnel

Tous les e-mails transactionnels sont complétés par des postbacks de statut d’événement envoyés sous forme de requête HTTP vers l’URL que vous avez spécifiée. Cela vous permet d’évaluer le statut du message en temps réel et de prendre des mesures pour atteindre l’utilisateur sur un autre canal si le message n’est pas distribué, ou de basculer vers un système interne si Braze connaît une certaine latence.

Vous pouvez associer ces mises à jour à des messages individuels à l’aide d’identifiants uniques :

• dispatch_id : un ID unique généré automatiquement par Braze pour chaque message.
• external_send_id : un identifiant personnalisé que vous fournissez, tel qu’un numéro de commande, pour faire correspondre les mises à jour avec vos systèmes internes.

Par exemple, si vous incluez external_send_id: 1234 dans la requête lors de l’envoi d’un e-mail de confirmation de commande, tous les postbacks d’événements ultérieurs pour cet e-mail — comme Sent ou Delivered — incluront external_send_id: 1234. Cela vous permet de confirmer que le client de la commande n°1234 a bien reçu son e-mail de confirmation de commande.

Mise en place des postbacks

Dans votre tableau de bord de Braze :

1. Allez dans Paramètres > Préférences des e-mails.
2. Sous Transactional Event Status Postback, saisissez l’URL vers laquelle Braze doit envoyer les mises à jour de statut pour vos e-mails transactionnels.
3. Testez le postback.

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

Statut du message

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