Webhook APIを使って添付ファイル付きメールを処理する(Google Cloud Functions + PHP)

Customers Mail CloudのWebhookは2種類あります。

  1. メール受信時
  2. メール送信時

メール受信時のWebhookはその名の通り、メールを受け取った際に任意のURLをコールするものです。この記事では添付ファイル付きメールを受け取った際のWebhook処理について解説します。

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

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

Webhook設定ダイアログ

送信されてくるデータについて

メールを受信すると、以下のようなWebhookが送られてきます(データは一部マスキングしています)。JSONにしていますが、実際にはmultipart/form-dataです。

{
    "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",
    "attachments": 1,
    "attachment1": "...."
}

Google Cloud Functionsの準備

今回はローカルで開発する流れを紹介します。まずindex.phpというファイルを作成し、内容を以下のように記述します。

<?php

use Google\CloudFunctions\FunctionsFramework;
use Psr\Http\Message\ServerRequestInterface;

// Register the function with Functions Framework.
// This enables omitting the `FUNCTIONS_SIGNATURE_TYPE=http` environment
// variable when deploying. The `FUNCTION_TARGET` environment variable should
// match the first parameter.
FunctionsFramework::http('helloHttp', 'helloHttp');

function helloHttp(ServerRequestInterface $request): string
{
    $name = 'World';
    $body = $request->getBody()->getContents();
    if (!empty($body)) {
        $json = json_decode($body, true);
        if (json_last_error() != JSON_ERROR_NONE) {
            throw new RuntimeException(sprintf(
                'Could not parse body: %s',
                json_last_error_msg()
            ));
        }
        $name = $json['name'] ?? $name;
    }
    $queryString = $request->getQueryParams();
    $name = $queryString['name'] ?? $name;

    return sprintf('Hello, %s!', htmlspecialchars($name));
}

次に、 composer.json というファイルを作成し、以下のように記述します。これは composer を使っていますので、あらかじめComposerのインストールを行ってください。

{
    "require": {
        "php": ">= 7.4",
        "google/cloud-functions-framework": "^1.1"
    },
    "scripts": {
        "start": [
           "Composer\\Config::disableProcessTimeout",
           "FUNCTION_TARGET=helloHttp php -S localhost:${PORT:-8080} vendor/google/cloud-functions-framework/router.php"
        ]
    }
}

ファイルを作成したら、 composer コマンドでインストールします。

composer require google/cloud-functions-framework

これで準備は完了です。関数は以下のように実行します。

export FUNCTION_TARGET=helloHttp composer start

実行すると、 http://127.0.0.1:8080 でサーバーが立ち上がります。

PHPのコード

処理は index.phphelloHttp 関数内に記述します。最低限として、200番台のステータスコードを返す必要があります。

function helloHttp(ServerRequestInterface $request): string
{
    // ここに処理を記述
    return printf('ok');
}

マルチパートフォームデータを取得する

multipart/form-data で送られてくるデータは $request->getParsedBody() にて取得できます。これは連想配列になっていますので、キーを指定してデータを取得できます。

$json = $request->getParsedBody();
printf($json['server_composition']); // sandbox
print($json['filter']); // info@smtps.jp

添付ファイルの処理

添付ファイルの有無は $json["attachments"] が0以上かどうかで判別できます。

添付ファイルは $request->getUploadedFiles() にてアクセスできます。1つ目の添付ファイルは $nameattachment1 、2つ目は attachment2 になります。

foreach ($request->getUploadedFiles() as $name => $file) {
    printf($name); // attachment1
    printf($file->getClientFilename());    // sample.jpg
    printf($file->getClientMediaType()); // image/jpeg
    printf($file->getSize()); // 12345
}

なお、日本語ファイル名はエンコードされているケースが多いので注意してください。

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

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

Webhookログ

まとめ

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

添付ファイルまで処理対象にしたい時には、この方法を利用してください。

受信サーバ | Customers Mail Cloud