On this page

Invalid Emails

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

This endpoint allows you to retrieve and delete entries in the Invalid Emails list.

Get

Retrieve a list of invalid emails with addresses and response codes, optionally with dates.

URI Parameter	Required	Requirements	Description
date	No	Must be set to 1	Retrieve the timestamp of the invalid email 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 invalid emails (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 invalid emails.
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 invalid emails.
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.

JSONXML

Call

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

Response

1[
2  {
3    "reason": "Known bad domain",
4    "created": "2011-06-06 16:11:57",
5    "email": "test@example.com"
6  },
7  {
8    "reason": "Invalid address",
9    "created": "2012-08-17 11:04:38",
10    "email": "brandon"
11  }
12]

Count

Retrieve the count of invalid emails.

URI Parameter	Required	Requirements	Description
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 invalid emails.
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 invalid emails.

JSONXML

Call

GET	`https://api.sendgrid.com/api/invalidemails.count.json`
GET Data	`api_user=apikey&api_key=your_sendgrid_api_key`

Response

1{
2  "count": 2
3}

Delete

Delete an address from the Invalid Email list.

URI Parameter	Required	Requirements	Description
email	Yes	Must be a valid user account email	Email Invalid Email address to remove

JSONXML

Call

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

Response

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