API V3 Overview

Authentication

To authenticate, add an Authorization header to your API request that contains a base64-encoded username:password string. Read more about basic access authentication.

Example header:

1
2

GET https://api.sendgrid.com/v3/resource HTTP/1.1
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ===

If you want to use the API via curl, it has support for base64-encoded authentication built-in. For example:

1

curl -H "Content-Type: application/json" -u sendgrid_username -X POST -d '{"name":"example_name"}' https://api.sendgrid.com/v3/templates

You then enter your password at the prompt.

V3 API also supports the use of API Keys. API Keys allow you to use another method of authentication seperate from your username and password to your account. Keys add an additional layer of secuirty for your account. API Keys can be generated in your account - visit https://app.sendgrid.com/settings/api_keys. To use keys, you must set a plain text header named “Authorizaton” with the contents of the header being “Bearer XXX” where XXX is your API Secret Key.

Example header:

1
2

GET https://api.sendgrid.com/v3/resource HTTP/1.1
Authorization: Bearer Your.API.Key-HERE

1

curl -X "GET" "https://api.sendgrid.com/v3/templates" -H "Authorization: Bearer Your.API.Key-HERE" -H "Content-Type: application/json"

Host

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

Rate Limits

All calls within the Web API are allotted a specific number of requests per refresh period.

Each Web API request 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.

Example Request

1

GET https://api.sendgrid.com/v3/resource HTTP/1.1

Example Response

1
2
3
4
5
6
7
8
9

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499
X-RateLimit-Reset: 1392815263

{
  "foo": "bar"
}

When Limit is Reached

You will no longer be able to make requests against that endpoint for the duration of that refresh period.

Example Request

1

GET https://api.sendgrid.com/v3/resource/ HTTP/1.1

Example Response

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"
    },
  ]
}

Requests

Authorization Header

You must provide an authorization header as described in Authentication.

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

HTTP Verbs

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

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.

1

GET https://api.sendgrid.com/v3/resource?limit=300&offset=10 HTTP/1.1

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

Responses

Content-Type Header

All responses are returned in JSON format. We specify this by sending the Content-Type header.

1

GET https://api.sendgrid.com/v3/resource HTTP/1.1

1
2
3
4
5
6

HTTP/1.1 200 OK
Content-Type: application/json

{
    "foo": "bar",
}

Status Codes

Below is a table description of the various status codes we currently support against resources.

Successful Requests

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

Failed Requests

The general format guidelines are displayed when the accompanying status code is returned.

1

GET https://api.sendgrid.com/v3/resource HTTP/1.1

1
2
3
4
5
6
7
8
9
10

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "errors": [
      {"field": "identifier1", "message": "error message explained"},
      {"field": "identifier2", "message": "error message explained"},
      {"field": "identifier3", "message": "error message explained"},
    ]
}

Pagination

When a request is made with a 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

GET https://api.sendgrid.com/v3/resource?limit=5&offset=0 HTTP/1.1

1
2
3
4
5
6
7

HTTP/1.1 200 OK
Content-Type: application/json

Link: <http://api.sendgrid.com/v3/resource?limit=5&offset=5>; rel="next"; title="2",
      <http://api.sendgrid.com/v3/resource?limit=5&offset=0>; rel="prev"; title="1",
      <http://api.sendgrid.com/v3/resource?limit=5&offset=10>; rel="last"; title="3",
      <http://api.sendgrid.com/v3/resource?limit=5&offset=0>; rel="first"; title="1"

Was this helpful? Yes No Feedback

---

SendGrid Pricing | Try out SendGrid for free!