Returned Mail Listing

Returned Mail API

The Returned Mail API lets you retrieve letters returned by the postal carrier. You may request data in JSON or XML format. Returned mail is processed by Bing Technologies as soon as it arrives, typically daily. We recommend polling the API no more than once or twice daily to avoid unnecessary load.

All requests must include your account code. If you include the parameter address=true to obtain full address details, HTTP Basic Authentication is mandatory. Contact Bing Customer Service to:

  • Enable the Returned Mail API on your account
  • Obtain your API username and password

The list of returned mail accumulates until you explicitly reset it. You must clear the list regularly, at least daily, by including reset=true. Failing to do so will result in an ever‑increasing dataset.

JSON

Query current list of returned mail since last reset and without address:

http://easymail.com/publicinterface/returnedmail.json?account=ABC12345

Query current list of returned mail since last reset including address:

http://easymail.com/publicinterface/returnedmail.json?account=ABC12345&address=true

Query current list of returned mail (since last reset) and reset(clear) list:

http://easymail.com/publicinterface/returnedmail.json?_method=PUT&account=ABC12345&reset=true

XML

Query current list of returned mail since last reset and without address:

http://easymail.com/publicinterface/returnedmail.xml?account=ABC12345

Query current list of returned mail since last reset including address:

http://easymail.com/publicinterface/returnedmail.xml?account=ABC12345&address=true

Query current list of returned mail (since last reset) and reset(clear) list:

http://easymail.com/publicinterface/returnedmail.xml?_method=PUT&account=ABC12345&reset=true

Sample Responses

JSON

[{
    "customer_reference": "123456789",
    "epid":               "ZZ4RBR76CMF24YPK464CCW4XR6ZZ",
    "idx":                40,
    "dbid":               99999999,
    "reason":             "Not Advised By Mail Carrier",
    "returned_posix":     1499832000,
    "returned":           "12/07/2017",
    "received":           "25/05/2017"
},
{
    "customer_reference": "012345678",
    "epid":               "ZZGYFB639R3RMX6T46MQY2FRYYZZ",
    "idx":                63,
    "dbid":               99999999,
    "reason":             "Left Address / Unknown",
    "returned_posix":     1499832000,
    "returned":           "12/07/2017",
    "received":           "15/06/2017"
}]

XML

<ListReturnsResult>
  <ReturnedLetter>
    <CustomerReference>123456789</CustomerReference>
    <Reason>Not Advised By Mail Carrier</Reason>
    <EPID>ZZ4RBR76CMF24YPK464CCW4XR6ZZ</EPID>
    <index>40</index>
    <ReturnedDate>12/07/2017</ReturnedDate>
    <BingDBID>99999999</BingDBID>
    <ReturnedPosix>1499832000</ReturnedPosix>
  </ReturnedLetter>
  <ReturnedLetter>
    <CustomerReference>012345678</CustomerReference>
    <Reason>Left Address / Unknown</Reason>
    <EPID>ZZGYFB639R3RMX6T46MQY2FRYYZZ</EPID>
    <index>63</index>
    <ReturnedDate>12/07/2017</ReturnedDate>
    <BingDBID>99999999</BingDBID>
    <ReturnedPosix>1499832000</ReturnedPosix>
  </ReturnedLetter>
</ListReturnsResult>

Notes

  • To keep responses manageable and reduce latency, limit API calls to once or twice per day.
  • Always clear the list after retrieval by using reset=true or a PUT request (via _method=PUT)—otherwise, returned items will continue to accumulate.
  • For any issues or further assistance, contact Bing Customer Service.