Making a Request

Host

The host for API requests is https://api.sendgrid.com/v3/

All requests must be made over HTTPS. HTTP is not supported.

Authorization Header

You must provide an authorization header as described in Authentication.

HTTP Verbs

Depending on the resource, we support the following HTTP verbs:

Verb Description
GET Retrieve a resource or group of resources
POST Create a new resource
PUT Update an existing resource
DELETE Delete an existing resource
OPTIONS View allowed verbs against a specific resources

Accept Header

The API provides JSON responses. The accept header is not currently required, though it may be required in the future. If not set, the API will use application/json.

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

Arrays of Data

When you send an array of data in a GET request, you will include the parameter multiple times on the URL. We do not require that you add brackets to the parameter name.

Example Array in a GET request

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

Formatting Your Request

Request Body

When submitting data to a resource via POST or PUT, you must submit your payload in 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"
}

Pagination

Some GET resources allow for retrieval of information in batches. We will provide the query args in the resource documentation when available to consume.

When requesting multiple items, we will default the request limit to 500 items. You can specify a different limit but cannot not exceed the default limit.

Resources documented will display a bolded list of available paginated parameters if available.

Below is a basic pagination example. In the resource documentation, we will only provide the bolded list of available parameters.

When information is batched, a Link Header will be provided in the response.

1
GET https://api.sendgrid.com/v3/resource?limit=300&offset=10 HTTP/1.1
Parameter Description
limit The number of records to return
offset The number of records to skip

Search & Parameters

Some resources allow for you to search by a specific field. Other resources require you to append a parameter to the URI.

In this example, we will display a paginated uri example, searching for resources where the email contains foo.

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

Successful Requests

Below is a general overview of what resource objects are returned on successful Web API requests.

VerbResource object returned
GETA single resource object or array of resource objects
PATCHThe updated resource object is returned
PUTThe updated resource object is returned
DELETENo content is returned
POSTThe newly created resource object is returned