Skip to content

Envoyez des e-mails transactionnels en utilisant la réception/distribution déclenchée par l’API.

post

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

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 de Braze et de l’ID de campagne correspondant.

Similaire à l’endpoint de campagne Send triggered, ce type de campagne vous permet d’héberger le contenu du message à l’intérieur du tableau de bord de Braze tout en dictant quand et à qui un message est envoyé via votre API. Contrairement au point de terminaison Send triggered campaign, qui accepte une audience ou un segment auquel envoyer des messages, une demande à ce point de terminaison doit spécifier un utilisateur unique par external_user_id ou user_alias, car ce type de campagne est créé pour l’envoi de messages 1:1 d’alertes telles que des confirmations de commande ou des réinitialisations de mot de passe.

See me in Postman

Conditions préalables

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

Limite de débit

Les e-mails transactionnels de Braze ne sont pas soumis à une limitation du débit. Selon le package que vous avez choisi, un nombre défini d’e-mails transactionnels est couvert par heure par l’accord de niveau de service (SLA). Les requêtes qui dépassent ce taux sont toujours envoyées, mais ne sont pas couvertes par l’accord de niveau de service. 99,9 % des e-mails sont envoyés en moins d’une minute.

Paramètres de chemin

Corps de la demande

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

Paramètres de demande

Exemple de demande

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-mail transactionnel répondra avec le message dispatch_id qui représente l’instance de cet envoi de message. Cet identifiant peut être utilisé avec les événements du postback de l’événement HTTP transactionnel pour tracer le statut d’un e-mail individuel envoyé à un utilisateur unique.

Exemple 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 renvoyer également, dans certains cas, un code d’erreur et un message lisible par un être humain, qui sont souvent des erreurs de validation. Voici quelques-unes des erreurs fréquentes pouvant être obtenues lorsque vous réalisez des requêtes invalides.

La plupart des endpoints Braze ont une implémentation de limites de débit qui renverra un code de réponse 429 si vous avez effectué trop de requêtes. L’endpoint d’envoi transactionnel fonctionne différemment : si vous dépassez la limite de débit qui vous a été attribuée, notre système continuera d’ingérer les appels API, de renvoyer les codes de réussite et d’envoyer les messages, mais ces derniers ne seront peut-être pas soumis à l’accord de niveau de service (SLA) contractuel pour la fonctionnalité. Veuillez nous contacter si vous désirez plus d’informations concernant cette fonctionnalité.

Postback de l’événement HTTP transactionnel

Tous les e-mails transactionnels sont complétés par des postbacks de statut d’événement envoyés en tant que requête HTTP à l’URL 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 reçu ou recourir à 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 est 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, toutes les rétrocessions d’événements ultérieures 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 l’e-mail de confirmation de sa commande.

Mise en place de postbacks

Dans votre tableau de bord de Braze :

  1. Allez dans Paramètres > Préférences e-mail.
  2. Sous Postback d’état d’événement transactionnel, entrez l’URL où Braze doit envoyer des mises à jour d’état pour vos e-mails transactionnels.
  3. Testez le postback.

Corps de 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"
    }
}
Github   Modifier cette page sur GitHub
CETTE PAGE A-T-ELLE ÉTÉ UTILE?
New Stuff!