Event Webhook は、メールの送信および送信エラーの発生、配信停止の操作などにより発生するイベントを指定したエンドポイントに通知します。

エンドポイントへの通知はイベントデータをリスト化し、設定された通知間隔（デフォルト1秒毎）もしくは最大イベント数（デフォルト100）のいずれかを満たした場合に通知されます。

API設定

Event Webhook を利用するには管理コンソールからAPIを設定する必要があります。

ユーザーガイド→「API」→「Webhook」 を参照し、APIの設定を行ってください。

イベント

Event Webhookは、以下のパラメータをエンドポイントにポストします。

　　メモ

　　　「blocks イベント」は、Business / Enterprise / OEM / Proプランにて
　　　ご利用いただける機能です。
　　　ご利用の際は Business / Enterprise / OEM / Proプランをご契約ください。

event/deliveries

このイベントは、メールリレー元サーバーからメールを受信し、宛先サーバーに対してメール送信を行ったときに発生します。

JSON

{
"deliveries": [
    {
    "created": "2015-12-14 10:53:52",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "senderIp": "",
    "sourceIp": "10.0.24.10",
    "status": "queued",
    "subject": "sample email #1",
    "apiData" : "CMC00123"
    },
    {
    "created": "2015-12-14 10:53:53",
    "returnPath": "envelope-from1@example.com",
    "from" : "header-from1@example.com",
    "to": "to1@example.com",
    "messageId": "\u003C823cb160-a205-11e5-833e-06ff9846521b@node1\u003E",
    "reason": "",
    "sourceIp": "",
    "senderIp": "10.0.24.20",
    "status": "succeeded",
    "subject": "sample email #1",
    "apiData" : "CMC00123"
    },
    ...
]
}

　　ヘッダ値が長いデータを取得される場合の注意点

　　　Email の仕様上、長いヘッダ値をそのまま記載することはできないため、
　　　適宜改行を入れることなります。

　　　複数行にわたるヘッダの場合には、ヘッダの仕様上、2行目以降については
　　　行頭にスペースが入ります。このとき、JSON の文字列等の解釈はしないため、
　　　意図しない箇所にスペースが入ることがあります。

　　　apiDataプロパティ（X-Api-Dataのヘッダ値）などへ長いヘッダ値を
　　　使用する場合には、意図しないスペースを取り除けるように、
　　　JWT化や Base64エンコード等を実施した上で、メール配信することを推奨します。

event/bounces

このイベントは、メール送信が失敗したときに発生します。

JSON

{
"bounces": [
    {
    "from": "from1@example.com",
    "messageId": "\u003C7bedd290-a213-11e5-8344-06ff9846521b@node1\u003E",
    "reason": "host unknown",
    "created": "2015-12-14 12:33:53",
    "status": "1",
    "to": "to1@example.com",
    "returnPath" : "env-from1@example.com",
    "subject" : "サービスに関するお知らせ",
    "apiData" : "CMC00123"
    },
    {
    "from": "from2@example.com",
    "messageId": "\u003dc9633d0-885f-11e5-8329-0638caaed3c7@node1\u003E",
    "reason": "Status:5.1.1 / X-Postfix; unknown user: \"to2@example.com\"",
    "created": "2015-12-14 12:33:53",
    "status": "2",
    "to": "to2@example.com",
    "returnPath" : "env-from2@example.com",
    "subject" : "サービスに関するお知らせ",
    "apiData" : "CMC00124"
    }
    ...
]
}

　　ヘッダ値が長いデータを取得される場合の注意点

　　　Email の仕様上、長いヘッダ値をそのまま記載することはできないため、
　　　適宜改行を入れることなります。

　　　複数行にわたるヘッダの場合には、ヘッダの仕様上、2行目以降については
　　　行頭にスペースが入ります。このとき、JSON の文字列等の解釈はしないため、
　　　意図しない箇所にスペースが入ることがあります。

　　　apiDataプロパティ（X-Api-Dataのヘッダ値）などへ長いヘッダ値を
　　　使用する場合には、意図しないスペースを取り除けるように、
　　　JWT化や Base64エンコード等を実施した上でメール配信することを推奨します。

event/blocks（Business / Enterprise / OEM / Pro）

このイベントは、配信停止とするメールアドレスを登録、または、削除した時に発生します。

JSON

{
"blocks": [
    {
    "created": "2015-12-14 10:53:52",
    "address" : "to1@example.com",
    "status": "registered"
    },
    {
    "created": "2015-12-14 10:53:52",
    "address" : "to2@example.com",
    "status": "deleted"
    },
    ...
]
}

送信エラーを受信する

Event Webhook の代表的な利用方法として、SMTPまたはAPIで送信したメールが送信エラーとなったことをリアルタイムに検知することができます。送信エラーは以下2つの方法で検知することができます。

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 を
　　　両方受信した場合、重複したデータを受信することとなります。