V3 Mail Send API概要

2024年4月以降、Domain AuthenticationもしくはSingle Sender Verificationの設定が必須になり、送信元に指定するドメインまたはメールアドレスで設定を完了させていない場合はメールを送信できません。詳しくはこちらをご覧ください。

このエンドポイントを利用することでWeb API v3（最新バージョンのAPI）経由でメール送信を行うことができます。 Web API v2メール送信エンドポイントのドキュメントについてはv2 APIリファレンスを参照してください。

SendGridはアプリケーションとv3の連携を簡単にするため7つのプログラミング言語向けのライブラリを提供しています。C#, Go, Java, NodeJS, PHP, Python, Ruby。

Request

1

POST https://api.sendgrid.com/v3/mail/send HTTP/1.1
Request Body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "personalizations": [
    {
      "to": [
        {
          "email": "john@example.com"
        }
      ],
      "subject": "Hello, World!"
    }
  ],
  "from": {
    "email": "from_address@example.com"
  },
  "content": [
    {
      "type": "text/plain",
      "value": "Hello, World!"
    }
  ]
}

Response

1
2
3

{
  HTTP/1.1 202
}
Web API v3についての一般的な情報については、API概要を参照してください。 v3メール送信エンドポイント経由でメールを送信するには2つの方法があります：

認証

1

curl -X "POST" "https://api.sendgrid.com/v3/mail/send" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "[YOUR DATA HERE]"
APIリクエストごとにAuthorizationヘッダを含めて認証する必要があります。このヘッダには、Bearer認証タイプと必要なパーミッションが割り当てられたAPIキーを含めなければいけません。詳細についてはこちらを参照してください。

制限事項

  • 送信可能なメールのサイズは添付ファイルを含め30MB以内です。
  • 指定可能な宛先数は1,000件以内です。これには、to, cc, bccパラメータで指定したものを含み、personalizations配列を超えてカウントされます。
  • custom argumentsの最大長は10,000バイトです。
  • fromフィールドはUnicodeエンコードをサポートしていません。
  • personalizations内のto.name, cc.name, bcc.nameは次の文字を含めることはできません：;, ,
  • 事前に送信元に指定するドメインまたはメールアドレスでDomain AuthenticationもしくはSingle Sender Veriificationを設定しておく必要があります。設定していない場合、メールを送信できません。
各パラメータの制限事項の詳細については、要求ボディパラメータを参照してください。

バリデーション

v3メール送信エンドポイントに要求を送信すると、メール送信前にJSONペイロードのバリデーションが行われます。 エラーがあった場合、SendGridはエラーを特定し、要求内のエラーを可能な限り返します。詳細についてはエラーページを参照してください。

要求ボディパラメータ

/v3/mail/sendに対するすべての要求には、メールコンテンツとメタデータを含むJSON形式のボディを指定する必要があります。これには、宛先アドレス、送信元アドレス、メールの件名などが含まれます。
JSONパラメータ 型 必須 制限 詳細
personalizations オブジェクト配列 Yes 最低1, 最大1000
メッセージおよびそのメタデータの配列です。personalizations内の各オブジェクトはエンベロープと考えることができます。すなわち、そのメッセージの受信者やメッセージの扱いが定義されます。詳細については、Personalizationsドキュメントを参照してください。personalizationsのパラメータはメッセージレベルの同じ名前のパラメータの値より優先されます。
to email オブジェクト配列 Yes 最低1
宛先の配列です。この配列の各emailオブジェクトには宛先の表示名を含めることができ、宛先のメールアドレスは常に必須です。
email string Yes
宛先のメールアドレス
name string No
宛先の表示名。;, ,を含んではいけません。
cc emailオブジェクト配列 No
メールのCcを受け取る宛先の配列です。この配列の各emailオブジェクトには宛先の表示名を含めることができ、宛先のメールアドレスは常に必須です。
email string Yes
宛先のメールアドレス
name string No
宛先の表示名。;, ,を含んではいけません。
bcc email オブジェクト配列 No
メールのBccを受け取る宛先の配列です。この配列の各emailオブジェクトには宛先の表示名を含めることができ、宛先のメールアドレスは常に必須です。
email string Yes
宛先のメールアドレス
name string No
宛先の表示名。;, ,を含んではいけません。
subject string No
メールの件名
headers オブジェクト No
メールをハンドリングするためのオブジェクト（拡張ヘッダ）です。
substitutions オブジェクト No personalizationオブジェクトあたり最大100、または10Kバイト
"置換タグ":"値"形式のオブジェクトです。それぞれstringである必要があります。これらのsubstitutionsはメールのコンテンツに加えて、subject と reply-to パラメータに適用されます。

personalizationオブジェクトあたり最大100個のsubstitutionを含めることができます。また、substitutionsの合計サイズはpersonalizationあたり10,000バイトを超えてはいけません。
custom_args オブジェクト No 10,000 bytesを超えないこと
カスタム引数は送信メールとイベントデータ（ActivityおよびEvent Webhookで確認可能）を紐付けることができます。各Personalizationで固有の値を設定可能です。カスタム引数の値は、メール本文中に含まれることはありません。また、substitutionsを利用してカスタム引数の値を置換することはできません。 カスタム引数のサイズは10,000バイトを超えてはいけません。
send_at integer No 秒（ミリ秒ではありません）
SendGridから送信される時刻を表すUNIXタイムスタンプです。送信時刻に柔軟性を持たせられる場合、オフピークタイムでの送信をお勧めします。多くのメールは毎時0分もしくは30分に送信されるようスケジュールされます。例えば10:53といった形でこの時刻を避けることで遅延を回避することができる可能性があります。
from オブジェクト Yes Unicodeエンコードされた文字を含まないこと
送信元のメールアドレスと表示名を含むemailオブジェクトです。fromフィールドではUnicodeエンコードはサポートされていません。.
email string Yes
送信元のメールアドレス
name string No
送信元の表示名
reply_to オブジェクト No
返信先のメールアドレスと表示名を含むemailオブジェクトです。
email string Yes
返信先のメールアドレス
name string No
返信先の表示名
subject string Yes
メールの件名。この値はpersonalizations[x].subjectによって上書かれます.
content オブジェクト配列 Yes＊ 最低1＊
メールの本文を含む配列です。複数のMIMEタイプの本文を含めることができますが、最低1つは指定する必要があります。複数のMIMEタイプを含めるには、配列に対してtypeとvalueパラメータから構成されるオブジェクトを追加します。この場合、text/plain→text/htmlの順で配列の最初に含める必要があります。text/plainもしくはtext/htmlいずれかのMIMEタイプを含める場合、それらはcontent配列の最初に含めなくてはいけません。
＊トランザクショナルテンプレートを使用してリクエストにtemplate_IDを指定している場合はコンテンツは必須ではありません。
type string Yes 最低1
メールに追加する本文のMIMEタイプです。例えば、text/plainやtext/htmlなど
value string Yes 最低1
MIMEタイプに対応した実際の本文です。
attachments オブジェクト配列 No
添付ファイルのオブジェクト配列
content string Yes
添付ファイルのコンテンツをBase64エンコードしたもの
type string No
添付するコンテンツのMIMEタイプ。例えば、application/pdfやimage/jpegなど
filename string Yes
添付ファイルのファイル名
disposition string No
添付ファイルの表示方法を指定します。例えば、 "inline" を指定すると自動的に本文内に表示されますが、 "attachment" を指定すると添付ファイルを表示するために何らかのアクション(例えば、ファイルを開く、ダウンロードする、など)が必要になります。 初期値は "attachment" です。"attachment" または "inline" が指定可能です。
content_id string No
添付ファイルを特定するためのユニークIDです。これはdispositionが"inline"指定され、かつ添付ファイルが画像の場合に使用されます。これにより、メール本文内でのファイルの表示位置を指定できます。例： <img src="cid:ii_139db99fdb5c3704"></img>
template_id string No
テンプレートIDを指定します。本文(textおよびhtml)と件名を含むテンプレートを使用する場合、personalizationsレベルおよびメッセージレベルで、それら（本文や件名）を指定する必要がなくなります。
sections カスタムオブジェクト No
key/valueペアのオブジェクトで、substitutionタグを使用してメールに挿入する大きなコンテンツブロックを定義します。
headers カスタムオブジェクト No
ヘッダ名と値をkey/valueペアとして含むオブジェクトです。Unicode文字は、適切にエンコードする必要があります。次の予約済みヘッダを含めることはできません： x-sg-id, x-sg-eid, received, dkim-signature, Content-Type, Content-Transfer-Encoding, To, From, Subject, Reply-To, CC, BCC
categories string配列 No 最大255
このメッセージのカテゴリ名の配列です。各カテゴリ名は255文字を超えることはできません。1リクエストあたり10カテゴリを超えて指定することはできません。
custom_args カスタムオブジェクト No
カスタム引数は送信メールとイベントデータ（ActivityおよびEvent Webhookで確認可能）を紐付けることができます。カスタム引数の値は、メール本文中に含まれることはありません。また、substitutionsを利用してカスタム引数の値を置換することはできません。 このカスタム引数はリクエスト内の全てのメールに適用されます。ただし、personalization内のカスタム引数に同じキーが指定されていた場合、このカスタム引数ではなく、personalization内の値が適用されます。カスタム引数の合計サイズは、10,000バイトを超えてはいけません。
send_at integer No
SendGridから送信される時刻を表すUNIXタイムスタンプです。リクエスト時にメール送信する場合、このパラメータは指定不要です。
batch_id string No
このIDは、スケジュール送信においてメールの束（複数の宛先への同じメールの送信）がお互いに関連することを表します。送信リクエストにbatch_idを含めることで、その送信リクエストをメールの束に含めることができ、すべての束をキャンセルまたは一時停止することができるようになりす。詳細については、Cancel Scheduled Sendsを参照してください。
asm オブジェクト No
配信停止の扱いを指定するオブジェクト
group_id integer Yes
このメールに紐付ける配信停止グループ
groups_to_display integer配列 No 最大25
購読グループの選択ページに表示する配信停止グループの配列
ip_pool_name string No 最低2, 最大64
このメールの送信元となるIPプール
mail_settings オブジェクト No
メールの扱いを指定するメール設定
bcc オブジェクト No
mail_settings.bccに指定したアドレスはpersonalizations配列の最初に定義される形でブラインドカーボンコピー（Bcc）を受信します。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
email string No
Bccを受け取るメールアドレス
bypass_list_management オブジェクト No
すべての配信停止グループとサプレッションリストを無視してメールの送信を試みる設定です。この設定は本当に必要な場合に限り応急的に使用するようにしてください。例: 障害発生通知やパスワードリセット通知など
enable boolean No trueまたはfalse
設定が有効か否かを表します。
footer オブジェクト No
すべてのメールの末尾に追加するフッタ設定です。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
text string No
フッタのPlainテキストコンテンツ
html string No
フッタのHTMLコンテンツ
sandbox_mode オブジェクト No
要求のボディパラメータの内容や形式が正しいことを確認するための設定です。詳細についてはClassroomを参照してください。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
spam_check オブジェクト No
メールコンテンツの迷惑メール判定を行います。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
threshold integer No 最大10
メールコンテンツを迷惑メールとみなすしきい値で、1〜10の範囲で指定します。10は最も厳しい設定で、より迷惑メールと判定されやすくなりますす。
post_to_url string No
迷惑メールレポートの送信先URLです。post_to_urlパラメータはhttp://またはhttps://で始まる文字列である必要があります。
tracking_settings オブジェクト No
受信者とメールの相互作用をトラッキングするための設定です。
click_tracking オブジェクト No
メール本文内のリンクのクリックトラッキング設定です。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
enable_text boolean No trueまたはfalse
テキストパート内のリンクをトラッキング対象とするか否かの設定です。
open_tracking オブジェクト No
メールの開封トラッキング設定です。設定を有効化するとHTMLパートに小さな画像が自動的に埋め込まれ、この画像にアクセスされるとメールが開封されたことを検知できます。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
substitution_tag string No
メール本文の任意の場所に画像を埋め込むための置換タグです。ここで指定したタグが開封トラッキング用画像に置換されます。
subscription_tracking オブジェクト No
メールのテキストパートおよびHTMLパートの末尾に配信停止用リンクを埋め込むための設定です。リンクの位置を指定する場合は、substitution_tagを使用してください。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
text string No
テキストパートに追加する配信停止リンクを含む文字列です。<% %>タグを使用してリンクの挿入位置を指定できます。
html string No
HTMLパートに追加する配信停止リンクを含む文字列です。<% 任意の文字列 %>タグを使用してリンクの挿入位置を指定できます。
substitution_tag string No
配信停止リンクに置換されるタグです。例：[unsubscribe_url]。 このパラメータが使用された場合、textおよびhtmlパラメータ両方が置換対象となります。リンクのURLは置換タグの位置にそのまま配置されます。
ganalytics オブジェクト No
Google Analyticsでトラッキングを行うための設定です。
enable boolean No trueまたはfalse
設定が有効か否かを表します。
utm_source string No
キャンペーンのソース (例： Google, SomeDomain.com, Marketing Email)
utm_medium string No
キャンペーンのメディア (例： Email)
utm_term string No
キャンペーンのキーワード（検索広告キーワード）
utm_content string No
キャンペーンのコンテンツ（広告との区別用）
utm_campaign string No
キャンペーン名 (商品名など)

応答例

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

Response Code: 202 Accepted
Response Headers:
    Access-Control-Allow-Headers →Authorization, Content-Type, On-behalf-of, x-sg-elas-acl
    Access-Control-Allow-Methods →POST
    Access-Control-Allow-Origin →https://sendgrid.api-docs.io
    Access-Control-Max-Age →600
    Connection →keep-alive
    Content-Length →0
    Content-Type →text/plain; charset=utf-8
    Date →Mon, 23 Oct 2017 23:09:41 GMT
    Server →nginx
    X-Message-Id →kA5kcHA8SVGtVh5S9rAUew
    X-No-CORS-Reason →https://sendgrid.com/docs/Classroom/Basics/API/cors.html
Response Body:

Event Webhookを利用している場合、イベントの重複を取り除くためにX-Message-IDを利用して識別することをお勧めします。