Skip to content

Get bounces list

Using this method you can retrieve a CSV with a list of bounces for a particular time period.

The list includes bounce date, bounced email address, and diagnostic codes.

Request data format

Request URL parameters:

ParameterTypeNotes
apiKeystringYour API key, required for authentication. Required.
startDatedateStart date of bounces period. Required.
endDatedateEnd date of bounces period. Required.
channelstringLimit returned data to selected channel. Optional. Defaults to Email.
Valid values are:
AllEmailSmsMms 
bounceTypeintLimit returned data to selected bounce type. Optional.
Valid values are:
1 – User unknown2 – Mailbox full3 – Blocked6 – Unknown7 – Other

Examples:

https://api.esv2.com/v2/Api/Bounces?apiKey=YOUR_API_KEY_HERE&startDate=2010-05-20&endDate=2010-05-22

https://api.esv2.com/v2/Api/Bounces?apiKey=YOUR_API_KEY_HERE&startDate=2010-05-20&endDate=2010-05-22&bounceType=1

Response

The response from this method is always data in CSV format, rather than XML, because the amount of data returned can be substantial.

CSV response minimizes overheads and allows for seamless integration with third party code/systems.

Response content type is “text/csv”. Returned data contains a header with column names in the first row.

CSV output is formatted using following settings:

  • Field separator: comma (,)
  • Quoting character: (“)
  • Escape character: (“)
  • Encoding: UTF-8

CSV response columns:

ParameterTypeNotes
DatedatetimeBounce date. YYYY-MM-DD HH:MM:SS format.
EmailstringBounced email.
PhonestringBounced phone number.
BounceCodestringBounce diagnostic code used to recognize bounce type.
BounceTypestringBounce type. See below for all possible bounce types.

CSV response for channel set to:

  1. All:
    • Date
    • Email*
    • Phone*
    • BounceCode
    • BounceType

* In each row either Email or Phone should be filled in, never both.

  1. Email:
    • Date
    • Email
    • BounceCode
    • BounceType
  2. Phone
    • Date
    • Phone
    • BounceCode
    • BounceType

Bounce types (one of those will be in BounceType column in CSV):

NameDescription
UserUnknownEmail does not exist.
MailboxFullMailbox is full or otherwise temporary inaccessible.
BlockedMessage blocked, usually for spam-related reasons.
UnknownUnknown reason when bounce cannot be classified.
OtherOther bounce reason. This category contains transport-related issues, mail server bugs etc.

Examples

Get multiple messages

Request:

GET https://api.esv2.com/v2/Api/Bounces?apiKey=test_api_key1&startDate=2010-10-01&endDate=2010-10-02&channel=Email HTTP/1.1 
Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 
Host: api.esv2.com

OK response:

HTTP/1.1 200 OK 
Cache-Control: private 
Content-Type: text/csv; charset=utf-8 
Server: Microsoft-IIS/7.5 
X-AspNetMvc-Version: 2.0 
X-AspNet-Version: 2.0.50727 
Set-Cookie: TIMEZONE=Central European Standard Time; path=/ 
X-Powered-By: ASP.NET 
Date: Thu, 08 Dec 2011 12:02:14 GMT 
Content-Length: 463  
 

Date,Email,BounceCode,BounceType
2010-10-01 17:10:00,test1@yahoo.com,some test bounce code,UserUnknown 
2010-10-01 17:10:00,test2@yahoo.com,some test bounce code,MailboxFull 
2010-10-01 17:11:00,test3@yahoo.com,some test bounce code,Blocked
2010-10-01 17:12:00,test4@yahoo.com,some test bounce code,Unknown
2010-10-01 19:20:00,john.doe@gmail.com,some test bounce code,Other
On this page
To top