API V3 概要

Web API v3へようこそ！このAPIは、RESTfulで、機能が網羅されており、連携が容易で、7つの言語をサポートした公式ライブラリが提供されています。

Hello, World!

1
2
3
4
5

curl --request POST \
  --url https://api.sendgrid.com/v3/mail/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"personalizations": [{"to": [{"email": "example@example.com"}]}],"from": {"email": "example@example.com"},"subject": "Hello, World!","content": [{"type": "text/plain", "value": "Heya!"}]}'

SendGridはWeb API v3との連携を容易にする7つのライブラリを提供しています。

Web API v3の使用

認証

各API要求はAPIキーをAuthorizationヘッダに指定する必要があります。

1

 curl -X "GET" "https://api.sendgrid.com/v3/templates" -H "Authorization: Bearer Your.API.Key-HERE" -H "Content-Type: application/json"

要求

Web API v3への全ての要求はHTTPSを利用する必要があります。すべての要求に Content-Type: application/json ヘッダを含めることを推奨します。

Web API v3は完全にRESTfulでGET, POST, PUT, そしてDELETE（リソースに依存）が利用できます。

1
2
3
4
5
6

POST https://api.sendgrid.com/v3/templates/ HTTP/1.1
Content-Type: application/json

{
  "name": "new template name"
}

応答

Web API v3は要求に対する応答の解釈を助けるために、応答コード、content-typeヘッダ、ページネーションのうち必要なものを返します。

Your Request

1

GET https://api.sendgrid.com/v3/resource HTTP/1.1

Our Response

1
2
3
4
5
6

HTTP/1.1 200 OK
Content-Type: application/json

{
    "foo": "bar",
}

呼び出し制限

使用するエンドポイントによっては、一定時間に要求可能な要求数に制限があります。 このしきい値に達した場合、429の応答コードが返ります。

エラー

API要求がエラーを返す場合があります。各応答はエラーコード、エラーの理由、エラーメッセージを含み、デバッグを助けてくれます。

一般的なエラーメッセージについてはこちらを参照してください。v3 Mail Sendエンドポイント利用時の特定のエラーについてはこちらを参照してください。

コード 理由 詳細
4xx 4xxの応答は要求が失敗したことを意味します 要求内容に問題がありました
400 BAD REQUEST
401 UNAUTHORIZED 要求を送信するための認証情報がありません
403 FORBIDDEN
404 NOT FOUND 指定したリソースが存在しないか見つかりません
405 METHOD NOT ALLOWED
413 PAYLOAD TOO LARGE 指定されたJSONペイロードのサイズが大きすぎます
429 TOO MANY REQUESTS 要求数がSendGridの制限を超えました
5xx 5xxの応答はSendGrid側でエラーが発生したことを意味します 要求は正しいが、処理を試みたところSendGridにてエラーが発生しました
500 SERVER ERROR SendGridのサーバ上でエラーが発生しました
503 SERVICE NOT AVAILABLE v3 Web APIが利用できません