V2 Mail Send

このエンドポイントではWeb API v2でメールの送信を行うことができます。

最新のメール送信用エンドポイントについては、Web API v3 Mail Sendを参照してください。現在 Web API v2をご利用の場合は、最新の機能が利用可能なWeb API v3への移行をお勧めします。

Web API v2を利用してメールを送信するSendGrid公式ライブラリが多数公開されています。可能であればこちらを利用することを推奨します。

メール送信

API経由でメールを送信する際はAPI Keysを使用してください。 APIキーは削除や権限設定変更がいつでもできるため、APIキーが漏洩した場合のリスクが低減できます。

AuthorizationヘッダにAPIキーをBearerトークンとして渡し、リクエストにはapi_userパラメータとapi_keyパラメータは含めないようにします。

1
例:"Authorization: Bearer <Your API Key>"

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

Web API v2では1回のAPIリクエストで宛先数は最大10,000まで指定可能です。また、明示的な送信間隔の制限はありませんが、1秒あたり3,000リクエストを超えないことを推奨します。

URI引数 必須 条件 説明
to Yes 有効なメールアドレスである必要があります このパラメータを使うと、受信者のアドレスを単一の宛先として指定できます。複数の宛先に送信する場合は配列で渡してください。
例:to[]=a@mail.com&to[]=b@mail.com 
x-smtpapiヘッダのTOパラメータを使用すれば受信者を追加できます。TOパラメータで単一の受信者を指定すると、受信ヘッダのForフィールドにそのアドレスが表示されるため、単一のアドレスを指定する場合は受信者が見やすいアドレスにしてください。例えば、toフィールドにはfromアドレスのような受信者が既に知っている一般的なメールアドレスを指定します。fromヘッダに表示される宛先を完全に隠したい場合は、toフィールドに複数のアドレスを配列として指定してください。
例:to[]=a@mail.com&to[]=b@mail.com 
もしくは、Web API v3のmail sendエンドポイントを使用してください。
toname No 文字列である必要があります。to パラメータが配列の場合、toname パラメータは to と同じ数の配列である必要があります 受信者の名前を与えます。上記のtoが配列で渡された場合、このパラメータも配列で渡す必要があります。
例:toname[]=Alpha&toname[]=Beta
x-smtpapi No 適切なJSONフォーマットである必要があります JSONヘッダによって実現可能な事についてはSMTP APIを参照してください
subject Yes 文字列である必要があります メールの件名です
text No textまたはhtmlを指定する必要があります メール本文のplainテキストコンテンツです
html No textまたはhtmlを指定する必要があります メール本文のHTMLコンテンツです
from Yes 送信元となる適切なメールアドレスである必要があります 受信者向けに表示されるFromメールアドレスです。
cc No 適切なメールアドレスである必要があります 複数の宛先に送信する場合、配列で渡すことができます。
例:cc[]=a@mail.com&cc[]=b@mail.com
ccname No 文字列である必要があります Ccフィールドに追加する名前です。
bcc No 適切なメールアドレスである必要があります 複数の宛先に送信する場合、配列で渡すことができます。
例:bcc[]=a@mail.com&bcc[]=b@mail.com
bccname No 文字列である必要があります Bccフィールドに追加する名前です。
fromname No 文字列である必要があります Fromメールフィールドに追加する名前です。すなわち - あなたの名前または会社名です
replyto No 適切なメールアドレスである必要があります メールのreply-toフィールドです
date No 適切な日付フォーマットである必要があります メールのDateヘッダを指定します。
例:“Thu, 21 Dec 2000 16:01:07 +0200”。PHPの場合 date(r); を使用することができます。
files No 7MB以下である必要があります 添付されるファイルです。ファイルコンテンツはHTTP POSTのマルチパートの一部である必要があります。
例:files[file1.jpg]=file1.jpg&files[file2.pdf]=file2.pdf
content No インラインイメージ送信時に必要です インラインイメージとして扱われるファイルのコンテンツIDです。コンテンツIDはHTML内で使用されるcidと一致している必要があります。
例: content[file1.jpg]=ii_139db99fdb5c3704はHTMLでは<img src="cid:ii_139db99fdb5c3704"></img>に対応します。また、files[file1.jpg]がコンテンツに含まれています
headers No 整数を含まない適切なJSONフォーマットである必要があります。 JSONフォーマットでキー/値のペアの集合。この引数はSendGrid以外の拡張ヘッダを指定するために使用します。それぞれのキーはヘッダ名を、値はヘッダ値を表します。{“X-Accept-Language”: “en”, “X-Mailer”: “MyApp”}
Parameter Value Requirements Description
1
7065689663

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data to=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to=destination@example.com&toname=Destination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
<result>
   <message>success</message>
</result>

複数の受信者への送信

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data to[]=destination@example.com&toname[]=Destination&to[]=example@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to[]=destination@example.com&toname[]=Destination&to[]=example@example.com&toname[]=Destination2&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
<result>
   <message>success</message>
</result>

ccとccnameを含むメール送信

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data to[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to[]=destination@example.com&toname[]=Destination&cc=ccdestination@mail.com&ccname=CCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
<result>
   <message>success</message>
</result>

bccとbccnameを含むメール送信

Call

POST https://api.sendgrid.com/api/mail.send.json
POST Data to[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/mail.send.xml
POST Data to[]=destination@example.com&toname[]=Destination&bcc=bccdestination@mail.com&bccname=BCCDestination&subject=Example_Subject&text=testingtextbody&from=info@domain.com

Response

1
2
3
<result>
   <message>success</message>
</result>

cURLの例

単一受信者へのメールの送信

1
2
3
4
5
6
7
8
curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode "to=destination@example.com" \
     --data-urlencode "toname=Destination" \
     --data-urlencode "subject=Example Subject" \
     --data-urlencode "text=testingtextbody" \
     --data-urlencode "from=info@domain.com"

複数受信者へのメールの送信

1
2
3
4
5
6
7
8
curl -X "POST" "https://api.sendgrid.com/api/mail.send.json" \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'Authorization: Bearer YOUR_API_KEY' \
     --data-urlencode "to[]=destination@example.com,example@example.com" \
     --data-urlencode "toname[]=Destination,Destination2" \
     --data-urlencode "subject=Example Subject" \
     --data-urlencode "text=testingtextbody" \
     --data-urlencode "from=info@domain.com"

添付ファイル付きメールの送信

1
2
3
4
5
6
curl https://api.sendgrid.com/api/mail.send.json \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
-F text="testing text body" --form-string html="<strong>testing html body</strong>" \
-F from=test@yourdomain.com \
-F files\[attachment.gz\]=@f.php.gz

注: ローカルファイルをアップロードする場合、@filenameを使用してください。

ファイル名に対して’;type=<mime type>’でファイルコンテンツのタイプを指定してのメールの送信

1
2
3
4
5
6
curl https://api.sendgrid.com/api/mail.send.json \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F to=recipient@domain.com -F toname=test -F subject="Example Subject" \
-F text="testing text body" --form-string html="<strong>testing html body</strong>" \
-F from=test@yourdomain.com \
-F files\[attachment.pdf\]=@attachment.pdf;type=application/pdf

HTTPダンプ

以下はWeb API v2を通じてSendGridサーバに対してメールを送信した際のHTTPダンプです。

1
POST /api/mail.send.json HTTP/1.1
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
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
Host: sendgrid.com

Accept: */*

Content-Length: 999

Expect: 100-continue

Content-Type: multipart/form-data; boundary=----------------------------400f182a9360

Authorization: Bearer YOUR_API_KEY

HTTP/1.1 100 Continue

------------------------------400f182a9360

Content-Disposition: form-data; name="to"

someone@somewhere.com

------------------------------400f182a9360

Content-Disposition: form-data; name="subject"

test of file sends

------------------------------400f182a9360

Content-Disposition: form-data; name="html"

the HTML

------------------------------400f182a9360

Content-Disposition: form-data; name="text"

the plain text

------------------------------400f182a9360

Content-Disposition: form-data; name="from"

example@sendgrid.com

------------------------------400f182a9360

Content-Disposition: form-data; name="files[myfile]"; filename="myfile"

Content-Type: application/octet-stream

file with stuff in it

------------------------------400f182a9360--

HTTP/1.1 200 OK

Server: nginx/0.7.65

Date: Fri, 03 Jun 2011 22:30:58 GMT

Content-Type: application/json

Transfer-Encoding: chunked

Connection: keep-alive

1
{"message":"success"}