Skip to contentSkip to navigationSkip to topbar
On this page

Using the SendGrid v2 Web API


(warning)

This documentation is for the SendGrid Web API v2

We will deprecate this version on February 10, 2025. To access all the latest features and upcoming developments, please see our v3 API. For assistance with transitioning, refer to our migration guide.


URL Format

url-format page anchor

The following is the syntax for making Web API requests:

Example WEB API URL

example-web-api-url page anchor

https://api.sendgrid.com/api/[module].[action].[format]

  • [module] - The API endpoint to call, e.g. blocks.
  • [action] - Each module supports multiple actions such as add, get, and delete.
  • [format] - This determines the response format. It can be either json for a JSON response or xml for an XML response.
https://api.sendgrid.com/api/blocks.get.json


  • 2XX - The API call was successful.
  • 4XX - The API call had an error in the parameters. The error will be encoded in the body of the response.
  • 5XX - The API call was unsuccessful. You should retry later.

The formats supported are XML and JSON. Errors and success responses are described below while calls that provide information have their own return structure.

  • XML

    1
    <result>
    2
    <message>error</message>
    3
    <errors>
    4
    ...
    5
    <error>... error messages ...</error>
    6
    ...
    7
    </errors>
    8
    </result>
  • JSON

    1
    {
    2
    "message": "error",
    3
    "errors": [
    4
    "...error messages..."
    5
    ]
    6
    }
  • XML

    1
    <result>
    2
    success
    3
    </result>
  • JSON

    1
    {
    2
    "message": "success"
    3
    }


SendGrid's API keys should be used when sending email over the API. API keys are preferred because you can revoke an API key at any time without changing your username and password. You can also limit the permissions of an API key, which reduces the potential for harm in the event that your API key is compromised.

When using an API key, pass it in an Authorization header and omit the api_user and api_key parameters from your request. Pass the API key as a Bearer Token: "Authorization: Bearer <Your API Key>"

For more information, see Upgrading your authentication method to API Keys.


Twilio SendGrid has a default rate limit of 600 requests/minute on some of the V2 API endpoints. If you exceed that rate limit you will receive a 429 error response with a "too many requests" message.

1
HTTP/1.1 429 TOO MANY REQUESTS
2
Content-Type: application/json
3
X-RateLimit-Limit: 150
4
X-RateLimit-Remaining: 0
5
X-RateLimit-Reset: 1392815263
6
7
{
8
"errors": [
9
{
10
"field": null,
11
"message": "too many requests"
12
},
13
]
14
}
(information)

Info

Note that this rate limit does not affect the V2 mail/send endpoint.


When you send data a GET request, it usually means that you're sending data in the URL's query string, the part after the '?' in the URL, as a key/value pair. The key is defined by the place where you are sending the data and is assumed to be URL-safe, however the data you provide may not be. So, you should URL encode the value (or the data part) of any URL-passed information.

For example, when you query google.com for sendgrid.com/docs/ you get the following URL:

https://www.google.com/?gws_rd=ssl#q=sendgrid.com%2Fdocs%2F

Where sendgrid.com/docs/ was encoded to sendgrid.com%2Fdocs%2F in the URL.

Most programming languages have support for URL encoding, but should you need a character lookup to reference, please see the Wikipedia doc about URL encoding(link takes you to an external page).

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.