Bounces

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

get

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

Parameter Required Requirements Description
date No Must be set to 1 Retrieve the timestamp of the bounce 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 bounces (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 bounces.
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 bounces.
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.
type No hard or soft choose the type of bounce to search for.
email No email address eg testing@example.com optional email addresses to search for.

Call

1

https://sendgrid.com/api/bounces.get.json?api_user=youremail@domain.com&api_key=secureSecret&date=1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

[
  {
    "status": "4.0.0",
    "created": "2011-09-16 22:02:19",
    "reason": "Unable to resolve MX host sendgrid.ne",
    "email": "esting@sendgrid.ne"
  },
  {
    "status": "4.0.0",
    "created": "2011-09-19 17:47:15",
    "reason": "Connection timed out",
    "email": "rawest@gmail.co"
  },
  {
    "status": "5.1.1",
    "created": "2011-10-17 11:07:10",
    "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at http://mail.google.com/support/bin/answer.py?answer=6596 z10si838244anz.171 ",
    "email": "claims@msp.org"
  },
  {
    "status": "5.7.1",
    "created": "2011-10-26 23:06:22",
    "reason": "550 5.7.1 <info@bnl.co.uk>... Relaying denied. Proper authentication required. ",
    "email": "info@bnl.co.uk"
  },
  {
    "status": "5.7.1",
    "created": "2011-12-01 01:45:55",
    "reason": "554 5.7.1 <richard@hengseng.com>: Relay access denied ",
    "email": "richard@hengseng.com"
  },
  {
    "status": "550",
    "created": "2012-06-01 14:10:15",
    "reason": "550 support.sendgrid.net [74.63.202.100] is currently not permitted to relay through this server. Perhaps you have not logged into the pop/imap server in the last 30 minutes or do not have SMTP Authentication turned on in your email client. ",
    "email": "test@brandonmwest.com"
  }
]

Call

1

https://sendgrid.com/api/bounces.get.xml?api_user=youremail@domain.com&api_key=secureSecret&date=1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

<bounces>
   <bounce>
      <email>email1@domain.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: email1@domain.com</reason>
      <created>2009-06-10 12:40:30</created>
   </bounce>
   <bounce>
      <email>email2@domain2.com</email>
      <status>5.1.1</status>
      <reason>host [127.0.0.1] said: 550 5.1.1 unknown or illegal user: email2@domain2.com</reason>
      <created>2009-08-01 10:16:30</created>
   </bounce>
</bounces>

delete

Delete an address from the Bounce list. Please note that if no parameters are specified the ENTIRE list will be deleted.

Parameter Required Requirements Description
start_date No Date must be in YYYY-mm-dd format and be before the end_date parameter Optional date to start deleting from.
end_date No Date must be in YYYY-mm-dd format and be after the start_date parameter Optional date to end deleting from.
type No hard or soft choose the type of bounce to be removed.
email No Must be a valid user account email Email bounce address to remove

Call

1

https://sendgrid.com/api/bounces.delete.json?api_user=youremail@domain.com&api_key=secureSecret&email=emailToDelete@domain.com

Response: Success

1
2
3

{
  "message": "success"
}

Response: Error

1
2
3

{
  "message": "Email does not exist"
}

Call

1

https://sendgrid.com/api/bounces.delete.xml?api_user=youremail@domain.com&api_key=secureSecret&email=emailToDelete@domain.com

Response: Success

1
2
3
4
5
6

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

<result>
  success
@nodes
</result>

Response: Error

1
2
3
4
5

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

<result>
   <message>error: reason</message>
</result>

Count

Parameter Required Requirements Description
start_date No Date must be in YYYY-mm-dd format and be before the end_date parameter Optional date to start counting from.
end_date No Date must be in YYYY-mm-dd format and be after the start_date parameter Optional date to end counting from.
type No hard or soft choose the type of bounce to search for.

Call

1

https://sendgrid.com/api/bounces.count.json?api_user=youremail@domain.com&api_key=secureSecret

Response: Success

1
2
3

{
  "count": "4"
}

Response: Error

1
2
3
4
5
6

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

Call

1

https://sendgrid.com/api/bounces.count.xml?api_user=youremail@domain.com&api_key=secureSecret

Response: Success

1
2
3
4
5
6

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

<result>
   <count>4</count>
   @nodes
</result>

Response: Error

1
2
3
4
5

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

<result>
   <message>error: reason</message>
</result>