Newsletter API Overview

SendGrid has a Newsletter API that allows users to access data and interact with the Newsletter functionality of SendGrid website. We also have a Newsletter web interface.

The Newsletter API provides developers with the ability to manage newsletters, lists, identities, and schedule delivery events. This can be very useful in allowing development teams to propagate data in and out of the web based Newsletter App that can be easily used by members of the company with little or no programming expertise.

The Newsletter API is very similar to the Web API in that it follows the same convention and format, and utilizes the same technology; http requests. This is done with http requests to the SendGrid site with a variety of parameters to organize data. All query responses can be provided in either JSON or XML.

URL Format

The following is the syntax for making Newsletter API requests:

https://sendgrid.com/api/newsletter/[action].[format]
  • [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.

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 
    1
2
3
4
5
6
7
8
9
10

    <?xml version="1.0" encoding="ISO-8859-1"?>

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

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

Success

  • XML 
    1
2
3
4
5

    <?xml version="1.0" encoding="ISO-8859-1"?>

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

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

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