SMTP API(X-SMTPAPI)入門
- 2015年10月20日
- by SendGrid
- Category: 技術ネタ 機能・使い方
はじめに
これまで、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機能を通じてアプリケーション側で受信できます。この際、各イベントとメールを関連付けるのに使用されるのが、CategoriesとUnique Argumentsです。
Categories(「category」パラメータ)はカテゴリ毎のStatsを取得できるため、複数メールをグループ化する際に使用します。Unique Arguments(「unique_args」パラメータ)は文字通り、メール一通毎に異なる値を指定して、メール1通とイベントを紐付けるために使用します。
{ "category": [ "dogs", "animals" ], "unique_args": { "customerAccountNumber": "55555", "activationAttempt": 1 } }
上記のような値を指定してメールを送信すると、Event Webhookでは次のようなイベントが取得できます。
配信スケジュールの指定
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文字列の生成を助けてくれるライブラリも提供されていますので、是非ご利用ください。より詳しい使い方や制限事項などについては、ドキュメントをご確認ください。