V3 Mail Send API概要

事前準備としてDomain Authenticationの設定が必須です。送信元に指定するドメインで設定を完了させていない場合はメールを送信できません。設定方法はこちらをご覧ください。

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

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

Request

POST https://api.sendgrid.com/v3/mail/send HTTP/1.1

Request Body

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

Response

{
  HTTP/1.1 202
}

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

cURLリクエストを利用する
7つのプログラミング言語向けライブラリを利用する

認証

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
	このメールに紐付ける配信停止グループ Global Unsubscribe、Group Unsubscribe、購読管理ページのいずれの機能を使用する場合でも指定が必要です。
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
	キャンペーン名 (商品名など)

応答例

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を利用して識別することをお勧めします。

メニュー

Request

Response

認証

制限事項

バリデーション

要求ボディパラメータ

応答例