Web API V2の使用方法

Web API v2（V2 Mail Sendを除く）は2025年2月に提供を終了します。

新たにWeb APIを利用する場合は、Web API v3をご利用ください。

Web API v2をご利用中の場合はWeb API v3へ移行してください。

URLフォーマット

以下はWeb APIリクエストを作成するための構文です。

Example WEB API URL

https://api.sendgrid.com/api/[module].[action].[format]

  • [module] - APIのエンドポイントです。
  • [action] - 各モジュールは複数のアクションをサポートしています。add, get, deleteなどです。
  • [format] - 応答フォーマットを決定します。JSONの場合”json”、XMLの場合”xml”が利用可能です。
1

https://api.sendgrid.com/api/blocks.get.json

応答

HTTP応答コード

  • 2XX - APIコールが成功
  • 4XX - APIコールのパラメータにエラーがあります。応答のBodyにエラーの内容が含まれます。
  • 5XX - APIコールが失敗しました。時間をおいてリトライしてください。

応答の形式はXMLとJSONをサポートしています。失敗および成功時の応答を以下に示します。

失敗時

  • XML 
    1
2
3
4
5
6
7
8

    <result>
   <message>error</message>
   <errors>
      ...
      <error>... error messages ...</error>
      ...
   </errors>
</result>
  • JSON 
    1
2
3
4
5
6

    {
  "message": "error",
  "errors": [
    "...error messages..."
  ]
}

成功時

  • XML 
    1
2
3

    <result>
success
</result>
  • JSON 
    1
2
3

    {
  "message": "success"
}

認証

API経由でメールを送信する際はAPIキーを使用してください。APIキーは、ユーザ名とパスワードに影響を与えることなく削除や権限設定変更ができるため、APIキーが漏洩した場合のリスクを低減できます。

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

1

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

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

呼び出し制限(Rate Limits)

一部のv2 APIエンドポイントには、 1分あたり600リクエストの呼び出し制限が設けられています。 制限を超えると、ステータスコード：429（too many requests）のレスポンスが返されます。

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

HTTP/1.1 429 TOO MANY REQUESTS
Content-Type: application/json
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1392815263

{
  "errors": [
    {
      "field": null,
       "message": "too many requests"
    },
  ]
}

v2 mail/sendエンドポイントは、本制限の対象外となります。

データのエンコード

GETリクエストを利用する場合、通常クエリストリングでデータを送信することを意味します。クエリストリングはURLの’?’以降の部分のキー/値のペアです。キーはデータを送信する場所で定義されておりURLセーフですが、値はURLセーフとは限りません。 URLで送信する全ての情報はURLエンコードが必要です。

例えば、google.comに対して”sendgrid.com/docs/”という値のクエリを送信する場合以下のようなURLになります。

1

https://www.google.com/?gws_rd=ssl#q=sendgrid.com%2Fdocs%2F

ここで “sendgrid.com/docs/” は “sendgrid.com%2Fdocs%2F” にエンコードされました。

ほとんどのプログラミング言語はURLエンコードをサポートしています。詳しくは各言語のリファレンスを参照してください。また、Wikipediaも参照してください。