The Template Engine is the first feature available on SendGrid’s new API architecture. As a result, interacting with the endpoints described here is different than the other existing endpoints, so please read carefully!
To authenticate, add an
Authorization header to your API
request that contains a base64-encoded
string. Read more about basic access
If you want to use the API via
curl, it has support for base64-encoded
authentication built-in. For example:
The host for API requests is
All requests must be made over HTTPS. HTTP is not supported.
You must provide an authorization header as described in Authentication.
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
Depending on the resource, we support the following HTTP verbs:
|GET||Retrieve a resource or group of resouces|
|POST||Create a new resource|
|PUT||Update an existing resource|
|DELETE||Delete an existing resource|
|OPTIONS||View allowed verbs against a specific resources|
When submitting data to a resource via
PUT, you must
submit your payload in JSON.
1 2 3 4 5 6
All calls within the Web API are allotted a specific number of requests per refresh period.
Each Web API requests returns the following header information regarding rate limits and number of requests left.
Depending on the endpoint you are trying to reach, it will have a specific number of allowed requests per refresh period. Once this threshold has been reached, we will return a status code 429 response.
1 2 3 4 5 6 7 8 9
You will no longer be able to make requests against that endpoint for the duration of that refresh period.
1 2 3 4 5 6 7 8 9 10 11 12 13 14
GET resources allow for retrieval of information in batches. We
will provide the query args in the resource documentation when available
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.
In this example, we will display an example paginated example. In the resource documentation, we will only provide the bolded list of available parameters.
|limit||The number of records to return|
|offset||The number of records to skip|
Some resources allow 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
All responses are returned in JSON format. We specify this by sending
1 2 3 4 5 6
Below is a table description of the various status codes we corrently support against resources.
|500||Internal server error|
Below is a general overview of what resource objects are returned on successful Web API requests.
|Verb||Resource object returned|
|GET||A single resource object or array of resource objects|
|PATCH||The updated resource object is returned|
|DELETE||No content is returned|
|POST||The newly created resource object is returned|
The general format guidelines are displayed with the accompanying status code is returned.
1 2 3 4 5 6 7 8 9 10
When a request is made with pagination query, the following data is included in the header to allow for easy traversal of previous, current, first, and last page of the data set.
1 2 3 4 5 6 7