要求

要求の作成

ホスト

API要求のホストは https://api.sendgrid.com/v3/ です。

全てのリクエストはHTTPSを利用する必要があります。 HTTPはサポートされていません。

Authorizationヘッダ

Authenticationの内容に従って、Authorizationヘッダを指定する必要があります。

HTTP動詞

リソースにも依存しますが、以下のHTTP動詞をサポートしています。

動詞 説明
GET リソースまたはリソースグループを取得します
POST 新規リソースを作成します
PUT 既存のリソースを更新します
DELETE 既存のリソースを削除します
OPTIONS 指定したリソースでサポートしている動詞を確認します

Acceptヘッダ

APIはJSON形式の応答を返します。Acceptヘッダは現在必須ではありませんが、将来必須になる可能性があります。指定しない場合、application/jsonとして扱われます。

1
2
GET https://api.sendgrid.com/v3/endpoint HTTP/1.1
Accept: application/json

配列データ

GET要求でデータ配列を送信する場合、パラメータをURL内で複数回使用してください。パラメータ名を括弧で括る必要はありません。

GET要求での配列の例

1
GET https://api.sendgrid.com/v3/endpoint?parameter=data1&parameter=data2 HTTP/1.1

要求形式

ボディ

POSTまたはPUTでデータを送信する際、ペイロードはJSONで送信する必要があります。

1
2
3
4
5
6
POST https://api.sendgrid.com/v3/templates/ HTTP/1.1
Content-Type: application/json

{
  "name": "new template name"
}

ページネーション

いくつかのGET系リソースは数回にわけて情報の取得を行うことができます。この機能が利用可能な場合、各リソースのドキュメント上でクエリパラメータに関して説明をします。

複数の情報を取得する場合、レコード数500がデフォルトの上限値です。上限を指定して要求を送信することはできますが、デフォルト値を超えることはできません。

このパラメータが利用可能な場合、リソースのドキュメントで強調されたリストで表されます。

以下にページネーションの例を示します。

ページネーションが発生した場合、Linkヘッダが応答に含まれます。

1
GET https://api.sendgrid.com/v3/resource?limit=300&offset=10 HTTP/1.1
パラメータ 説明
limit 応答に含まれるレコード数上限
offset レコードの開始位置

検索とパラメータ

いくつかのリソースは特定のフィールドで検索をすることができます。その他のリソースはURIにパラメータを追加する必要があります。

以下に検索を行うURIの例を示します。この例は、emailにfooを含むリソースを検索します。

1
GET https://api.sendgrid.com/v3/resource?email=foo&bar=baz HTTP/1.1

成功時の応答

要求に成功した場合の一般的な応答内容を以下に示します。

動詞応答内のリソースオブジェクト
GET単一のリソースオブジェクトまたはリソースオブジェクトの配列
PATCH更新後のリソースオブジェクト
PUT更新後のリソースオブジェクト
DELETE何も返却されません
POST新しく作成されたリソースオブジェクト