SMTP API(X-SMTPAPI)入門

20639682_s2

はじめに

これまで、SMTP APIについてはメール送信の拡張機能ということで、部分的には様々な場面でご紹介してきましたが、今回は改めてSMTP APIについて整理してご紹介します。

SMTP APIとは

名前に「SMTP」と入っているため紛らわしいのですが、SMTP APIはSendGridのメール送信機能を拡張するカスタムヘッダ(もしくはパラメータ)のことを指します。いわゆるメール配信プロトコルの方のSMTPとは全くの別物です。

SMTP APIはSMTP、Web APIのメール送信エンドポイントいずれからも利用できます。

  • SMTPで利用する場合

    X-SMTPAPI: {"category":"newuser"}
    

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

  • Web APIで利用する場合

    $ curl -X POST https://api.sendgrid.com/api/mail.send.json -d X-SMTPAPI={"category":"newuser"}...
    

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

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

SMTP APIでできること

SMTP APIには多数の機能があります。個別に詳しくご紹介していきます。

複数の宛先指定

複数の宛先に個別にメールを送信する場合、通常のSMTPでは、Toヘッダに宛先を一つ指定したメッセージを繰り返し送信する必要があります。この方法は非常に時間がかかり非効率です。SMTP APIでは「to」パラメータに配列の形で宛先を複数指定できるため、効率的に大量のメールを送信することができます。次のような形で宛先を指定します。

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

このリクエストはSendGridで分解され、各宛先にはToヘッダに個別に宛先指定(他の人の宛先が見えることはありません)されたメールが届きます。Toに指定できる宛先数についてはこちらをご確認ください。

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

宛先ごとに「ようこそ!◯◯様」などといった形で宛名やその他様々な属性値をメール本文などに埋め込みたい場合、Substitution Tagsが利用できます。次のように、「sub」パラメータで置換キー(-name-)と宛先毎の置換文字列([“Alice”,”Bob”])を配列で指定します。配列の順序は「to」パラメータで指定した宛先配列の順序と対応づいています。

{
  "to" : [
    "alice@test.com",
    "bob@test.com"
  ],
  "sub": {
    "-name-": [
      "Alice",
      "Bob"
   ]
}

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

ようこそ!-name-様

こうすることで、このリクエストはSendGridで処理され、宛先ごとに分解された上で、置換キーが宛先ごとに対応する文字列で置き換えられます。また、Section Tagsを利用することでより高度な置換処理を指定することもできます。

メールとイベントの関連付け

SendGridから送信したメールに関するイベントはEvent Webhook機能を通じてアプリケーション側で受信できます。この際、各イベントとメールを関連付けるのに使用されるのが、CategoriesUnique Argumentsです。

Categories(「category」パラメータ)はカテゴリ毎のStatsを取得できるため、複数メールをグループ化する際に使用します。Unique Arguments(「unique_args」パラメータ)は文字通り、メール一通毎に異なる値を指定して、メール1通とイベントを紐付けるために使用します。

{
  "category": [
      "dogs",
      "animals"
   ],
  "unique_args": {
    "customerAccountNumber": "55555",
    "activationAttempt": 1
  }
}

上記のような値を指定してメールを送信すると、Event Webhookでは次のようなイベントが取得できます。

1-1

配信スケジュールの指定

SMTP APIを利用して配信スケジュールを指定することもできます。この機能を利用して、受信者が読みやすい時間帯にメールを配信することができます。配信スケジュール指定用のパラメータは次の2種類が用意されています。時刻はUNIXタイム形式で指定します。

  • send_at」パラメータ:全てのメールの配信時刻を一括指定

    {
      "send_at": 1409348513
    }
    

  • send_each_at」パラメータ:宛先ごとに配信時刻を指定。配列の順序は「to」パラメータでしていた宛先配列の順序と対応づいています

    {
      "to" : [
        "alice@test.com",
        "bob@test.com"
      ],
      "send_each_at": [
        1409348513,
        1409347513
      ]
    }
    

この機能には、単なる配信時刻指定の他にもう一つの使い方があります。「to」パラメータに指定可能な宛先数の上限は10,000ですが、同一の配信時刻を指定したリクエストを複数回実施することで、その上限を超える宛先に対しても一斉送信が可能になります。

配信停止グループの指定

配信停止グループを指定しておくと、配信停止グループ毎に配信停止を行うことができます。「asm_group_id」パラメータにグループIDを指定します。

{
  "asm_group_id": 1
}

受信者による購読管理をするためのPreferenceページに表示する配信停止グループを指定することもできます。

{
  "asm_groups_to_display": [1, 2, 3]
}

グループの作成方法、グループIDの確認方法など、詳細についてはこちらをご確認ください。

各種機能のOn/Off切替え

例えば開封トラッキング機能は、ポータル上でOn/Offを設定しますが、特定のメールのみ機能を無効にしたいといったケースもあるかと思います。このような場合にメール個別でOn/Offを切り替えることが可能です。

  • Bcc
  • 開封・クリック・配信停止トラッキング
  • フッタの指定
  • テンプレート

などで切り替え可能です。On/Off設定だけでなくフッタやテンプレートの内容の指定もできます。詳しい使い方や他の設定についてはこちらをご確認ください。

さいごに

SMTP APIは、SendGridの機能の中核と言ってもいいくらい、様々な機能が詰め込まれています。JSONのフォーマットはそれほど複雑ではありませんが、JSON文字列の生成を助けてくれるライブラリも提供されていますので、是非ご利用ください。より詳しい使い方や制限事項などについては、ドキュメントをご確認ください。