Menu

Expand

This documentation is for the SendGrid Web API v2

To access all the latest features and upcoming developments, please see our v3 API.

Rate this page:

Using the SendGrid v2 Web API

URL Format

The following is the syntax for making Web API requests:

Example WEB API URL

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

Responses

HTTP Return codes

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

Errors

  • XML
    <result>
       <message>error</message>
       <errors>
          ...
          <error>... error messages ...</error>
          ...
       </errors>
    </result>
    

  • JSON
    {
      "message": "error",
      "errors": [
        "...error messages..."
      ]
    }
    

Success

  • XML
    <result>
    success
    </result>
    

  • JSON
    {
      "message": "success"
    }
    


Authentication

Each API call requires authentication. You must send the following HTTP parameters on your API calls. We highly recommend using an API key whenever possible. For more on API keys, see the SendGrid API keys documentation

  • api_user - This should always be the string "apikey" (without quotes).
  • api_key - This should be API key you generated on your account.

Example API URL with user & pass parameters

https://api.sendgrid.com/api/blocks.get.json?api_user=apikey&api_key=your_sendgrid_api_key

For detailed information on the available Web API methods, select one from the tree on the left.

Rate Limits

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.

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

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

The Data

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 urlencode 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 urlencoding, but should you need a character lookup to reference, please see the Wikipedia doc about urlencoding.

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. How could this documentation serve you better?

        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