How to use the SendGrid V3 API

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



Making a Request


The host for Web API v3 requests is always

All requests must be made over HTTPS. The API does not support HTTP.

Authorization Header

You must provide an authorization header as described in Authentication.

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 resource

Accept Header

The API provides JSON responses. It doesn't currently require the accept header, but might in the future. If not set, the API will use application/json.

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. The parameter name does not require brackets.

#### Example Array in a GET request\


Formatting Your Request

Request Body

When submitting data to a resource via POST or PUT, you must submit your payload in JSON.

Content-Type: application/json
  "name": "new template name"


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 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.

A Link Header is provided in the response for batched information.

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.


Successful Requests

Below is a general overview of what resource objects return with successful Web API requests.

Verb Resource object returned
GET Returns a single resource object or array of resource objects
PATCH Returns the updated resource object
PUT Returns the updated resource object
DELETE No content is returned
POST Returns the newly created resource object
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more