SMTP APIの使用方法

多数のSMTP APIメソッドをまとめて一つの大きなJSON文字列として結合し、メッセージとともにSendGridに送信します。これは、「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
33
34
35
36
{
  "to": [
    "ben@sendgrid.com",
    "joe@sendgrid.com"
  ],
  "sub": {
    "%name%": [
      "Ben",
      "Joe"
    ],
    "%role%": [
      "%sellerSection%",
      "%buyerSection%"
    ]
  },
  "section": {
    "%sellerSection%": "Seller information for: %name%",
    "%buyerSection%": "Buyer information for: %name%"
  },
  "category": [
    "Orders"
  ],
  "unique_args": {
    "orderNumber": "12345",
    "eventID": "6789"
  },
  "filters": {
    "footer": {
      "settings": {
        "enable": 1,
        "text/plain": "Thank you for your business"
      }
    }
  },
  "send_at": 1409348513
}

上記の例は読みやすいようにフォーマットされています。ヘッダは1行あたり72文字以内で構成する必要があります。RFC 821ではテキスト行の最大長さは1000文字です。この文字列をご自身で生成する場合、上記の制限に収まるよう確認することをお勧めします。

以下はPerlスクリプトで上記のJSONヘッダを生成する例です:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#!/usr/local/bin/perl -w

use strict;
use JSON;

my $header = { to => ['ben@sendgrid.com', 'joe@sendgrid.com'],
sub => { '%name%' => [ 'Ben', 'Joe' ], '%role%' =>[ 'sellerSection', 'buyerSection' ] },
section => { '%sellerSection%' => 'Seller information for: %name%', '%buyerSection%' => 'Buyer information for: %name%' },
category => 'Orders',
unique_args => { 'orderNumber' => '12345', 'eventID' => '6789' },
filters => { 'footer' => {'settings' => {'text/plain' => "Thank you for your business"}}}};

my $json = JSON->new;
$json->space_before(1);
$json->space_after(1);
my $js = $json->encode($header);
# This regex breaks the string up at whitespaces to keep the line length short
$js =~ s/(.{1,72})(\s)/$1\n   /g;
my $hdr = "X-SMTPAPI: $js";
print "$hdr\n";

要件と制限事項

指定可能な宛先数の上限は10,000ですが、1,000程度の宛先に分割することを推奨します。これにより処理の負荷を分散させることができます。さらに、多数のSubstitutionやSectionがある場合、小さなグループに分割して送信することを推奨します。

SMTPAPIの機能を使用して複数の受信者に対してメッセージを送信する場合、SMTPプロトコルを使用して複数の受信者に対して送信してはいけません。これを行うと、メッセージの複製が送信される可能性があります。 これに関する詳細についてはRFC 821を参照してください。

ヘッダが1行あたり1000文字以内の制限に収まっていることを確認してください。 これは結果的にメールにスペースが挿入される結果となります。加えて、SendGridに到達する前に他のMTAを経由している場合、最大ヘッダ長の制限設定によりヘッダが切り捨てられる場合があります。

APIを使用する場合、X-SMTPAPIヘッダのパースに失敗した場合、そのメッセージのMAIL FROMのアドレスはバウンスされます。 最終的なメールの送信の際にMAIL FROMは書き直されます。そのためバウンスの際の警告を受信するアドレスをセットしても安全です。

SMTP API内でのUnicodeを送信

SMTP API経由でUnicode文字を送信する場合、\uを使用してエスケープする必要があります。エスケープすると「á」といった文字列は「\u00E1」のような形になります。 Unicode文字の一覧についてはUnicode Articleを参照してください。