Welcome to SendGrid’s Web API v3! This API is RESTful, fully featured, easy to integrate with, and offers support in 7 different languages.

Hello, World!

1
2
3
4
5
curl --request POST \
  --url https://api.sendgrid.com/v3/mail/send \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"personalizations": [{"to": [{"email": "your.email@example.com"}]}],"from": {"email": "example@example.com"},"subject": "Hello, World!","content": [{"type": "text/plain", "value": "Heya!"}]}'

SendGrid provides 7 different libraries to help you quickly and easily integrate with the Web API v3.

Using the Web API v3

Authentication

Every API request you make to the Web API v3 must be authenticated by including an Authorization Header with your API Key.

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

Requests

All requests to the Web API v3 must be made via HTTPS. The Web API v3 is completely RESTful and accepts GET, POST, PUT, and DELETE requests, depending on the resource.

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

{
  "name": "new template name"
}

Responses

The Web API v3 provides a selection of response codes, content-type headers, and pagination options to help you interpret the responses to your API requests.

Your Request

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

Our Response

1
2
3
4
5
6
HTTP/1.1 200 OK
Content-Type: application/json

{
    "foo": "bar",
}

Rate Limits

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.

Errors

Sometimes your API call will generate an error. Every response to an API call that generates an error will include an error code, the reason for the error, and an error message to help you debug your request.

For an example of a generic error message, click here. For a list of specific errors that may be returned when using the v3 Mail Send endpoint, click here.

Code Reason Description
4xx 4xx responses indicate an error with your request There was a problem with your request.
400 BAD REQUEST
401 UNAUTHORIZED You do not have authorization to make the request.
403 FORBIDDEN
404 NOT FOUND The resource you tried to locate could not be found or does not exist.
405 METHOD NOT ALLOWED
413 PAYLOAD TOO LARGE The JSON payload you have included in your request is too large.
429 TOO MANY REQUESTS The number of requests you have made exceeds SendGrid’s rate limitations.
5xx 5xx responses indicate an error made by SendGrid The request you made was valid, but an error occurred when SendGrid attempted to process it.
500 SERVER ERROR An error occurred on a SendGrid server.
503 SERVICE NOT AVAILABLE The SendGrid v3 Web API is not available.