Web API V2の使用方法

こちらはWeb API v2に関するページです。
現在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も参照してください。