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 キーを生成する必要があります。

レート制限

エンド/transactional/v1/campaigns/{campaign_id}/sendポイントは有料のエンドポイントであり、単位は時間あたりである（例：パッケージに応じて1時間あたり50,000単位）。エンドポイントごとの個別のレート制限は存在しない。割り当てられた容量を超えて送信することは可能だが、SLAの対象となるのは割り当てられた容量のみである。このエンドポイントへのリクエストは、全体の外部APIレート制限にカウントされる。その制限（例えば、全エンドポイントで1時間あたり25万リクエスト）を超えると、Brazeは429を返し、リクエストは制限される。取引量のカウントは毎時リセットされる。したがって、1時間後には新たな割り当てが利用可能になる。SLAの対象範囲内では、メールの99.9%が1分以内に送信される。

パスパラメーター

要求本文:

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

リクエストパラメーター

例のリクエスト

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のレスポンスコードを返す。トランザクション送信エンドポイントには、有料の時間単位割り当てがある。これは単位で測定される（例：パッケージに応じて1時間あたり50,000単位）。このエンドポイントには個別のレート制限はない。割り当てられた量を超えて送信できるが、SLAの対象となるのは割り当て量のみだ。割り当て量を超えるリクエストは送信されるが、SLAの対象外となる。このエンドポイントへのリクエストは、全体の外部APIレート制限にカウントされる。その制限（例えば、全エンドポイントで1時間あたり25万リクエスト）を超過した場合、Brazeは429を返し、制限がリセットされるまでリクエストを制限する。取引件数は毎時リセットされる。この機能についてさらに情報が必要な場合は、Brazeサポートに連絡せよ。

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

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

一意の識別子を使って、これらの更新を個々のメッセージに関連付けることができる：

  • dispatch_id:Brazeが各メッセージに自動的に生成するユニークなID。
  • external_send_id:顧客の内部システムと更新を一致させるために、顧客が提供する識別子（注文番号など）。

例えば、注文確認メールを送信する際、リクエストにexternal_send_id: 1234 を含めると、そのメールに対するその後のすべてのイベントポストバック（Sent やDeliveredのようなもの）にはexternal_send_id: 1234 が含まれる。これにより、注文番号#1234の顧客が注文確認メールを受け取ったかどうかを確認することができる。

ポストバックの設定

Brazeダッシュボードで：

  1. [設定] > [メール設定] に移動します。
  2. トランザクションイベントステータスポストバックに、Brazeがトランザクションメールのステータス更新を送信するURLを入力する。
  3. ポストバックをテストする。

ポストバック本文

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!