Envoyez des e-mails transactionnels en utilisant la réception/distribution déclenchée par l’API.
/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.
L’e-mail transactionnel est actuellement disponible dans certains forfaits Braze. Contactez votre gestionnaire du succès des clients Braze pour plus d’informations.
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.
Conditions préalables
Pour utiliser cet endpoint, vous devrez générer une clé API avec l’autorisation transactional.send
.
Limite de débit
Braze Transactional Emails are not subject to a rate limit. Depending on your chosen package, a set number of transactional emails is covered per hour by SLA. Requests that exceed that rate will still send, but are not covered by SLA. 99.9% of emails will send in less than one minute.
Paramètres de chemin
Paramètre | Requis | Type de données | Description |
---|---|---|---|
campaign_id |
Requis | Chaîne de caractères | ID de la campagne |
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
Paramètre | Requis | Type de données | Description |
---|---|---|---|
external_send_id |
Facultatif | Chaîne de caractères | Une chaîne de caractères compatible Base64. Validé par rapport aux expressions régulières suivantes :/^[a-zA-Z0-9-_+\/=]+$/ Ce champ facultatif vous permet de transmettre un identifiant interne pour cet envoi particulier, qui sera inclus dans les événements envoyés à partir du postback de l’événement HTTP transactionnel. Lorsqu’il est communiqué, cet identifiant est également utilisé comme clé de déduplication, que Braze conservera pendant 24 heures. Le fait d’indiquer le même identifiant à une autre demande n’entraînera pas de nouvelle instance d’envoi par Braze pendant 24 heures. |
trigger_properties |
Facultatif | Objet | Voir les propriétés du déclencheur. Les paires clé-valeur de personnalisation qui s’appliquent à l’utilisateur de cette demande. |
recipient |
Requis | Objet | L’utilisateur que vous ciblez avec ce message. Peut contenir des attributes et un seul external_user_id ou user_alias .Notez que si vous fournissez un ID utilisateur externe qui n’existe pas déjà dans Braze, la transmission d’un des champs à l’objet attributes aura pour effet de créer ce profil utilisateur dans Braze et d’envoyer ce message à l’utilisateur nouvellement créé. Si vous envoyez plusieurs demandes au même utilisateur avec des données différentes dans l’objet attributes , les attributs first_name , last_name et email seront mis à jour de manière synchrone et intégrés dans votre message. Les attributs personnalisés n’ont pas cette même protection, procédez donc avec prudence lors de la mise à jour d’un utilisateur via cette API et de la transmission des différentes valeurs d’attributs personnalisés en succession rapide. |
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.
Erreur | Résolution des problèmes |
---|---|
The campaign is not a transactional campaign. Only transactional campaigns may use this endpoint |
L’ID de campagne fourni n’est pas pour une campagne transactionnelle. |
The external reference has been queued. Please retry to obtain send_id. |
L’identifiant external_send_id a été créé récemment, essayez un nouvel identifiant external_send_id si vous avez l’intention d’envoyer un nouveau message. |
Campaign does not exist |
L’ID fourni pour la campagne ne correspond pas à une campagne existante. |
The campaign is archived. Unarchive the campaign in order for trigger requests to take effect. |
L’ID de campagne fourni correspond à une campagne archivée. |
The campaign is paused. Resume the campaign in order for trigger requests to take effect. |
L’ID de campagne fourni correspond à une campagne en pause. |
campaign_id must be a string of the campaign api identifier |
L’ID fourni pour la campagne n’est pas dans un format valide. |
Error authenticating credentials |
La clé API fournie est invalide |
Invalid whitelisted IPs |
L’adresse IP qui envoie la demande ne figure pas sur la liste blanche des adresses IP (si elle est utilisée). |
You do not have permission to access this resource |
La clé API n’a pas la permission d’effectuer cette action |
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
All transactional emails are complemented with event status postbacks sent as an HTTP request back to your specified URL. This will allow you to evaluate the message status in real-time and take action to reach the user on another channel if the message goes undelivered, or fallback to an internal system if Braze is experiencing latency.
You can associate these updates with individual messages using unique identifiers:
dispatch_id
: A unique ID Braze automatically generates for each message.external_send_id
: A custom identifier you provide, such as an order number, to match updates with your internal systems.
For example, If you include external_send_id: 1234
in the request when sending an order confirmation email, all subsequent event postbacks for that email—like Sent
or Delivered
—will include external_send_id: 1234
. This allows you to confirm whether the customer for order #1234 received their order confirmation email.
Setting up postbacks
In your Braze dashboard:
- Go to Settings > Email Preferences.
- Under Transactional Event Status Postback, enter the URL where Braze should send status updates for your transactional emails.
- Test the postback.
Postback body
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),
}
}
Message status
Status | Description |
---|---|
sent |
Message successfully dispatched to a Braze email sending partner |
processed |
Email sending partner has successfully received and prepared the message for sending to the user’s inbox provider |
aborted |
Braze was unable to successfully dispatch the message due to the user not having an emailable address, or Liquid abort logic was called in the message body. All aborted events include a reason field within the metadata object indicating why the message was aborted |
delivered |
Message was accepted by the user’s email inbox provider |
bounced |
Message was rejected by the user’s email inbox provider. All bounced events include a reason field within the metadata object reflecting the bounce error code provided by the inbox provider |
Example 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"
}
}