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

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

SMTPを拡張するSMTP APIを利用してメール送信する場合

SMTP APIとは

名前に「SMTP」と入っているため紛らわしいのですが、SMTP APIはSendGridのメール送信機能を拡張するカスタムヘッダで、いわゆるメール配信プロトコルのSMTPとは全くの別物です。SMTPでSMTP APIを利用する場合、次のような内容を拡張ヘッダとして指定します。ヘッダ名をとって「X-SMTPAPI」と呼ぶこともあります。値はJSON文字列で指定します。

1

X-SMTPAPI: {"to":["alice@test.com","bob@test.com"]}

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

宛先ごとに「ようこそ！◯◯様」などといった形で宛名やその他様々な属性値をメール本文などに埋め込む場合、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を参照してください。サンプルコードについてはこちらを参照してください。

Web API v3を利用してメール送信する場合

一方、Web API v3でメール送信する場合、Personalizations配列に指定する各オブジェクト内でsubstitutionsを指定することにより、宛先ごとの文字列埋め込みが実現できます。例えば、上の例と同じく、アリスとボブにメール送信する場合、リクエストは次のような形になります。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

{
  "personalizations" : [
    {
      "to": [{"email": "alice@test.com"}],
      "substitutions": {"-name-": "アリス"}
    },
    {
      "to": [{"email": "bob@test.com"}],
      "substitutions": {"-name-": "ボブ"}
    }
  ],
  "from": {"email": "sender@example.com"},
  "subject": "これは件名です",
  "content": [
    {
      "type": "text/plain",
      "value": "ようこそ！-name-様"
    }
  ]
}

Web API v3のメール送信エンドポイントでは、SMTP APIと同じく様々な機能が利用できます。詳しくはAPIリファレンスを参照してください。SendGrid公式ライブラリを利用するとWeb API v3で簡単にメール送信が行なえます。