Event

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	このイベントの種別を送信します。イベントの種別は、deliveries, bounces, blocks* の3種類があります。
event	Yes	UTF-8	イベント種別ごとに定義したデータをJSON形式で送信します。

メモ

「blocks イベント」は、Proプランにてご利用いただける機能です。ご利用の際は 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"
    },
    ...
]
}

プロパティ	説明
created	メールアドレスに対する配信ステータスを記録した日時（YYYY-MM-DD HH:mm:ss形式）
messageId	メールヘッダのMessage-IDフィールドの値
status	送信するメールの状態を示す配信ステータス
sourceIp	メールリレー元サーバーの接続IP。配信ステータスが queued である場合に記録されます。
senderIp	このメールを宛先サーバーに送信した時に使用したIP。配信ステータスが queued 以外である場合に記録されます。
returnPath	メールを送信するときに使用したエンベロープ Fromアドレス。
from	このメールのヘッダFromアドレス。
to	メールを送信するときに使用したエンベロープ Toアドレス。
subject	メールの件名。
reason	SMTPの応答メッセージ。配信ステータスが failed または deferred である場合に記録されます。
apiData	メール送信元アプリケーションが付与した X-Api-Data のヘッダ値。

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

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"
    }
    ...
]
}

プロパティ	説明
created	バウンスメールを受信した日（YYYY-MM-DD HH:MM:SS形式）
status	どのような理由でメール送信がエラーとなったかを示すエラーステータス
from	メールヘッダのFromに指定されたメールアドレス
to	このメールを送信したメールアドレス
messageId	メールヘッダのMessage-IDフィールドの値
reason	エラーステータスの判定に使用した SMTP応答メッセージまたはバウンスメールの本文
returnPath	メール送信時に使用したエンベローブFrom
subject	エラーとなったメールの件名
apiData	メール送信元アプリケーションが付与した X-Api-Data のヘッダ値

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

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

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

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

event/blocks

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

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"
    },
    ...
]
}

プロパティ	説明
created	配信停止対象のメールアドレスを登録、または、解除した日（YYYY-MM-DD HH:mm:ss形式）
address	操作対象のメールアドレス
status	値と発生の条件を以下に示します。

status値	発生の条件
registered	配信停止が有効である場合、配信停止の実行タイミングが到来した、または、画面上から即時実行を行ったことにより、配信停止の対象となるメールアドレスが登録された場合にこのイベントが通知されます
deleted	配信停止を解除したメールアドレスを通知します。以下の操作を行った際に、このイベントが通知されます。・配信停止画面からの解除操作・Transactional Email Blocks/delete APIの呼び出し・Transactional Email Blocks/cancel APIの呼び出し

送信エラーを受信する

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