{"id":3695,"date":"2023-08-31T06:24:58","date_gmt":"2023-08-31T05:24:58","guid":{"rendered":"https:\/\/help.expertsender.com\/?post_type=es&p=3695"},"modified":"2024-06-24T13:59:51","modified_gmt":"2024-06-24T12:59:51","slug":"get-bounces-list","status":"publish","type":"es","link":"https:\/\/help.expertsender.com\/pl\/emp\/api\/methods\/get-bounces-list\/","title":{"rendered":"Get bounces list"},"content":{"rendered":"\n

Using this method you can retrieve a CSV with a list of bounces for a particular time period.<\/p>\n\n\n\n

The list includes bounce date, bounced email address, and diagnostic codes.<\/p>\n\n\n\n

<\/a><\/a>Request data format<\/strong><\/h3>\n\n\n\n

Request URL parameters:<\/p>\n\n\n\n

Parameter<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
apiKey<\/td>string<\/td>Your API key, required for authentication. Required.<\/td><\/tr>
startDate<\/td>date<\/td>Start date of bounces period. Required.<\/td><\/tr>
endDate<\/td>date<\/td>End date of bounces period. Required.<\/td><\/tr>
channel<\/td>string<\/td>Limit returned data to selected channel. Optional. Defaults to Email.
Valid values are:
All
Email
SmsMms\u00a0<\/td><\/tr>
bounceReason<\/td>int<\/td>Limit returned data to selected bounce reason. Optional.
Valid values are:
1 – User unknown
2 – Mailbox full
3 – Blocked
6 – Unknown
7 – Other<\/td><\/tr>
bounceType<\/td>int<\/td>Bounce type. Optional.
Valid values are:
1 – Hard
2 – Soft
3 – Transparent<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Examples:<\/p>\n\n\n\n

<\/path><\/path><\/svg><\/span>
https:\/\/api.esv2.com\/v2\/Api\/Bounces?apiKey=YOUR_API_KEY_HEREu0026amp;startDate=2010-05-20u0026amp;endDate=2010-05-22nn<\/span><\/span>\nhttps:\/\/api.esv2.com\/v2\/Api\/Bounces?apiKey=YOUR_API_KEY_HEREu0026amp;startDate=2010-05-20u0026amp;endDate=2010-05-22u0026amp;bounceReason=1<\/span><\/span>\nhttps:\/\/api.esv2.com\/v2\/Api\/Bounces?apiKey=YOUR_API_KEY_HERE&startDate=2010-05-20&endDate=2010-05-22&bounceType=2<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
Response<\/strong><\/h3>\n\n\n\n
The response from this method is always data in CSV format, rather than XML, because the amount of data returned can be substantial.<\/p>\n\n\n\n
CSV response minimizes overheads and allows for seamless integration with third party code\/systems.<\/p>\n\n\n\n
Response content type is “text\/csv”. Returned data contains a header with column names in the first row.<\/p>\n\n\n\n
CSV output is formatted using following settings:<\/p>\n\n\n\n
    \n
  • Field separator: comma (,)<\/li>\n\n\n\n
  • Quoting character: (“)<\/li>\n\n\n\n
  • Escape character: (“)<\/li>\n\n\n\n
  • Encoding: UTF-8<\/li>\n<\/ul>\n\n\n\n
    CSV response columns:<\/p>\n\n\n\n
    Parameter<\/th>Type<\/th>Notes<\/th><\/tr><\/thead>
    Date<\/td>datetime<\/td>Bounce date. YYYY-MM-DD HH:MM:SS format.<\/td><\/tr>
    Email<\/td>string<\/td>Bounced email.<\/td><\/tr>
    Phone<\/td>string<\/td>Bounced phone number.<\/td><\/tr>
    BounceCode<\/td>string<\/td>Bounce diagnostic code used to recognize bounce type.<\/td><\/tr>
    BounceReason<\/td>string<\/td>Bounce reason. See below for all possible bounce reason.<\/td><\/tr>
    BounceType<\/td>string<\/td>Bounce type. See below for all possible bounce types.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    CSV response for channel set to:<\/p>\n\n\n\n
      \n
    1. All:\n
        \n
      • Date<\/li>\n\n\n\n
      • Email*<\/li>\n\n\n\n
      • Phone*<\/li>\n\n\n\n
      • BounceCode<\/li>\n\n\n\n
      • BounceReason<\/li>\n\n\n\n
      • BounceType<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
        * In each row either Email or Phone should be filled in, never both.<\/p>\n\n\n\n
          \n
        1. Email:\n
            \n
          • Date<\/li>\n\n\n\n
          • Email<\/li>\n\n\n\n
          • BounceCode<\/li>\n\n\n\n
          • BounceReason<\/li>\n\n\n\n
          • BounceType<\/li>\n<\/ul>\n<\/li>\n\n\n\n
          • Phone\n
              \n
            • Date<\/li>\n\n\n\n
            • Phone<\/li>\n\n\n\n
            • BounceCode<\/li>\n\n\n\n
            • BounceReason<\/li>\n\n\n\n
            • BounceType<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n\n\n\n
              Bounce types (one of those will be in BounceType column in CSV):<\/p>\n\n\n\n
              Name<\/th>Description<\/th><\/tr><\/thead>
              UserUnknown<\/td>Email does not exist.<\/td><\/tr>
              MailboxFull<\/td>Mailbox is full or otherwise temporary inaccessible.<\/td><\/tr>
              Blocked<\/td>Message blocked, usually for spam-related reasons.<\/td><\/tr>
              Unknown<\/td>Unknown reason when bounce cannot be classified.<\/td><\/tr>
              Other<\/td>Other bounce reason. This category contains transport-related issues, mail server bugs etc.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
              Bounce type (one of those will be in BounceReason column in CSV):<\/p>\n\n\n\n
              Name<\/strong><\/td>Description<\/strong><\/td><\/tr>
              Hard<\/td>Persistent problem with email address.<\/td><\/tr>
              Soft<\/td>Temporary problem with email address.<\/td><\/tr>
              Transparent<\/td>Temporary problem not counted.<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
              Examples<\/strong><\/h3>\n\n\n\n
              Get multiple messages<\/strong><\/p>\n\n\n\n
              Request:<\/p>\n\n\n\n
              <\/path><\/path><\/svg><\/span>
              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 <\/span><\/span>\nAccept-Encoding: gzip,deflate <\/span><\/span>\nUser-Agent: Jakarta Commons-HttpClient\/3.1 <\/span><\/span>\nHost: api.esv2.com<\/span><\/span><\/code><\/pre><\/div>\n\n\n\n
              OK response:<\/p>\n\n\n\n
              <\/path><\/path><\/svg><\/span>
              HTTP\/1.1 200 OK <\/span><\/span>\nCache-Control: private <\/span><\/span>\nContent-Type: text\/csv; charset=utf-8 <\/span><\/span>\nServer: Microsoft-IIS\/7.5 <\/span><\/span>\nX-AspNetMvc-Version: 2.0 <\/span><\/span>\nX-AspNet-Version: 2.0.50727 <\/span><\/span>\nSet-Cookie: TIMEZONE=Central European Standard Time; path=\/ <\/span><\/span>\nX-Powered-By: ASP.NET <\/span><\/span>\nDate: Thu, 08 Dec 2011 12:02:14 GMT <\/span><\/span>\nContent-Length: 463  <\/span><\/span>\n<\/span>\nDate,Email,BounceCode,BounceReason, BounceType<\/span><\/span>\n2010-10-01 17:10:00,test1@yahoo.com,some test bounce code, UserUnknown, Hard<\/span><\/span>\n2010-10-01 17:10:00,test2@yahoo.com,some test bounce code, MailboxFull, Soft<\/span><\/span>\n2010-10-01 17:11:00,test3@yahoo.com,some test bounce code, Blocked, Soft<\/span><\/span>\n2010-10-01 17:12:00,test4@yahoo.com,some test bounce code, Unknown, Soft<\/span><\/span>\n2010-10-01 19:20:00,john.doe@gmail.com,some test bounce code, Other, Hard<\/span><\/span><\/code><\/pre><\/div>\n","protected":false},"author":5,"featured_media":0,"parent":3548,"menu_order":249,"template":"","format":"standard","emp-category":[],"class_list":["post-3695","es","type-es","status-publish","format-standard","hentry"],"acf":[],"_links":{"self":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3695","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es"}],"about":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/types\/es"}],"author":[{"embeddable":true,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/users\/5"}],"version-history":[{"count":3,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3695\/revisions"}],"predecessor-version":[{"id":10846,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3695\/revisions\/10846"}],"up":[{"embeddable":true,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/es\/3548"}],"wp:attachment":[{"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/media?parent=3695"}],"wp:term":[{"taxonomy":"emp-category","embeddable":true,"href":"https:\/\/help.expertsender.com\/pl\/wp-json\/wp\/v2\/emp-category?post=3695"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}