API トリガー配信によるトランザクションメールの送信

このエンドポイントを使用して、指定されたユーザーに 1 回限りのトランザクションメッセージを即時に送信します。

このエンドポイントは、Braze トランザクションメールキャンペーンとそれに対応するキャンペーン ID の作成と同時に使用されます。

送信トリガーキャンペーンエンドポイントと同様に、このキャンペーンタイプでは、APIを介してメッセージをいつ、誰に送信するかを指定しながら、メッセージコンテンツをBrazeダッシュボード内に格納できます。メッセージを送信するオーディエンスまたはセグメントを受け入れる送信トリガーキャンペーンエンドポイントとは異なり、このエンドポイントへのリクエストはまたはで1人のユーザーを指定する必要があります。このキャンペーンタイプはuser_alias、external_user_id注文確認やパスワードリセットなどのアラートを1：1メッセージで送信することを目的として作成されているためです。

前提条件

このエンドポイントを使用するには、transactional.send権限のある API キーを生成する必要があります。

レート制限

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.

パスパラメーター

リクエスト本文

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

リクエストパラメーター

リクエスト例

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

応答

トランザクションメール送信エンドポイントは、dispatch_idこのメッセージ送信のインスタンスを表すメッセージで応答します。この識別子を Transactional HTTP イベントポストバックのイベントと一緒に使用して、1 人のユーザーに送信された個々の電子メールのステータスを追跡できます。

回答例

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
}

トラブルシューティング

エンドポイントは、エラーコードと人間が読めるメッセージを返す場合もありますが、そのほとんどは検証エラーです。無効なリクエストを行うときに発生する可能性のある一般的なエラーは次のとおりです。

Braze のほとんどのエンドポイントには、リクエストが多すぎる場合に 429 応答コードを返すレート制限が実装されています。トランザクション送信エンドポイントの動作は異なります。割り当てられたレート制限を超えると、システムは引き続き API 呼び出しを取り込み、成功コードを返し、メッセージを送信しますが、それらのメッセージは機能の契約上の SLA の対象にならない場合があります。この機能についてさらに情報が必要な場合は、お問い合わせください。

トランザクション HTTP イベントポストバック

すべてのトランザクションメールは、指定されたURLにHTTPリクエストとして送信されるイベントステータスポストバックによって補完されます。これにより、メッセージステータスをリアルタイムで評価でき、メッセージが配信されない場合は別のチャネルでユーザーに到達するためのアクションを実行でき、Braze で遅延が発生した場合は内部システムにフォールバックできます。

受信イベントを特定のsendインスタンスに関連付けるには、dispatch_id APIレスポンスで返されたBrazeをキャプチャして保存するか、external_send_id独自の識別子をフィールドに渡すかを選択できます。このフィールドに渡すことができる値の例としては、注文 ID があります。注文 1234 が完了すると、Braze external_send_id : 1234 を通じてユーザーに注文確認メッセージが送信され、リクエストに含まれます。やなどSent、Deliveredexternal_send_id : 1234以降のすべてのイベントポストバックがペイロードに含まれ、ユーザーが注文確認メールを正常に受信したことを確認できます。

トランザクション HTTP イベントポストバックの使用を開始するには、Braze ダッシュボードの [設定] > [**メール設定]** に移動し、[トランザクションイベントステータスポストバック] セクションを見つけてください。ポストバックを受け取るには、ご希望のURLを入力してください。

/docs/ja/assets/img/transactional_webhook_url.png?658e9f5dbdb24b1c295d7683b2520603

ポストバック本文

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

メッセージステータス

ポストバックの例

```json

//送信済みイベント { “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” } }

//処理済みイベント { “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” } }

//中止されました { “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” } }

//配信イベント { “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” } }

//バウンスイベント { “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” } }

```