Skip to contentSkip to navigationSkip to topbar
On this page

Bounces


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


Get

get page anchor

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

URI ParameterRequiredRequirementsDescription
dateNoMust 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.
daysNoIf specified, must be an integer greater than 0.Number of days in the past for which to retrieve bounces (includes today).
start_dateNoDate 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_dateNoDate 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.
limitNoSome integer.Optional field to limit the number of results returned.
offsetNoSome integer.Optional beginning point in the list to retrieve from.
typeNoHard or soft.Choose the type of bounce to search for.
emailNoEmail address e.g. testing@example.com.Optional email addresses to search for.
JSONXML

Call

GEThttps://api.sendgrid.com/api/bounces.get.json
GET Dataapi_user=apikey&api_key=your_sendgrid_api_key&date=1

Response

1
[
2
{
3
"status": "4.0.0",
4
"created": "2011-09-16 22:02:19",
5
"reason": "Unable to resolve MX host sendgrid.ne",
6
"email": "example@example.com"
7
},
8
{
9
"status": "4.0.0",
10
"created": "2011-09-19 17:47:15",
11
"reason": "Connection timed out",
12
"email": "example@example.com"
13
},
14
{
15
"status": "5.1.1",
16
"created": "2011-10-17 11:07:10",
17
"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 ",
18
"email": "example@example.com"
19
},
20
{
21
"status": "5.7.1",
22
"created": "2011-10-26 23:06:22",
23
"reason": "550 5.7.1 <example@example.com>... Relaying denied. Proper authentication required. ",
24
"reason": "550 5.7.1 <info@bnl.co.uk>... Relaying denied. Proper authentication required. ",
25
"email": "example@example.com"
26
},
27
{
28
"status": "5.7.1",
29
"created": "2011-12-01 01:45:55",
30
"reason": "554 5.7.1 <example@example.com>: Relay access denied ",
31
"reason": "554 5.7.1 <richard@hengseng.com>: Relay access denied ",
32
"email": "example@example.com"
33
},
34
{
35
"status": "550",
36
"created": "2012-06-01 14:10:15",
37
"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. ",
38
"email": "example@example.com"
39
}
40
]


Delete an address from the Bounce list.

URI ParameterRequiredRequirementsDescription
start_dateNoDate must be in YYYY-mm-dd format and be before the end_date parameter.Optional date to start deleting from.
end_dateNoDate must be in YYYY-mm-dd format and be after the start_date parameter.Optional date to end deleting from.
typeNoHard or soft.Choose the type of bounce to be removed.
emailNoMust be a valid user account email.Email bounce address to remove.
delete_allNoMust be set to 1.This will delete the bounce list and will not be retrievable.
JSONXML
POSThttps://api.sendgrid.com/api/bounces.delete.json
POST Dataapi_user=apikey&api_key=your_sendgrid_api_key&email=emailToDelete@domain.com
1
{
2
"message": "success"
3
}


URI ParameterRequiredRequirementsDescription
start_dateNoDate must be in YYYY-mm-dd format and be before the end_date parameter.Optional date to start counting from.
end_dateNoDate must be in YYYY-mm-dd format and be after the start_date parameter.Optional date to end counting from.
typeNoHard or soft.Choose the type of bounce to search for.
JSONXML
GEThttps://api.sendgrid.com/api/bounces.count.json
GET Dataapi_user=apikey&api_key=your_sendgrid_api_key
1
{
2
"count": "4"
3
}

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.