Customers Mail CloudのWebhookは2種類あります。
- メール受信時
- メール送信時
メール送信時は、送信したメールに対してステータスが変わったタイミングで通知が送られるものです。
この時、 application/json を指定しない設定ができます。この時のデータがどうなっているのか紹介します。
受け取るWebhookの設定
管理画面にて、受け取るWebhookを設定できます。設定は以下が用意されています。
- Bounces
- bounced（エラーメールを受け取る）
- Deliveries
- queued（キューに入ったタイミング）
- succeeded（送信完了）
- failed（送信失敗）
- deferred（送信延期）
この中で application/json を指定できます。本記事では指定しなかった場合を想定しています。
Google Apps Scriptによる実装
今回はGoogle Apps Script（以下GAS）でWebhookを受け取った場合について解説します。Google Apps ScriptではdoPost関数を定義して、Webアプリケーションとしてデプロイすることでデータを受け取れます。
function doPost(e) {
// e.postData.getDataAsString() にデータが入ります
}
以下はこの e.postData.getDataAsString() の内容になります。
実際のデータ
実際のデータは各パラメータが&でつながれ、各値と変数名が=で連携された状態になります。いわばクエリーストリングです。
server_composition=pro&event_type=deliveries&event=%7B%22deliveries%22%3A%5B%7B%22reason%22%3A%22%22%2C%22sourceIp%22%3A%22127.0.0.1%22%2C%22returnPath%22%3A%22info%40return.pro.smtps.jp%22%2C%22created%22%3A%222023-02-24+10%3A34%3A49%22%2C%22subject%22%3A%22%E3%83%86%E3%82%B9%E3%83%88%E3%83%A1%E3%83%BC%E3%83%AB%22%2C%22apiData%22%3A%22%22%2C%22messageId%22%3A%22%5Cu003C6d13b6b0-b3e3-11ed-b516-9ca3ba30b181%40mta04.pro.smtps.jp%5Cu003E%22%2C%22from%22%3A%22info%40example.com%22%2C%22to%22%3A%22user%40example.jp%22%2C%22senderIp%22%3A%22%22%2C%22status%22%3A%22queued%22%7D%5D%7D
パースする際には、以下のようにデコードした上で分解します。 event の中身はJSONでパースできるもので、それ以外の場合は文字列として扱います。
const data = e.postData.getDataAsString();
const decode = decodeURIComponent(data);
const params = decode
.split('&')
.map(s => s.split('='))
.reduce((target, obj, index) => {
target[obj[0]] = obj[0] === 'event' ? JSON.parse(obj[1]) : obj[1];
return target;
}, {});
これで以下に示すようなJSONでデータを扱えます。
メール送信した直後
メール送信を行うと、そのデータがキューに入ります。そして、以下のようなWebhookが送られてきます（データは一部マスキングしています）。
{ "event_type": "deliveries", "server_composition": "pro", "event": { "deliveries": [ { "reason": "", "sourceIp": "100.100.100.1", "returnPath": "info@return.pro.smtps.jp", "created": "2023-01-25 14:03:06", "subject": "メールマガジンのテスト", "apiData": "", "messageId": "<031a32d4-06cd-b1ae-9526-011c0b9f1296@example.com>", "from": "info@example.com", "to": "user@example.jp", "senderIp": "", "status": "queued" } ] } }
メール送信完了時
Customers Mail Cloudからメール送信処理が行われると、ステータスが succeeded になったWebhookが送られてきます。
{ "event_type": "deliveries", "server_composition": "pro", "event": { "deliveries": [ { "reason": "", "sourceIp": "", "returnPath": "info@return.pro.smtps.jp", "created": "2023-01-25 14:03:09", "subject": "メールマガジンのテスト", "apiData": "", "messageId": "<031a32d4-06cd-b1ae-9526-011c0b9f1296@example.com>", "from": "info@example.com", "to": "user@example.jp", "senderIp": "100.100.100.3", "status": "succeeded" } ] } }
メール送信失敗時（メールアドレス形式に問題がある場合）
メールアドレスの形式に問題があるなど、送信処理が失敗した場合には以下のようなWebhookが送られてきます。
{ "event_type": "bounces", "server_composition": "pro", "event": { "bounces": [ { "reason": "host unknown", "returnPath": "info@return.pro.smtps.jp", "created": "2023-01-25 14:05:15", "subject": "メールマガジンのテスト", "apiData": "", "messageId": "<8f902ee7-ae65-8711-48a8-2f708cb14205@example.com>", "from": "info@example.com", "to": "user@example", "status": "1" } ] } }
メール送信失敗時（送信先サーバーからエラーが返ってくる場合）
ユーザーが存在しない、メールボックスがいっぱいなど送信先サーバーからエラーが返ってきた場合には、以下のようなJSONが返ってきます。
{ "event_type": "deliveries", "server_composition": "pro", "event": { "deliveries": [ { "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try 5.1.1 double-checking the recipient's email address for typos or 5.1.1 unnecessary spaces. Learn more at 5.1.1 https://support.google.com/mail/?p=NoSuchUser b197-20020a621bce000000b0058b80756b07si311029pfb.3 - gsmtp (in reply to RCPT TO)", "sourceIp": "", "returnPath": "info@return.pro.smtps.jp", "created": "2023-01-25 14:06:06", "subject": "メールマガジンのテスト", "apiData": "", "messageId": "<9e7e564c-ac83-8cd8-2cb4-b9ff2a9f168d@example.com>", "from": "info@example.com", "to": "no-user@example.jp", "senderIp": "100.100.100.3", "status": "failed" } ] } }
エラーとしてのWebhookも送られてきます。上記のものと event_type が異なるので注意してください。
{ "event_type": "bounces", "server_composition": "pro", "event": { "bounces": [ { "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try 5.1.1 double-checking the recipient's email address for typos or 5.1.1 unnecessary spaces. Learn more at 5.1.1 https://support.google.com/mail/?p=NoSuchUser b197-20020a621bce000000b0058b80756b07si311029pfb.3 - gsmtp (in reply to RCPT TO)", "returnPath": "info@return.pro.smtps.jp", "created": "2023-01-25 14:06:07", "subject": "メールマガジンのテスト", "apiData": "", "messageId": "<9e7e564c-ac83-8cd8-2cb4-b9ff2a9f168d@example.com>", "from": "info@example.com", "to": "no-user@example.jp", "status": "2" } ] } }
まとめ
Webhookを使うことで、メール送信ステータスの変化に応じて通知を受け取れるようになります。メールと連携したシステムを開発する際に役立つでしょう。
このWebhookはAPI/SMTP経由どちらでも利用できます。ぜひご利用ください。
