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
| 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 |
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 |
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.