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:

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:
bounceReasonintLimit returned data to selected bounce reason. Optional.
Valid values are:
1 – User unknown
2 – Mailbox full
3 – Blocked
6 – Unknown
7 – Other
bounceTypeintBounce type. Optional.
Valid values are:
1 – Hard
2 – Soft
3 – Transparent



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:

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

CSV response for channel set to:

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

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

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

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

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.

Bounce type (one of those will be in BounceReason column in CSV):

HardPersistent problem with email address.
SoftTemporary problem with email address.
TransparentTemporary problem not counted.


Get multiple messages


Accept-Encoding: gzip,deflate 
User-Agent: Jakarta Commons-HttpClient/3.1 

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,BounceReason, BounceType
2010-10-01 17:10:00,,some test bounce code, UserUnknown, Hard
2010-10-01 17:10:00,,some test bounce code, MailboxFull, Soft
2010-10-01 17:11:00,,some test bounce code, Blocked, Soft
2010-10-01 17:12:00,,some test bounce code, Unknown, Soft
2010-10-01 19:20:00,,some test bounce code, Other, Hard
On this page
To top