このドキュメントはAPIバージョン1のAPI仕様です。
最新バージョンのAPI仕様はAPIリファレンスを参照ください。
Event Webhook は、メールの配信状況をエンドポイントに通知します。
エンドポイントへの通知はイベントデータをリスト化した上で、設定された通知間隔（デフォルト1秒毎）もしくは最大イベント数（デフォルト100）のいずれかを満たした場合に通知されます。
API設定
Event Webhook を利用するには管理コンソールからAPIを設定する必要があります。
ユーザーガイド＞API＞Webhook を参照し、APIの設定を行ってください。
イベント
Event Webhookは、以下のパラメータをエンドポイントにポストします。
パラメータ | 必須 | データ型 | 説明 |
|---|---|---|---|
api_key | No | ASCII | 管理コンソールにてAPIキーの設定を行った場合、指定されたAPIキーを送信します。 |
server_composition | Yes | UTF-8 | このイベントが発生したサーバ構成の名前を送信します。 |
event_type | Yes | ASCII | このイベントの種別を送信します。 |
event | Yes | UTF-8 | メール配信状況のイベントデータをJSON形式で送信します。イベントデータは、deliveries, bounces の２種類があります。 |
event/deliveries
JSON
{
"deliveries": [
{
"created": "2015-12-14 10:53:52",
"envelopeFrom": "from1@example.com",
"envelopeTo": "to1@example.com",
"messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
"reason": "",
"senderIp": "",
"sourceIp": "10.0.24.10",
"status": "queued",
"subject": "sample email #1"
},
{
"created": "2015-12-14 10:53:53",
"envelopeFrom": "from1@example.com",
"envelopeTo": "to1@example.com",
"messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
"reason": "",
"sourceIp": "",
"senderIp": "10.0.24.20",
"status": "succeeded",
"subject": "sample email #1"
},
...
]
}プロパティ | 説明 |
|---|---|
created | 配信ステータスを記録した日時 (YYYY-MM-DD HH:MM:SS形式) |
messageId | メールヘッダのMessage-IDフィールドの値 |
status | 配信ステータス |
sourceIp | メールリレー元サーバの接続IP。配信ステータスが queued の場合に記録されます。 |
senderIp | メール送信時に使用したIP。配信ステータスが queued 以外の場合に記録されます。 |
envelopeFrom | メールを送信するときに使用したエンベロープ Fromアドレス。 |
envelopeTo | メールを送信するときに使用したエンベロープ Toアドレス。 |
subject | メールの件名。 |
reason | SMTPの応答メッセージ。配信ステータスが failed または deferred である場合に記録されます。 |
event/bounces
JSON
{
"bounces": [
{
"from": "from1@example.com",
"messageId": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E",
"reason": "host unknown",
"received": "2015-12-14 12:33:53",
"status": "1",
"to": "to1@example.com"
},
{
"from": "from2@example.com",
"messageId": "\u003dc9633d0-885f-11e5-8329-0638caaed3c7@node1\u003E",
"reason": "Status:5.1.1 / X-Postfix; unknown user: to2@example.com",
"received": "2015-12-14 12:33:53",
"status": "2",
"to": "to2@example.com"
}
...
]
}プロパティ | 説明 |
|---|---|
received | バウンスメールを受信した日 (YYYY-MM-DD HH:MM:SS形式) |
status | エラーステータス |
from | メールヘッダのFromに指定されたメールアドレス |
to | このメールを送信したメールアドレス |
messageId | メールヘッダのMessage-IDフィールドの値 |
reason | エラーステータスの判定に使用した SMTP応答メッセージまたはバウンスメールの本文 |
送信エラーを受信する
Event Webhook の代表的な利用方法として、SMTPまたはAPIで送信したメールが送信エラーとなったことをリアルタイムに検知することができます。送信エラーは以下２つの方法で検知することができます。
bounced イベント
Event Webhook で送信エラーを検知するには bounced イベントを受信します。bounced は、受信サーバがバウンスメールを受信・解析した結果であるエラーステータスと宛先メールアドレスを event/bounces の JSONフォーマットで通知します。
bouncedイベントを受信するには、Customers Mail Cloudでバウンスメールを受信する必要があります。
failed イベント
failed は、リレーサーバと宛先サーバとのSMTP通信処理において、500番台エラーが発生したことを、event/deliveries のJSONフォーマットで通知します。failedイベントは、Customers Mail Cloudでバウンスメールを受信せずとも通知することができます。
メモ
Customers Mail Cloudでバウンスメールを受信する設定になっている、かつ、送信エラーが発生した場合、まずは failed イベントが発生します。次にリレーサーバはバウンスメールを生成・送信します。受信サーバはリレーサーバからバウンスメールを受信し bounced イベントを発生させます。
このため、failed と bounced を両方受信した場合、重複したデータを受信することとなります。
