Перейти к содержимому

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:
All
Email
SmsMms 
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

Examples:

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

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.
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):

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.

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

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

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,BounceReason, BounceType
2010-10-01 17:10:00,test1@yahoo.com,some test bounce code, UserUnknown, Hard
2010-10-01 17:10:00,test2@yahoo.com,some test bounce code, MailboxFull, Soft
2010-10-01 17:11:00,test3@yahoo.com,some test bounce code, Blocked, Soft
2010-10-01 17:12:00,test4@yahoo.com,some test bounce code, Unknown, Soft
2010-10-01 19:20:00,john.doe@gmail.com,some test bounce code, Other, Hard
Privacy policy