Returned Mail Listing

The Returned Mail API can be queried using either JSON or XML. Bing processes returned postal mail as it is received from the postal carrier, typically daily.  The Returned Mail API  should only be queried once or twice per day.

The list must be cleared on a regular basis. If it isn’t, the API will return an ever-increasing list of returned letters.

To use the Returned Mail API, contact Bing Customer Service. They can enable the API for your account and provide further guidance on its usage.

Below are some examples of how to use the Returned Mail API with JSON and XML:

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

JSON Response

[{
	"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

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

XML Response

<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>