SendGrid has a Web API that allows customers to retrieve information about their account such as statistics, bounces, spam reports, unsubscribes, and other information. This API is not a RESTful API since in most calls both GET and POST HTTP verbs can be used interchangeably.

URL Format

The following is the format for the API requests:

• – The module to interact with. We support multiple modules such as bounces, profile, stats, and many others.
• – Each module supports multiple actions such as add, get, and delete. See our list of modules and actions.
• 
  – This determines the response format. It can be either json for a JSON response or xml for an XML response.

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.

Responses

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. Your credentials are the same used for your SMTP authentication and/or website.

• api_user – This is the same credential used for your SMTP settings, and for logging into the website.
• api_key – This is the same password to authenticate over SMTP, and for logging into the website.

Modules

The following is a list of all of our available modules and the available actions for each module.

Bounces

This module allows you to retrieve and delete email addresses that have bounced from emails that you’ve delivered.

Blocks

This module allows you to retrieve and delete email addresses that were blocked by their ISP. These emails are not suppressed and are just for information.

Email Parse

This module allows you to add, edit, or delete your email parse settings.

Event Notification URL

This module allows you to add, edit, or delete an event notification URL for your account.

Filters

This module allows you to view your available Apps, edit their settings, as well as enable and disable them. For a list of all the apps and parameters accesible with the Web API you can check the Filter Settings page.

Invalid Emails

This module allows you to retrieve and delete email addresses that you’ve sent to that are invalid email addresses.

Mail

This module allows you to send email.

Profile

This module allows you to retrieve and update your profile information such as credentials and email address.

Spam Reports

This module allows you to retrieve and delete email addresses that have marked your emails as SPAM.

Stats

This module allows you to retrieve statistical data on a range of metrics including requests, bounces, spam reports, categories, and others.

Unsubscribes

This module allows you to add, retrieve and delete email addresses that were unsubscribed from your emails.