The letter status API allows customers to query the status of individual letters.
Although the SOAP/XML service will continue to be provided indefinitely, further development of existing and new APIs will use JSON only. We recommend using the JSON-RPC interface if possible.
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.
SOAP – Letter Status
Soap service detail is currently published at https://easymail.com/publicinterface/clientservice.asmx?wsdl
This site contains details about the web service – WSDL
Developers can create an application to use the web service to query mailing status. This way, all low level SOAP messages are hidden from the user, and the application interacts with the web service via objects.
How do I test it?
A SOAP query test is available via 3rd party websites, such as http://www.soapclient.com/soapmsg.html which will return the specific SOAP response in a web browser. The example below uses the EasyPost test account “ABC12345” and an example reference ID “myref1”.
Server Address: https://easymail.com/publicinterface/clientservice.asmx
SOAP Action: https://easymail.com/RequestLetterStatus
SOAP Message:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<RequestLetterStatus xmlns="http://easymail.com/">
<Account>ABC12345</Account>
<LetterReferences>
<string>myref1</string>
</LetterReferences>
</RequestLetterStatus>
</soap:Body>
</soap:Envelope>
Once the Execute button is clicked, the following is returned in the web browser:
<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<RequestLetterStatusResponse xmlns="http://easymail.com/">
<RequestLetterStatusResult>
<LetterStatus>
<Reference>myref1</Reference>
<ServiceNumber>PQXVKT8T7FXDCPBD4BH9KPBCW3PF</ServiceNumber>
<LetterIndex>1</LetterIndex>
<LetterId>5749643</LetterId>
<WhenCreated>2007-06-22T04:56:07Z</WhenCreated>
<WhenLodged />
<Status>Received</Status>
</LetterStatus>
</RequestLetterStatusResult>
</RequestLetterStatusResponse>
</soap:Body>
</soap:Envelope>
Status successfully returned is “Received”.
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.
If failover is enabled status are:
Lodged + POST - Letter was lodged with the postal carrier.
Lodged + EMAIL - Letter was lodged via email.
Lodged + EMAIL + Failover - Letter was attempted via email, email has failed and letter has now been lodged with the postal carrier.
Received + POST - Letter was received successfully and is currently being produced for lodgement with the postal carrier.
Received + EMAIL - Letter was received successfully and is currently being routed for email.
Received + EMAIL + Failover - Letter was received successfully and has been attempted via email, the email has failed and the letter is now being produced for lodgement with the postal carrier.
Cancelled + POST - Letter was cancelled and has been removed from production.
Cancelled + EMAIL - Letter was cancelled and has been removed from production.
Returned + POST - Letter was lodged with the postal and has subsequently been returned.
Returned + EMAIL - Letter was lodged via email but has been rejected after the 24 hour failover period.
Returned + EMAIL + Failover - Letter was attempted via email, email has failed and letter was lodged with the postal carrier and has subsequently been returned.
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 with status “Unknown” for each request where there is an invalid Customer ID, or the mailing is not yet known by the server.
5. We recommend a maximum of 1000 references per query.
6. We suggest that any given reference not be queried more than once per hour.