宛先ごとに異なる文字列を本文や件名に埋め込んで送信する

複数の宛先に個別でメールを送信する場合、通常のSMTPでは、Toヘッダに宛先を1つ指定したメッセージを繰り返し送信する必要があります。この方法は非常に時間がかかり非効率です。また、「ようこそ!◯◯様」のように本文内に宛先ごとに異なる文字列を埋め込む場合、送信側で宛先ごとに本文の内容を調整して送信する必要があります。こういった課題を解決する方法としてSMTP API(X-SMTPAPI)があります。

SMTP APIとは

名前に「SMTP」と入っているため紛らわしいのですが、SMTP APIはSendGridのメール送信機能を拡張するカスタムヘッダ(もしくはパラメータ)のことを指します。いわゆるメール配信プロトコルのSMTPとは全くの別物です。 SMTP APIは、SMTPおよびWeb APIのメール送信用エンドポイントのいずれからも利用できます。

  • SMTPで利用する場合
1
X-SMTPAPI: {"to":["alice@test.com","bob@test.com"]}

といった形でメール送信リクエスト内の拡張ヘッダとして指定します。

  • Web APIで利用する場合
1
$ curl -X POST https://api.sendgrid.com/api/mail.send.json -d x-smtpapi={"to":["alice@test.com","bob@test.com"]}...

といった形でメール送信リクエスト内のパラメータとして指定します。

共通しているのが「X-SMTPAPI」というキーワードです。このため、SMTP APIのことをX-SMTPAPIと呼ぶこともあります。値はJSON文字列で指定します。

宛先ごとの文字列埋め込み

宛先ごとに「ようこそ!◯◯様」などといった形で宛名やその他様々な属性値をメール本文などに埋め込む場合、Substitution Tagsを利用します。次のように、「sub」パラメータで置換キー(-name-)と宛先毎の置換文字列を配列([“アリス”,”ボブ”])で指定します。配列の順序は「to」パラメータで指定した宛先配列の順序と対応づいています。また、SMTP APIでASCII文字列以外を使用する場合、Unicodeエスケープ(「\uXXXX」形式)する必要があります。

1
2
3
4
5
6
7
8
9
10
11
{
  "to" : [
    "alice@test.com",
    "bob@test.com"
  ],
  "sub": {
    "-name-": [
      "アリス",
      "ボブ"
   ]
}

一方、メール本文や件名には置換したい箇所に置換キーを埋め込みます。

1
ようこそ!-name-様

こうすることで、このリクエストはSendGridで処理され、宛先ごとに分解された上で、置換キーが宛先ごとに対応する文字列で置き換えられます。

この状態でメールを送信すると、それぞれの宛先に次のような内容のメールが届きます。

  • alice@test.com宛のメール
    ようこそ!アリス様

  • bob@test.com宛のメール
    ようこそ!ボブ様

SMTP APIには他にも様々な機能があります。詳しい使い方や制限事項についてはAPIリファレンスを参照してください。

SendGridの公式ライブラリは、X-SMTPAPIヘッダの生成やメール送信リクエストへの設定を行ってくれるので簡単に利用できます。ライブラリの詳しい利用方法は各リポジトリ内のREADMEを参照してください。サンプルコードについてはこちらを参照してください。