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 このイベントの種別を送信します。
対象イベント queued, succeeded, failed, deferred を通知する場合、値は deliveries です。
対象イベント bounced を通知する場合、値は bounces です。
event Yes UTF-8 メール配信状況のイベントデータをJSON形式で送信します。イベントデータは、deliveries, bounces の2種類があります。
{
  "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 のヘッダ値。
{
  "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 のヘッダ値

送信エラーを受信する

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