Transaktions-E-Mails mit API-getriggerter Zustellung senden

Verwenden Sie diesen Endpunkt, um sofortige, einmalige transaktionsbezogene Nachrichten an eine:n bestimmte:n Nutzer:in zu senden.

Dieser Endpunkt wird zusammen mit der Erstellung einer Braze-Transaktions-E-Mail-Campaign und der entsprechenden Campaign-ID verwendet.

Wichtig

Transaktions-E-Mails sind derzeit als Teil ausgewählter Braze-Pakete verfügbar. Wenden Sie sich für weitere Informationen an Ihren Braze-Customer-Success-Manager.

Ähnlich wie beim Endpunkt zum Senden getriggerter Campaigns können Sie mit diesem Campaign-Typ den Nachrichteninhalt im Braze-Dashboard hinterlegen und gleichzeitig über Ihre API festlegen, wann und an wen eine Nachricht gesendet wird. Im Gegensatz zum Endpunkt „Getriggerte Campaign senden“, der eine Zielgruppe oder ein Segment akzeptiert, an das Nachrichten gesendet werden, muss eine Anfrage an diesen Endpunkt eine:n einzelne:n Nutzer:in entweder über external_user_id oder user_alias angeben, da dieser Campaign-Typ für 1:1-Nachrichten wie Bestellbestätigungen oder Passwortzurücksetzungen konzipiert ist.

Voraussetzungen

Um diesen Endpunkt zu verwenden, müssen Sie einen API-Schlüssel mit der Berechtigung transactional.send generieren.

Rate-Limit

Der /transactional/v1/campaigns/{campaign_id}/send-Endpunkt ist ein kostenpflichtiger Endpunkt, der in Einheiten pro Stunde berechnet wird (zum Beispiel 50.000 pro Stunde, abhängig von Ihrem Paket). Es gibt kein separates Rate-Limit pro Endpunkt: Sie können über Ihr zugewiesenes Volumen hinaus senden, jedoch ist nur das zugewiesene Volumen durch die SLA abgedeckt. Anfragen an diesen Endpunkt werden auf Ihr Gesamt-Rate-Limit für externe API-Anfragen angerechnet. Wenn Sie dieses Limit überschreiten (z. B. 250.000 Anfragen pro Stunde über alle Endpunkte hinweg), gibt Braze den Statuscode 429 zurück und die Anfragen werden gedrosselt. Das Transaktionsvolumen wird stündlich zurückgesetzt, sodass nach einer Stunde ein neues Kontingent verfügbar ist. Innerhalb des vom SLA abgedeckten Volumens werden 99,9 % der E-Mails in weniger als einer Minute versendet.

Pfad-Parameter

Anfragetext

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

Anfrage-Parameter

Beispielanfrage

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

Antwort

Der Endpunkt „Transaktions-E-Mails senden“ antwortet mit der dispatch_id der Nachricht, die die Instanz dieses Versands darstellt. Dieser Bezeichner kann zusammen mit den Ereignissen aus dem Transactional-HTTP-Event-Postback verwendet werden, um den Status einer einzelnen E-Mail zu verfolgen, die an eine:n einzelne:n Nutzer:in gesendet wurde.

Beispielantworten

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
}

Fehlerbehebung

Der Endpunkt kann in einigen Fällen auch einen Fehlercode und eine lesbare Nachricht zurückgeben, wobei es sich meist um Validierungsfehler handelt. Hier finden Sie einige häufige Fehler, die bei ungültigen Anfragen auftreten können.

Die meisten Endpunkte bei Braze verfügen über eine Rate-Limit-Implementierung, die einen 429-Antwortcode zurückgibt, wenn zu viele Anfragen gestellt werden. Der Endpunkt für den Transaktionsversand verfügt über ein bezahltes Stundenkontingent, das in Einheiten gemessen wird (beispielsweise 50.000 Einheiten pro Stunde, abhängig von Ihrem Paket). Für diesen Endpunkt gibt es kein separates Rate-Limit pro Endpunkt: Sie können über Ihr zugewiesenes Volumen hinaus senden, jedoch wird nur das zugewiesene Volumen durch die SLA abgedeckt. Anfragen, die über dieses Kontingent hinausgehen, werden weiterhin gesendet, sind jedoch nicht durch die SLA abgedeckt. Anfragen an diesen Endpunkt werden auf Ihr Gesamt-Rate-Limit für externe API-Anfragen angerechnet. Wenn Sie dieses Limit überschreiten (beispielsweise 250.000 Anfragen pro Stunde über alle Endpunkte hinweg), gibt Braze den Statuscode 429 zurück und drosselt die Anfragen, bis das Limit zurückgesetzt wird. Das Transaktionsvolumen wird stündlich zurückgesetzt. Wenden Sie sich an den Braze-Support, wenn Sie weitere Informationen zu dieser Funktion benötigen.

Transaktionelles HTTP-Ereignis-Postback

Alle Transaktions-E-Mails werden durch Ereignisstatus-Postbacks ergänzt, die als HTTP-Anfrage an die von Ihnen angegebene URL zurückgesendet werden. So können Sie den Status der Nachricht in Realtime auswerten und Maßnahmen ergreifen, um Nutzer:innen auf einem anderen Kanal zu erreichen, wenn die Nachricht nicht zugestellt wurde, oder auf ein internes System als Fallback zurückgreifen, wenn Braze eine Latenz aufweist.

Sie können diese Updates über eindeutige Bezeichner mit einzelnen Nachrichten verknüpfen:

• dispatch_id: Eine eindeutige ID, die Braze automatisch für jede Nachricht generiert.
• external_send_id: Ein angepasster Bezeichner, den Sie angeben, z. B. eine Bestellnummer, um Updates mit Ihren internen Systemen abzugleichen.

Wenn Sie beispielsweise external_send_id: 1234 in die Anfrage beim Versenden einer Bestellbestätigungs-E-Mail aufnehmen, enthalten alle nachfolgenden Ereignis-Postbacks für diese E-Mail – wie Sent oder Delivered – den Wert external_send_id: 1234. Damit können Sie bestätigen, ob die Kund:in für Bestellung #1234 die Bestellbestätigungs-E-Mail erhalten hat.

Einrichten von Postbacks

In Ihrem Braze-Dashboard:

1. Gehen Sie zu Einstellungen > E-Mail-Präferenzen.
2. Geben Sie unter Transactional Event Status Postback die URL ein, an die Braze Status-Updates für Ihre Transaktions-E-Mails senden soll.
3. Testen Sie das 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),
   }
}

Nachrichtenstatus

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