システム連携にはいくつかの方法があります。まず一つはAPIを公開し、外部のシステムから呼んでもらうという方法です。これはCustomers Mail Cloudで言えばメール送信APIが該当するでしょう。このAPIによるシステム連携は、一対多の構成において有効です。API公開側はリクエストを待っていれば良く、API利用側も使う際にアクセスすれば良いだけです。API型の欠点として、情報のリアルタイムな送受信に問題があります。API利用側は新しいデータがあるのかどうか、リクエストしてみなければ分かりません。その頻度も毎分なのか、毎時間なのかリクエスト側に依存します。
その欠点を補う存在として注目されているのがWebhookです。Webhookは利用側があらかじめ特定のURLを指定します。そしてシステムに何かアクションがあれば、その指定したURLを呼び出してもらうのです。データを利用する側はリクエストを待っていれば良く、定期的なデータ存在確認が不要になります。
Customers Mail Cloudではメールの送信状態をWebhookで取得できるようになっています。今回はその実装方法を紹介します。
URLを設定する
まずCustomers Mail CloudのAPI設定画面にてWebhook URLを設定します。これは自分で管理しているサーバを指定します。Webhookは必ずインターネット上に公開されているサーバである必要がありますが、Basic認証や認証キーの設定も可能なので、これらの情報を使ってセキュアに保ってください。
指定できるイベントについて
Customers Mail Cloudはメール送信に関連したイベントをWebhookで通知できます。
- bounced
配信完了 - queued
送信キューに登録 - succeeded
送信成功 - failed
送信失敗 - deferred
送信延期
送信ステータスについて細かく取ることも、逆にbouncedだけを取得して送信完了したという情報だけを得ることもできます。
リクエストされる内容
Webhookは指定したURLに対してPOSTメソッドでリクエストされます。その際のリクエストボディーは次のようになっています。
| キー | 説明 |
|---|---|
| server_composition | サーバ構成名。sandboxなど |
| event_type | deliveriesまたはbounces |
| event | イベント内容。文字列ですが、中身はJSONの配列となっています |
eventキーの内容はさらに次のようになっています。キーの下は配列です。
| キー | 説明 |
|---|---|
| (キー) | deliveriesまたはbounces |
| reason | エラーの原因など |
| sourceIp | IPアドレス |
| created | 送信処理日時 |
| envelopeTo | 宛先 |
| subject | 件名 |
| messageId | メッセージID |
| envelopeFrom | 送信元 |
| senderIp | 送信者のIPアドレス |
| status | queued、succeededなど。Webhookのイベント同じ |
例えばメール送信完了した際には次のようなリクエストボディーが送られてきます。eventキー以下をJSONとしてパースすれば、詳細な情報が分かるようになっています。
{
server_composition: 'sandbox',
event_type: 'deliveries',
event: '{"deliveries":[{"reason":"","sourceIp":"","created":"2019-05-28 ' +
'09:59:12","envelopeTo":"test@smtps.jp","subject":"テストメール","messageId":"\\u003C301456480.14899.1559005150211@mta01.sandbox.smtps.jp\\u003E","envelopeFrom":"info@return.sandbox.smtps.jp","senderIp":"153.149.8.217","status":"succeeded"}]}'
}
まとめ
Webhookを使うことで、逐一データを取りに行くことなく最新の情報が得られるようになります。ぜひ皆さんのシステム連携にお役立てください。
※実際にWebhookでエラー情報を連携する方法もアップしてありますので、参考にして下さい。 blog.smtps.jp
