SMTPメールの構築

Telnetでテストメールを送信し、 SMTPの使用方法を確認したら、コンテンツを構築しましょう。

構築を開始する

SMTP APIはさまざまなパラメータをJSON文字列で指定することにより動作します。例えば、”X-SMTPAPI”ヘッダに次のようなJSON文字列を指定します:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

{
  "to": [
    "example@example.com",
    "example@example.com"
  ],
  "sub": {
    "%name%": [
      "Ben",
      "Joe"
    ],
    "%role%": [
      "%sellerSection%",
      "%buyerSection%"
    ]
  },
  "category": [
    "Orders"
  ],
  "unique_args": {
    "orderNumber": "12345",
    "eventID": "6789"
  },
  "filters": {
    "footer": {
      "settings": {
        "enable": 1,
        "text/plain": "Thank you for your business"
      }
    }
  },
  "send_at": 1409348513
}

制限事項

  • 宛先として指定可能なアドレスの上限数は10,000ですが、ジョブを分割するために1,000アドレス程度を上限とすることをお勧めします。これにより、負荷を分散させることができます。多数の置換タグやセクションタグを指定する場合、小さなグループに分割することを推奨します。
  • X-SMTPAPIを利用して複数の宛先に送信する場合、SMTPプロトコルの”TO”フィールドは使用できません。メールヘッダ内に指定したアドレスがすべて表示されてしまうため、標準SMTPプロトコルの”TO”フィールドを使用して複数の宛先に個別にメールを送信することはできません。詳細については RFC 5321を参照してください。
  • ヘッダは1行あたり最大1,000文字が上限となります。この制限に従わないと、中間のMTAがヘッダをスペース以外で分割してしまう可能性があります。これにより、最終的なメールにスペースが挿入されてしまう可能性があります。メールがSendGridに到達する前に別のMTAを通過する場合、最大ヘッダ長の制限がさらに厳しくなり、ヘッダが切り捨てられる可能性があります。
  • SMTP APIを使用する場合、SendGridのシステムがパースエラーを起こすと、SMTPセッションのMAIL FROMで指定されたアドレスにバウンス通知されます。MAIL FROMアドレスはSendGridからメール送信される際に上書きされます。このため、バウンスを受け取れるアドレスを指定しておくと安全です。これによりエラーを検知することができます。
  • SMTP APIでユニコード文字列を送信する時は、\u エスケープ文字列を使ってエスケープする必要があります。例えば、ユニコード文字 á は \u00E1 のように表現されます。

送信のカスタマイズ

SMTPによるメール送信を異なる設定でカスタマイズすることができます。これらの設定は X-SMTPAPIヘッダ で変更できます。

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

{
  "to": ["example@example.com", "example@example.com"],
  "sub": {
    "%name%": ["Ben", "Joe"],
    "%role%": ["%sellerSection%", "%buyerSection%"]
  },
  "category": ["Orders"],
  "unique_args": {
    "orderNumber": "12345",
    "eventID": "6789"
  },
  "filters": {
    "footer": {
      "settings": {
        "enable": 1,
        "text/plain": "Thank you for your business"
      }
    }
  },
  "send_at": 1409348513
}

X-SMTPAPIヘッダはいくつかのセクションより構成される連想配列をJSONエンコードしたものです。以下は各セクションを使用したJSON文字列の例です。SMTPメッセージにこのヘッダを追加すると、SendGrid側で解釈され、そのメッセージのトランザクションに適用されます。X-SMTPAPIヘッダでは次のような機能を利用できます:

スケジュール送信

X-SMTPAPIヘッダで send_at パラメータを利用することでメールの送信時刻をスケジュール指定できます。send_at に UNIX タイムスタンプを設定してください。

1
2
3

{
  "send_at": 1409348513
}

詳細については scheduling parametersを参照してください。

置換タグ

置換タグ（Substitution Tag）を利用することで、宛先の氏名など、各宛先に関連した特定のコンテンツを挿入できます。

例えば、宛先の氏名を置換するために置換タグを使用する場合、メッセージのHTMLパートに {{name}} タグを指定します:

1
2
3
4
5
6
7
8

<html>
  <head></head>
  <body>
    <p>Hello {{name}},<br>
        The body of your email would go here...
    </p>
  </body>
</html>

{{name}}タグを置換する値を定義するには、X-SMTPAPIヘッダで以下のように定義します:

1
2
3
4
5
6
7
8
9
10
11
12

{
  "to": [
    "john.doeexampexample@example.com",
    "example@example.com"
  ],
  "sub": {
    "{{name}}": [
      "John",
      "Jane"
    ]
  }
}

詳細については substitution tags を参照してください。

セクションタグ

この機能は廃止されました。

セクションタグ（Section Tag）は置換タグと似ていますが、各宛先ごとのタグを置換するというよりは、一般的なコンテンツ（例えば挨拶文など）を置換するにに使用します。

詳細については、 section tagsを参照してください。

配信停止グループ

X-SMTPAPIヘッダにasm_group_idパラメータを含めることで配信停止グループを簡単に指定できます。指定したいグループの数値IDを asm_group_id に指定するだけです。

1
2
3

{
  "asm_group_id": 1
}

詳細については、suppression groups を参照してください。

カテゴリ

カテゴリを使用すると、「週刊ニュースレター」や「確認メール」など、幅広いトピックに基づいてメールを追跡できるようになります。X-SMTPAPIヘッダのcategoryパラメータで定義したいカテゴリを指定するだけです:

1
2
3

{
  "category": "Example Category"
}

詳細については、categories を参照してください。

カテゴリは幅広いトピックを指定するのに使用してください。ユニークな識別子を指定する場合は ユニーク引数（Unique Arguments） を使用してください。

ユニーク引数

ユニーク引数を使用して、個々のメッセージに固有の特定の識別子に基づいてメールを追跡できます。ユニーク引数はSendGridの Event Webhook もしくは Activityページで確認できます。

詳細については、unique argumentsを参照してください。

追加のリソース