status_reports/get_report

Note: Status reports can be routed back to you via HTTP, which is the preferred way for you to receive status reports. Using get_report to poll for reports is not recommended.
Please read this section to see why we do not recommend its use.

This API call may be useful to you, however, if you are not permanently connected to the Internet, but still need to be able to query for status reports.

URL

«EAPI URL»/status_reports/get_report/2/2.0

Example

«EAPI URL»/status_reports/get_report/2/2.0?username=john&password=abcd1234&batch_id=123456

Request parameters

parameter required description
username  
password  
batch_id the id returned by a successful submission to send_sms(>= ver 2.0)
msisdn   supply if querying the status of a single recipient.
optional_fields   a comma-separated list of optional fields to return in the output, chosen from this list:
    * body
    * completed_time (the time that message delivery was completed - only available for some networks)
    * created_time
    * credits
    * origin_address
    * source_id

Response on failure

request_status_code|request_status_description

Possible values for status_code are:

status_code description
22 Internal error
23 Authentication failure
24 Data validation failed

Response on success

0|Returns to follow

Followed by one or more newline-separated items in the format:

msisdn|status_code[|optional_field_1][|optional_field_2]...*

Optional fields will be returned in the order that you specified them.

values for status_code are:

status_code description
0 In progress (a normal message submission, with no error encountered so far).
10 Delivered upstream
11 Delivered to mobile
12 Delivered upstream unacknowledged (assume message is in progress)
22 Internal fatal error
23 Authentication failure
24 Data validation failed
25 You do not have sufficient credits
26 Upstream credits not available
27 You have exceeded your daily quota
28 Upstream quota exceeded
29 Message sending cancelled
31 Unroutable
32 Blocked (probably because of a recipient’s complaint against you)
33 Failed: censored
40 Temporarily unavailable
50 Delivery failed - generic failure
51 Delivery to phone failed
52 Delivery to network failed
53 Message expired
54 Failed on remote network
55 Failed: remotely blocked (variety of reasons)
56 Failed: remotely censored (typically due to content of message)
57 Failed due to fault on handset (e.g. SIM full)
60 Transient upstream failure (transient)
61 Upstream status update (transient)
62 Upstream cancel failed (transient)
63 Queued for retry after temporary failure delivering (transient)
64 Queued for retry after temporary failure delivering, due to fault on handset (transient)
70 Unknown upstream status

It is strongly recommended that you have reports pushed to you instead of using get_report. Other than push being faster and more efficient than pull, consider that it is normal for status reports to be delayed for a period of days. It is also normal to not receive status reports for 100% of messages sent. Therefore, using get_report, you will need to keep polling, continuously, for a period of many days, until you can be fairly sure that a status report is not available for a given message.

Polling too frequently for every message you’ve sent, over many days, will place massive, unnecessary load on our servers. Therefore we require you to apply some sensible algorithm to determine how frequently you should be polling. This would typically be an incremental backoff strategy, whereby you delay polling for a given message, for an increasing greater period of time, every time you fail to retrieve a report. For instance, your polling pattern might be, for any one message or batch, to poll 5 minutes after sending, and then after 30 minutes, 2 hours, 5 hours, 1 day, 2 days and 5 days. It is possible for reports to come in after even 5 days, although this is not common, and typically relates to an error on a mobile network operator.

All this complexity and inefficiency is avoidable by simply using HTTP Push for reports instead: reports are immediately pushed to you, and all you need is to set up a simple script listening at a URL on your Web server.