Event

注意

このドキュメントは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	このイベントの種別を送信します。対象イベント queued, succeeded, failed, deferred を通知する場合、値は deliveries です。対象イベント bounced を通知する場合、値は bounces です。
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 を両方受信した場合、重複したデータを受信することとなります。