SMTP API（X-SMTPAPI）入門
- 2024年4月16日
- by SendGrid
- Category: 技術ネタ 機能・使い方
SMTPでメールを送るとき、通常はコマンドを実行して1通1通送信する必要がありますが、複数の宛先への一斉配信や宛先ごとに異なる文字列の差し込みなど、もっと複雑な送り方をしたいこともあるでしょう。そんな時にはSMTP APIが有効です。
SMTP APIは、「X-SMTPAPI」ヘッダをメッセージに付与することでSMTPのメール送信をカスタマイズできる、Twilio SendGrid独自の拡張機能です。今回は、SMTP APIでどのようなことができるのか、ひとつずつご紹介します。
SMTP APIとは
名前に「SMTP」と入っているため紛らわしいですが、SMTP APIはSendGridのメール送信機能を拡張するカスタムヘッダ（もしくはパラメータ）のことを指します。いわゆるメール配信プロトコルのSMTPとは全くの別物です。
SMTP APIは、以下のようにSMTPのメール送信リクエスト内でJSON文字列の拡張ヘッダ（X-SMTPAPIヘッダ）として指定することで利用できます。
X-SMTPAPI: {"category":"newuser"}
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で処理される際に宛先ごとに分解され、置換キーが宛先ごとに対応する文字列で置き換えられます。
属性情報の付与
カテゴリ（Categories）やユニーク引数（Unique Arguments）を用いることで、送信するメールに属性情報を付与することができます。
カテゴリ（「category」パラメータ）は複数のメールをグループ化する際に使用します。一方、ユニーク引数（「unique_args」パラメータ）は、文字通りメール毎に異なる値を指定して、メール1通とイベントを紐付けるために使用します。カテゴリとユニーク引数の違いやそれぞれの活用方法について知りたい方は、こちらの記事をご確認ください。
{
"category": [
"dogs",
"animals"
],
"unique_args": {
"customerAccountNumber": "55555",
"activationAttempt": 1
}
}
上記で指定したカテゴリとユニーク引数は、Activityの詳細情報から確認することができます。
配信スケジュールの指定
受信者が開封しやすい日時を狙ってメールを送るなど、配信スケジュールを指定することもできます。配信スケジュール指定用のパラメータは次の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 Centerにどの配信停止グループを表示するかを指定することもできます。
{
"asm_groups_to_display": [1, 2, 3]
}
配信停止グループの作成方法はこちらをご確認ください。
各種機能の状態切り替え
トラッキングなどの機能は、すべてのメールに対する設定（有効または無効）をダッシュボードで切り替えますが、メール個別に設定することも可能です。
有効/無効の設定だけでなく、フッタやテンプレートの内容の指定もできます。詳しい使い方や他の設定についてはこちらをご確認ください。
さいごに
SMTP APIは、SendGridの機能の中核と言ってもいいくらい、様々な機能が詰め込まれています。JSONのフォーマットはそれほど複雑ではありませんが、JSON文字列の生成を助けてくれるライブラリも提供されていますので、是非ご利用ください。より詳しい使い方や制限事項などについてはドキュメントをご確認ください。
