JSON Mailing Queries

The letter status API allows customers to query the status of individual letters "get_letter_status" or the most recent letters uploaded "recent_uploads".

Get Letter Status

To use the web service for letter status customers supply a unique reference ID with each individual letter. A query containing the reference ID(s) is made to the web service which will return the letter status values.

URL: https://easymail.com/publicinterface/jsonrpc
HTTP verb: POST

Query:

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

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

Example using "cURL" (http://curl.haxx.se), with the json RPC query.

          stored in a file named "query.json":

curl -d @query.json -H "Content-Type:text/json" "https://easymail.com/publicinterface/jsonrpc"

Interpreting Letter Status

Standard status values are:

• Unknown - Letter not known or internal status not recognised.
• Received - Letter was received successfully and is currently being produced.
• Lodged - Letter was lodged with the carrier.
• Cancelled - Letter was cancelled and has been removed from production.
• Returned - Letter was returned by the carrier.

Notes and Limitations

1. Letter reference ID strings must be unique for every letter sent. Don’t simply use account number or customer reference as this will then most likely appear in more than one letter.
2. Verify that reference ID is correctly extracted from the letter data (as per the “How to use Reference ID” guide).
3. Once a letter status query has returned a terminal state for a letter i.e. Lodged, Cancelled or Returned, then the reference ID should be removed any further queries. 
4. The letter status query will respond with a Status element  “Unknown” for each request where there is an invalid Customer ID, or the mailing has not yet been received.
5. Requests should be batched with up to 5000 references per query.
6. We ask that any given reference not be queried more than once per hour.

Recent Uploads

The "recent_uploads" rpc returns the "limit" most recently uploaded mailings in reverse chronological order.

A query containing the account ID, and optional "limit", is made to the web service which will return the most recent mailings uploaded on the account.

URL: https://easymail.com/publicinterface/jsonrpc
HTTP verb: POST

Query:

{
	"json_rpc": "2.0",
	"id": 1,
	"method": "recent_uploads",
	"params": {
		"account": "ABC01234",
		"limit": 2
	}
}

( "limit" is optional, default 100, maximum 100 )

Response:

{
	"jsonrpc": "2.0",
	"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
		}]
	}]
}