SMTP API概要

SendGridのSMTP APIは開発者がメールに対してカスタムの処理を指定することができます。これはメッセージのヘッダに挿入されるX-SMTPAPIヘッダを通じて実現されます。ヘッダはJSON形式で指定されます。

X-SMTPAPIヘッダは最終的に送信されるメールからは取り除かれます。このヘッダはSendGridが受け取ったメールをどのように処理するかを示すためのものであることが理由です。従って、最終的なメールでこのヘッダを確認することはできません。

ヘッダの例

1
2
3
4
5
{
    "category": [
        "newuser"
    ]
}

この場合、ヘッダはこのメールに対して”newuser”というCategoryを割り当てることを意味しています。

X-SMTPAPIヘッダ

X-SMTPAPIヘッダはいくつかのセクションから構成されるJSONエンコードされた連想配列です。以下はそれぞれのセクションを使用したJSON文字列の例です。このヘッダはSendGridに送信されるSMTPメッセージに追加され、このメールに対してヘッダの内容が適用され処理されます。

要件と制限事項参照

Apps: フィルタとその設定から構成される連想配列です。これは既にセットアップされたフィルタ設定を更新するために使用されます。Settingsは名前とその値から構成される連想配列です。

1
2
3
4
5
6
7
8
9
10
11
{
  "filters": {
    "footer": {
      "settings":
        {
          "enable": 1,
          "text/plain": "Thank you for your business"
        }
    }
  }
}

Category: メールに対してカテゴリを関連付けてログとしてき記録されます。カテゴリは配列として10項目まで挿入することができます。また、カテゴリは事前に定義されていません。カテゴリは「newsletter」や「password_reset」といった形でより広いトラッキングのために利用されます。

1
2
3
4
5
6
{
  "category": [
    "category1",
    "category2"
  ]
}

Scheduling Parameters: スケジュール配信や高速なメールフローを実現するために使用します。

1
2
3
{
  "send_at": 1409348513
}

Section: Sectionは多数の受信者に共通の置換処理を簡略化するために使用することができます。以下はSubstitutionの値で使用できる連想配列です。

1
2
3
4
5
6
{
  "section": {
    "%sellerSection%": "Seller information for: %name%",
    "%buyerSection%": "Buyer information for: %name%"
  }
}

Substitution: メールの本文内のタグを置換する連想配列です。各値はJSON文字列内のTo:セクションに対応しています。

1
2
3
4
5
6
7
8
9
10
11
12
{
  "sub": {
    "%name%": [
      "Ben",
      "Joe"
    ],
    "%role%": [
      "%sellerSection%",
      "%buyerSection%"
    ]
  }
}

To: メッセージの送信先アドレスリストです。表示名を含めることもできます。

1
2
3
4
5
6
{
  "to": [
    "<ben@example.com>",
    "Joe Smith <joe@example.com>"
  ]
}

Unique Arguments: 引数とその値から構成される連想配列です。これはSMTP APIトランザクションで送信されるメールに対して適用されます。Unique Argumentsは「newsletter_fall_safe_1_1_14」や「password_reset_user123456」といった形でより詳細なトラッキングのために利用されます。

1
2
3
4
5
6
{
  "unique_args": {
    "orderNumber": "12345",
    "eventID": "6789"
  }
}
X-SMTPAPIヘッダを使用した例についてはSMTP APIの使用方法を参照してください。