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.

Unsubscribes

Retrieve, delete, and add entries in the Unsubscribes list.

Get

Retrieve a list of Unsubscribes with addresses and optionally with dates.

URI Parameter Required Requirements Description
date No Must be set to 1. Retrieve the timestamp of the unsubscribe records. It will return a date in a MySQL timestamp format - YYYY-MM-DD HH:MM:SS.
days No If specified, must be an integer greater than 0. Number of days in the past for which to retrieve unsubscribes (includes today).
start_date No Date must be in YYYY-MM-DD format and be earlier than the end_date parameter. The start of the date range for which to retrieve unsubscribes.
end_date No Date must be in YYYY-MM-DD format and be later than the start_date parameter. The end of the date range for which to retrieve unsubscribes.
limit No Some integer. Optional field to limit the number of results returned.
offset No Some integer. Optional beginning point in the list to retrieve from.
email No Email address (e.g. testing@example.com). Optional email addresses to search for.

Call

GET https://api.sendgrid.com/api/unsubscribes.get.json
GET Data api_user=apikey&api_key=your_sendgrid_api_key&date=1

Response

[
  {
    "email": "example@example.com",
    "created": "2012-09-06 14:03:18"
  }
]

Call

GET https://api.sendgrid.com/api/unsubscribes.get.xml
GET Data api_user=apikey&api_key=your_sendgrid_api_key&date=1

Response

<unsubscribes>
   <unsubscribe>
      <email>example@example.com</email>
      <created>2012-09-06 14:03:18</created>
   </unsubscribe>
</unsubscribes>

Delete

Delete an address from the Unsubscribe list. Use delete_all=1 in order to delete all addresses from your unsubscribe list.

URI Parameter Required Requirements Description
email No Must be a valid user account email. Unsubscribed email address to remove.

Call

POST https://api.sendgrid.com/api/unsubscribes.delete.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&email=emailToDelete@domain.com

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/unsubscribes.delete.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&email=emailToDelete@domain.com

Response

<result>
   <message>success</message>
</result>

Add

Add email addresses to the Unsubscribe list.

URI Parameter Required Requirements Description
email Yes Must be a valid email address. Email address to add to unsubscribe list.

Call

POST https://api.sendgrid.com/api/unsubscribes.add.json
POST Data api_user=apikey&api_key=your_sendgrid_api_key&email=email2@domain.com

Response

{
  "message": "success"
}

Call

POST https://api.sendgrid.com/api/unsubscribes.add.xml
POST Data api_user=apikey&api_key=your_sendgrid_api_key&email=email2@domain.com

Response

<result>
   <message>success</message>
</result>