Skip to content

API トリガー配信でトランザクションメールを送信する

post

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

このエンドポイントを使用して、指定したユーザーに即時の単発トランザクション・メッセージを送信する。

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

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

See me in Postman

前提条件

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

レート制限

パスパラメーター

要求本文:

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 で応答します。この識別子は、トランザクション 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に待ち時間が発生している場合は内部システムにフォールバックしたりすることができる。

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

トランザクションHTTPイベントポストバックの使用を開始するには、Brazeダッシュボードの「設定」>「メール設定」を開き、「トランザクションイベントステータスポストバック」のセクションを見つける。ポストバックを受け取りたいURLを入力する。

ポストバック本文

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

メッセージステータス

ポストバックの例

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   GitHub でこのページを編集
「このページはどの程度役に立ちましたか?」
New Stuff!