JSON Mailing Queries

The letter status API allows customers to query individual letters using get_letter_status or retrieve their most recent uploads using recent_uploads.

Endpoint and Authentication

Both methods use the same HTTPS endpoint:

URL: https://bingmail.com.au/apiv2/jsonrpc
HTTP verb: POST
Content-Type: application/json

Authentication is required. You can authenticate using either:

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

For authorisation and assistance obtaining credentials, please contact Bing Customer Service. Your credentials must be authorised to access the account you are querying.

API Key Authentication

Include your API key in the Authorization header:

Authorization: Bearer <your-api-key>
  Content-Type: application/json

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.

Use one authentication method per request.

Get Letter Status

Supply a unique reference ID with each letter you upload. Send these reference IDs to get_letter_status to retrieve their current status.

URL: https://bingmail.com.au/apiv2/jsonrpc
HTTP verb: POST

Query:

{
    "jsonrpc": "2.0",
    "method": "get_letter_status",
    "id": 1,
    "params": {
      "account": "ABC12345",
      "refs": [
        "myref1",
        "myref2"
      ]
    }
  }

Replace ABC12345 with your account code and the example references with your letter reference IDs.

Example response:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "letters": [
        {
          "price": 0.20,
          "dbid": 46805050,
          "epid": "2JWM49JYMXWV2PGYX8TRBGJ847JK",
          "ref": "myref1",
          "status": "Lodged",
          "idx": 1,
          "received_ts": 1643676175,
          "transport": "EMAIL"
        },
        {
          "price": 1.93,
          "dbid": 46805051,
          "epid": "2JWM49JYMXWV2PGYX8TRBGJ847JK",
          "ref": "myref2",
          "status": "Lodged",
          "idx": 2,
          "received_ts": 1643676175,
          "failover": true,
          "transport": [
            "SMS",
            "POST"
          ],
          "email_first_opened": 1643677275,
          "email_last_opened": 1643677433,
          "doc_first_opened": 1643677280,
          "doc_last_opened": 1643677280
        }
      ]
    }
  }

Using cURL with an API Key

Save the query in a file named query.json. This shell example reads your API key from the BING_API_KEY environment variable, which must already be set securely:

curl --request POST \
    --url "https://bingmail.com.au/apiv2/jsonrpc" \
    --header "Authorization: Bearer ${BING_API_KEY}" \
    --header "Content-Type: application/json" \
    --data-binary @query.json

Using cURL with a Username and Password

Save the query in query.json. This example reads your username from the BING_USERNAME environment variable and prompts you to enter your password:

curl --request POST \
    --url "https://bingmail.com.au/apiv2/jsonrpc" \
    --user "${BING_USERNAME}" \
    --header "Content-Type: application/json" \
    --data-binary @query.json

Interpreting Letter Status

Standard status values are:

• Unknown — The letter is not known or its internal status is not recognised.
• Received — The letter was received successfully. This does not confirm that it has been lodged with the carrier.
• Lodged — The letter was lodged with the carrier.
• Cancelled — The letter was cancelled and removed from production.
• Returned — The letter was returned by the carrier.

Notes and Limitations

1. Use a unique reference ID for every letter. An account number or customer reference alone may be repeated across multiple letters.
2. Verify that the reference ID is correctly extracted from the letter data, as described in the “How to use Reference ID” guide.
3. Stop querying a reference once its status is Lodged, Cancelled or Returned.
4. A reference that is not known to the service, including a letter that has not yet been received, may return Unknown. This is distinct from an authentication failure.
5. Batch up to 5,000 references per query.
6. Do not query the same reference more than once per hour.

Recent Uploads

The recent_uploads method returns the most recently uploaded mailings for an account, in reverse chronological order.

URL: https://bingmail.com.au/apiv2/jsonrpc
HTTP verb: POST

Include your account code and an optional limit. Authenticate using either an API key or a username and password, as described above.

Query:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "recent_uploads",
    "params": {
      "account": "ABC12345",
      "limit": 2
    }
  }

The limit parameter is optional. It defaults to 100 and has a maximum of 100.

Example response:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
      {
        "epid": "PP7WMYBFMV724XJFXPJV29827BVR",
        "uploaded": 1437691161,
        "uploaded_s": "Fri Jul 24 08:39:21 AEST 2015",
        "letters": [
          {
            "reference": "987654",
            "idx": 1
          },
          {
            "reference": "1234567",
            "idx": 2
          }
        ]
      },
      {
        "epid": "JJDRVVH4G693FMCGXPT9YPYCYCP3",
        "uploaded": 1437690916,
        "uploaded_s": "Fri Jul 24 08:35:16 AEST 2015",
        "letters": [
          {
            "reference": "10718814",
            "idx": 1
          }
        ]
      }
    ]
  }

Support

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