Webhook APIを使ってメールを処理する（PHP + Laravel編）

PHP Laravel Webhook 技術情報

Customers Mail Cloudではプログラム側からデータを取得したり、メールを送信するWeb APIの他に、Customers Mail Cloudでメールを受信した時にイベントを伝えてくれるWebhook APIが用意されています。

Webhook APIを使うことで、自前でメールサーバを立てずにメール受信のタイミングでシステムを起動させられるようになります。メールサーバを安定して動作させ続けるのはメンテナンスコストが大きいですが、Customers Mail Cloudを使うことで簡単にメールと連携したシステムが作れるようになるでしょう。

今回はPHP + Laravelを使ってメールを処理する流れを紹介します。

フォーマットはJSONとマルチパートフォームデータ

Webhookの形式として、JSONとマルチパートフォームデータ（multipart/form-data）が選択できます。この二つの違いは、添付ファイルがあるかどうかです。JSONの場合、添付ファイルは送られてきません。メールに添付ファイルがついてくる可能性がある場合は、後者を選択してください。

Webhook設定ダイアログ

今回はJSONフォーマットにおけるWebhook処理について紹介します。

Laravelのコード

Laravelでは以下のように作成します。まず、コントローラーを作成します。

php artisan make:controller MailController

次にルーティングを routes/web.php に追加します。

Route::post('/mails', 'App\Http\Controllers\MailController@index');

このコントローラーではCSRFがあると動かなくなるので、 app/Http/Middleware/VerifyCsrfToken.php にて 除外します。

class VerifyCsrfToken extends Middleware
{
    /**
     * The URIs that should be excluded from CSRF verification.
     *
     * @var array<int, string>
     */
    protected $except = [
        '/mails',
    ];
}

App\Http\Controllers\MailController.php での実装は次のようになります。 $request->input('JSONキーの名前') で送信されてきたデータを受け取れます。

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class MailController extends Controller
{
    public function index (Request $request)
    {
        $subject = $request->input('subject');
        $headers = $request->input('headers');
        $header = $headers[0];
        return response()->json(['status' => 'ok', 'header' => $header['name'], 'subject' => $subject]);
    }
}

具体的なデータ構造は次のようになっています。

{
    "filter": "info@smtps.jp",
    "headers": [
      {name: 'Return-Path', value: '<user@example.com>'},
        :
      {name: 'Date', value: 'Thu, 27 Apr 2023 15:56:26 +0900'}
    ],
    "subject": "Webhookのテスト",
    "envelope-to": "user@smtps.jp",
    "server_composition": "sandbox",
    "html": "<div dir=\\\\\\\\"ltr\\\\\\\\">Webhookのテスト用メールです。<div>...</div></div>",
    "text": "Webhookのテスト用メールです。\\\\\\\\r\\\\\\\\n\\\\\\\\r\\\\\\\\n--\\\\\\\\r\\\\\\\\n...",
    "envelope-from": "info@smtps.jp"
}

Webhookの結果は管理画面で確認

Webhookでデータが送信されたログは管理画面で確認できます。送信時のAPIキー設定など、HTTPヘッダーを編集するといった機能も用意されていますので、運用に応じて細かなカスタマイズが可能です。

Webhookログ

出力例

今回の例で言えば、以下のようなJSONレスポインスが得られます。WebhookのレスポンスとしてはHTTPステータス200を返しておけば大丈夫です。

{
    "status": "ok",
    "header": "Return-Path",
    "subject": "テキストメールテスト"
}

まとめ

メールと連携したシステムはよくあります。通常、メールサーバを立てて、その中で処理することが多いのですが、メールサーバが落ちてしまうとシステムが稼働しなくなったり、メール文面の解析が煩雑でした。Customers Mail Cloudを使えばそうした手間なくJSONで処理できて便利です。

受信サーバ | Customers Mail Cloud