Returned Mail Listing

The Returned Mail API lets you retrieve letters returned by the postal carrier in JSON or XML format. Returned mail is processed by Bing Technologies as soon as it arrives, typically daily.

Bing recommends querying this API no more than once or twice per day.

To use the Return Mail API, contact Bing Customer Service to have it enabled for your account and to obtain the necessary authorisation and credentials.

Authentication

Authenticate using either:

  • An API key using Bearer authentication.
  • A username and password using HTTP Basic authentication.

Your credentials must be authorised to access the account you are querying. Include your account code in every request and use one authentication method per request.

API Key Authentication

Include your API key in the Authorization header:

Authorization: Bearer <your-api-key>

Username and Password Authentication

Use HTTP Basic authentication with your username and password. Most HTTP clients, including cURL, can generate the required Authorization header automatically.

Retrieving and Resetting Returned Mail

The list contains returned-mail records accumulated since the last reset. Include address=true to request full address details.

The list continues to accumulate until you reset it. Clear it regularly, at least daily, as part of your retrieval process. A reset request retrieves the current list and clears it, so save the returned response to retain those records in your integration.

JSON

Retrieve Returned Mail Without Addresses

Use an authenticated GET request to retrieve the current list without full address details:

https://bingmail.com.au/apiv2/returnedmail.json?account=ABC12345

Replace ABC12345 with your account code.

Retrieve Returned Mail With Addresses

Include address=true to request full address details:

https://bingmail.com.au/apiv2/returnedmail.json?account=ABC12345&address=true

Retrieve and Reset Returned Mail

The following request retrieves the current list and clears it using the _method=PUT override and reset=true parameter:

https://bingmail.com.au/apiv2/returnedmail.json?_method=PUT&account=ABC12345&reset=true

This request changes the list. Save the returned response so your integration retains the retrieved records.

XML

Retrieve Returned Mail Without Addresses

Use an authenticated GET request to retrieve the current list without full address details:

https://bingmail.com.au/apiv2/returnedmail.xml?account=ABC12345

Retrieve Returned Mail With Addresses

Include address=true to request full address details:

https://bingmail.com.au/apiv2/returnedmail.xml?account=ABC12345&address=true

Retrieve and Reset Returned Mail

The following request retrieves the current list and clears it using the _method=PUT override and reset=true parameter:

https://bingmail.com.au/apiv2/returnedmail.xml?_method=PUT&account=ABC12345&reset=true

This request changes the list. Save the returned response so your integration retains the retrieved records.

Sample Responses

The following examples show responses without full address details.

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>

Using cURL

The following examples retrieve the JSON list without full address details and without resetting it. Replace ABC12345 with your account code. To retrieve XML, replace returnedmail.json with returnedmail.xml.

API Key Authentication

This shell example reads your API key from the BING_API_KEY environment variable, which must already be set securely:

curl --request GET \
    --url "https://bingmail.com.au/apiv2/returnedmail.json?account=ABC12345" \
    --header "Authorization: Bearer ${BING_API_KEY}"

Username and Password Authentication

This example reads your username from the BING_USERNAME environment variable and prompts you to enter your password:

curl --request GET \
    --url "https://bingmail.com.au/apiv2/returnedmail.json?account=ABC12345" \
    --user "${BING_USERNAME}"

Notes and Limitations

  • Contact Bing Customer Service to enable the Returned Mail API and arrange authorisation.
  • Include your account code in every request.
  • Limit queries to no more than once or twice per day.
  • Retrieving the list without a reset may return records your integration has already retrieved.
  • Clear the list regularly, at least daily, using a retrieval request that includes both _method=PUT and reset=true.
  • Save the response from a reset request, as the retrieved records are cleared from the list.

Support

For authorisation, credentials or assistance using this API, please contact Bing Customer Service.