Failover Listing

The Failover API lets you retrieve failover events in JSON or XML format. The list contains events recorded since the last reset.

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

To use the Failover 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. Use one authentication method per request.

Always use HTTPS. Keep your credentials secure and do not include them in URLs, source code or shared examples.

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.

JSON

Retrieve Failovers

Use an authenticated GET request to retrieve the current list of failovers without clearing it:

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

Replace ABC12345 with your account code.

Retrieve and Reset Failovers

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

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

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

Example JSON Response

[
    {
      "epid": "Q9VGGCHHM2Q7D68MJVMR9TDTGPQ4",
      "customer_reference": "20924",
      "dbid": 80712339,
      "failover_reason": "5.1.1: SMTP; 550 Requested action not taken: mailbox unavailable",
      "idx": 1,
      "failover_posix_ts": 1487720980,
      "failover_time": "22/02/2017 10:49:40",
      "transport": [
        "EMAIL",
        "POST"
      ]
    }
  ]

XML

Retrieve Failovers

Use an authenticated GET request to retrieve the current list of failovers without clearing it:

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

Retrieve and Reset Failovers

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

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

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

Example XML Response

<?xml version="1.0" encoding="UTF-8"?>
  <ListFailoversResult>
    <FailoverLetter>
      <CustomerReference>20924</CustomerReference>
      <Reason>5.1.1: SMTP; 550 Requested action not taken: mailbox unavailable</Reason>
      <EPID>X2PPTRGDC7B89W7PXQDQ78DKHXVK</EPID>
      <index>1</index>
      <FailoverTime>24/08/2012 09:36:05</FailoverTime>
      <BingDBID>14376202</BingDBID>
      <FailoverPosixTS>1345764965</FailoverPosixTS>
    </FailoverLetter>
  </ListFailoversResult>

Using cURL

The following examples retrieve the JSON list without resetting it. Replace ABC12345 with your account code. To retrieve XML, replace failovers.json with failovers.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/failovers.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/failovers.json?account=ABC12345" \
    --user "${BING_USERNAME}"

Notes and Limitations

• Contact Bing Customer Service to enable the Failover 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 events your integration has already retrieved.
• Only use a reset request when you intend to clear the current list.

Support

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