このドキュメントはAPIバージョン1のAPI仕様です。

最新バージョンのAPI仕様はAPIリファレンスを参照ください。

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",
      "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 である場合に記録されます。
{
  "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で送信したメールが送信エラーとなったことをリアルタイムに検知することができます。 送信エラーは以下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 を両方受信した場合、重複したデータを受信することとなります。