Parse Webhookテクニカルガイド【入門】

この記事は Beginner’s Technical Guide to the SendGrid Parse Webhook の抄訳です。

Parse Webhookは様々な場面で利用できるSendGridの強力な機能の一つです。Parse Webhookを使うことで、あるドメイン(もしくはサブドメイン)宛の全てのメールの内容を指定したアプリケーションにPOSTすることができます。Parse Webhookは無限の可能性を秘めていますが、初めて使う場合には理解するのが少し難しいかもしれません。

ParseWebhookのイメージ図

このチュートリアルでは、Parse Webhookを初めて利用される方向けにできるだけわかりやすく説明します。
理解を助けるために、サンプルアプリケーションを作成しました。このサンプルはNode.js上で動作します。ソースコードはGitHubで公開しています。
このサンプルはハッカソンなどですぐに利用するためのツールとしても役に立ちます。

はじめに

まず、リポジトリのクローンを作成し、作成されたディレクトリ内に移動します。

$ git clone https://github.com/scottmotte/sendgrid-parse-api-example.git
$ cd sendgrid-parse-api-example

次に、認証情報を編集します。.env.exampleファイルの名称を.envに変更します。

$ mv .env.example .env

.envファイルを編集して、SendGridのユーザ名とパスワードをセットします。

SENDGRID_USERNAME=your_sendgrid_username
SENDGRID_PASSWORD=your_sendgrid_password

アプリケーションを実行します。

$ npm install
$ node app.js

アプリケーションがTCPポート3000番で待ち受けを開始します。

ローカルトンネルの準備

ローカルトンネルを利用することで、ローカル環境でテストできるため、時間を節約することができます。今回は ngrok を紹介します。ngrokはローカルサーバをWeb上にトンネルするためのツールです。SendGridからのPOSTはインターネットを経由して送信されるためこのようなツールが必要になります。こういったツールを利用せずに、いきなり実際のサーバにデプロイしてテストしようとすると、非常に手間がかかるのでお奨めしません。

ngrokをインストール、起動してローカルのTCPポート3000番をWeb上にトンネルします。

$ wget https://dl.ngrok.com/darwin_amd64/ngrok.zip
$ unzip ngrok.zip -d /usr/local/bin
$ ngrok 3000

以下のような表示になります。

ngrokのサンプル

(上記手順はMacを前提としています。他のOSについてはngrok Webサイトの「Download and Installation」をご覧ください。)

SendGrid側の設定とMXレコードの設定

DNS設定の反映には時間がかかるため、すぐに使える5分間アプローチと、独自ドメインを利用した48時間アプローチを紹介します。

5分間アプローチ

ハッカソンなどでは5分間アプローチが役に立ちます。SendGridのメールの受信(Parsing Incoming Emails)設定を行います。HostnameとUrlをそれぞれ以下のように設定します。

  1. Hostname
    [SendGridユーザ名].bymail.in
    (bymail.inドメインのMXレコードは予めmx.sendgrid.netに設定されています。)
  2. Url
    [ngrokを実行した際に表示されたForwardingのURL]/inbound
    上記の場合)https://321cd6c3.ngrok.com/inbound
    Parsing Incoming Emails の設定画面
48時間アプローチ

実際のメール運用では独自ドメインを通じてメールを処理したいところです。これには、MXレコードの変更が必要になります。MXレコードの変更反映のため、最長48時間かかることがあります。
まず、SendGridのメールの受信(Parsing Incoming Emails)の設定を行います。

  1. Hostname
    メールを受信するドメイン名を入力します。
  2. Url
    [ngrokを実行した際に表示されたForwardingのURL]/inbound
    上記の場合)https://321cd6c3.ngrok.com/inbound
    Parsing Incoming Emails の設定画面

次に、上記で Hostname に指定したドメインのDNS上のMXレコードを mx.sendgrid.net に設定します。以下に設定画面の例を示します。
MXレコードの設定例

1〜48時間待ちます。最長48時間かかるのは、MXレコードの変更が世界中に反映されるのに時間がかかるためです。待ち時間が長く不便ですが、インターネット上の仕組みによるものなので待つしかありません。

メールの送信

inbound@[上記でHostnameに設定したドメイン] 宛にメールを送信します。アプリケーションがSendGridからのPOSTを受信し、メール内の各コンテンツ(ヘッダ、件名、本文、添付ファイルなど)を取得できます。
メール送信してから1分以内にはPOSTを受信することができます。コンテンツはこのような形式で取得されます。

次のステップ

今回は、SendGridのParse Webhookの使用方法をご紹介しました。
このチュートリアルの内容をマスターすれば、あとは好きなようにカスタマイズしていくことができます。
routes/inbound.js をカスタマイズするところから始めるのがお奨めです。例えば、メールの本文をDBに記録したり、メールの件名内のキーワードをもとにイベントを発行したり。ロジックはあなた次第です。また、このブログ記事でもいくつかのアイディアをご紹介しています。