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 eg testing@example.com Optional email addresses to search for.
Parameter Value Requirements Description

Call

GET https://api.sendgrid.com/api/invalidemails.get.json?api_user=your_sendgrid_username&api_key=your_sendgrid_password&date=1

Response

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

Call

GET https://api.sendgrid.com/api/invalidemails.get.xml?api_user=your_sendgrid_username&api_key=your_sendgrid_password&date=1

Response

1
2
3
4
5
6
7
8
9
10
11
12
<invalidemails>
   <invalidemail>
      <reason>Known bad domain</reason>
      <created>2011-06-06 16:11:57</created>
      <email>test@example.com</email>
   </invalidemail>
   <invalidemail>
      <reason>Invalid address</reason>
      <created>2012-08-17 11:04:38</created>
      <email>brandon</email>
   </invalidemail>
</invalidemails>

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.
Parameter Value Requirements Description

Call

GET https://api.sendgrid.com/api/invalidemails.count.json?api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
{
  "count": 2
}

Call

GET https://api.sendgrid.com/api/invalidemails.count.xml?api_user=your_sendgrid_username&api_key=your_sendgrid_password

Response

1
2
3
4
<result>
   <count>2</count>
   <result> </result>
</result>

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
Parameter Value Requirements Description

Call

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

Response

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

Call

POST https://api.sendgrid.com/api/invalidemails.delete.xml
POST Data api_user=your_sendgrid_username&api_key=your_sendgrid_password&email=emailToDelete@domain.com

Response

1
2
3
4
<result>
   success
   <result> </result>
</result>