transactional.bouncedList

‹ BACK TO API PAGE


Description

This method returns bounce information for all contacts who received emails sent from eMS Enterprise, regardless of whether they are signed up for email marketing communications, or their subscription status within the system.

Arguments

Field Description Field Type Required Example
email The email address of the contact for which you wish to get bounce information. string Yes, unless template_id used johndoe@bluehornet.com
external_id An identifier defined within an external system used to retrieve bounce data on a single subscriber. If this element is included with the <email> element, then the search for the subscriber record will be based on both the external ID and the email address. string No ABC123DEF456
template_id The template identification number associated with the template for which you wish to receive bounce information. number Yes, unless email used 1055589
start_date The starting date and time of the range to retrieve subscriber bounce data, in YYYY-MM-DD HH24:MI:SS format. date No 2017-01-05 19:23:45
end_date The ending date and time of the range to retrieve subscriber bounce data, in YYYY-MM-DD HH24:MI:SS format. date No 2017-01-25 11:59:00

Response

If only template_id is POSTed:

Field Description Example
email The email address that bounced over the history of the template. jdoe@example.com
external_id An identifier defined within an external system associated with the subscriber's email address that bounced over the history of the template. This element will only be included in the response when the External ID feature is enabled for your account. ABC123DEF456
reason The reason for the bounce 5-Invalid Recipient
flagged_invalid The invalid action taken as a result of the bounce 4
bounced_date The date the message bounced when sent to the subscriber. The date will be in YYYY-MM-DD HH24:MI:SS format in US Pacific Time Zone. 2017-01-05 19:23:45

If email is POSTed either by itself or together with template_id

Field Description Example
template_id The transactional template ID used to create the email that the POSTed email address bounced on 10289702
reason The reason for the bounce 5-Invalid Recipient
flagged_invalid The invalid action taken as a result of the bounce 4

The value for flagged_invalid will have one of the following values:

Value Description
0 The contact record remains valid
1 The contact record is temporarily invalid and will be for {X} days based on the client's account-configured bounce rules
2 The contact record is permanently invalid as a result of 1 hard bounce or multiple soft bounces based on the client's account-configured bounce rules
3 The contact record is on the Global Suppression List
4 The contact record is a "transactional only" record, added as a result of receiving a transactional message, and is not in the client's email subscriber database

Response Codes

Response Code Response Text Description
205 Successfully returned bounced data A successful request.
429 Invalid Template ID The value for the <template_id> element does not exist in your account.

Example Post

Example One:

<methodCall>

<methodName>transactional.bouncedlist</methodName>

<template_id>1055589</template_id>

</methodCall>


Example Two:

<methodCall>

<methodName>transactional.bouncedlist</methodName>

<email>jdoe@example.com</email>

</methodCall>

Example Response

Example One:

<methodResponse>

<item>

<methodName>transactional.bouncedlist</methodName>

<template_id>

<value>1055589</value>

<item>

<email>jdoe@example.com</email>

<reason>5-Invalid Recipient</reason>

<flagged_invalid>4</flagged_invalid>

</item>

<item>

<email>1@2.com</email>

<reason>5-DNS Failure</reason>

<flagged_invalid>4</flagged_invalid>

</item>

<item>

<email>ksmith@example.com</email>

<reason>5-DNS Failure</reason>

<flagged_invalid>4</flagged_invalid>

</item>

</template_id>

<responseNum>1</responseNum>

</item>

</methodResponse>


Example Two:

<methodResponse>

<item>

<methodName>transactional.bouncedlist</methodName>

<email>

<value>jdoe@example.com</value>

<item>

<template_id>1055589</template_id>

<reason>5-DNS Failure</reason>

<flagged_invalid>4</flagged_invalid>

</item>

</email>

<responseNum>1</responseNum>

</item>

</methodResponse>


Back to API Reference Guide