The Report List Bounces command allows you to get the Contact Data for all Contact Emails that have bounced from a mailbox for a Campaign sent from a specific List.
GET /lists/[listId]/bounces?querystring
https://[siteurl]/rest/lists/[listId]/bounces?querystring
The following queries are supported:
start=[yyyy-mm-dd]
end=[yyyy-mm-dd]
bounceTypes=[bounceType]
Bounce types include:
- HARD_BOUNCE
- SOFT_BOUNCE
- BLOCKED
Request Body Parameters
The Report List Bounces command requires the URI call with the List ID. Optional Filters include Start and End Date parameters and Bounce Type. No additional fields are required in the JSON.
The query strings 'start', 'end', and 'bounceTypes' are case sensitive and must be defined as in the example above. The Date fields support the date format yyyy-mm-dd. If the query string is incorrect or missing, it is ignored and the command returns all Bounces for the List.
The query assumes the time of midnight of the date defined. For instance, to get only Contacts with an event on June 15th, 2016, set the dates to the following:
start=2016-06-15
end=2016-06-16
To include events that occurred on the 16th also, set the end date to one day greater than 16, June 17th.
Request Body Example
Using Report List Bounces:
curl --request GET \
--url 'https://mail.mydomain.com/rest/lists/10/bounces?start=2016-06-01&end=2016-06-30' \
--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \
--header 'accept: application/vnd.whatcounts-v1+json' \
--header 'content-type: application/json' \
--include
Response Body
The response returns Contact data in JSON format for each Contact that matches any of the query fields. It also includes the type of bounce for each Contact (Hard, Soft, Block), the total number of Contacts returned, and number of Bounces.
If more than 500 results are found, the first 500 are displayed, and you must use the "skip" value to view the next 500.
For example, to find the three groups of 500 Contacts in a List with 1455 matching Contacts, the URIs would be formatted as:
- https://[siteurl]/rest/lists/[listId]/bounces?start=2016-06-01&end=2016-06-30&skip=0
- https://[siteurl]/rest/lists/[listId]/bounces?start=2016-06-01&end=2016-06-30&skip=500
- https://[siteurl]/rest/lists/[listId]/bounces?start=2016-06-01&end=2016-06-30&skip=1000
For more information about "skip", see Pagination.
Based on the example above, and two matching Contacts from the List, the response returns:
HTTP/1.1 200 OK
Server: serverName
Content-Type: application/json
Link: <https://mail.mydomain.com/rest/lists/10/bounces?start=2016-06-15&end=2016-06-16>;
Date: Fri, 17 Jun 2016 12:54:44 GMT
{
"subscribers": 2
{
"date": "Nov 21, 2015 6:14:16 AM"
"bounceType": "HARD_BOUNCE"
"subscriberId": 7160984
"realmId": 1561
"email": "jon.doe@mydomain.com"
"firstName": "Jon"
"lastName": "Doe"
"company": "My Company"
"address1": "123 Some Street North"
"address2": "Suite 500"
"city": "My City"
"state": "WA"
"zip": "98000"
"country": "United States"
"phone": "(206) 555 1212"
"fax": ""
"createdDate": "May 21, 2012 9:14:16 AM"
"updatedDate": "Nov 2, 2015 10:31:27 AM"
"md5Encryption": "C8ADED17D5F088E8262BF31ED933B7D4"
"sha1Encryption": "356B1860247728C81486A35062688F302D96C2D1"
"skip": 1
"max": 0
}
"date": "May 5, 2016 10:14:16 PM"
"bounceType": "SOFT_BOUNCE"
"subscriberId": 25158866
"realmId": 1561
"email": "jane.doe@mydomain.com"
"firstName": "Jane"
"lastName": ""
"company": ""
"address1": ""
"address2": ""
"city": ""
"state": ""
"zip": ""
"country": ""
"phone": ""
"fax": ""
"createdDate": "May 4, 2015 9:48:33 AM"
"updatedDate": "Jun 13, 2016 1:06:46 PM"
"md5Encryption": "5EBD1AAAEA76811129331B0FA649F48C"
"sha1Encryption": "811B2A6ADC716AFFF1127A7B27D2F7B81167AB2E"
"skip": 0
"max": 0
}
"bounceTotal": 2
}
Error Response
Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes.
For example, if the Authorization is incorrect, the error would appear as:
{
"error": "Unauthorized"
"status": "Unauthorized"
"statusCode": 401
}