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
|
|
応答
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
|
|
詳細については、こちらを参照してください。
呼び出し制限(Rate Limits)
一部のv2 APIエンドポイントには、 1分あたり600リクエストの呼び出し制限が設けられています。 制限を超えると、ステータスコード:429(too many requests)のレスポンスが返されます。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
v2 mail/sendエンドポイントは、本制限の対象外となります。
データのエンコード
GETリクエストを利用する場合、通常クエリストリングでデータを送信することを意味します。クエリストリングはURLの’?’以降の部分のキー/値のペアです。キーはデータを送信する場所で定義されておりURLセーフですが、値はURLセーフとは限りません。 URLで送信する全ての情報はURLエンコードが必要です。
例えば、google.comに対して”sendgrid.com/docs/”という値のクエリを送信する場合以下のようなURLになります。
1
|
|
ここで “sendgrid.com/docs/” は “sendgrid.com%2Fdocs%2F” にエンコードされました。
ほとんどのプログラミング言語はURLエンコードをサポートしています。詳しくは各言語のリファレンスを参照してください。また、Wikipediaも参照してください。