To get delivery reports, you have two options: The much more efficient and faster method is a callback directly to your server. As soon as a new status is available, your desired URL is automatically called up. The alternative method is to directly query the status of an SMS via a request to the API. If there is no status yet, you might have to query again later. We recommend to use the callback variant. Both variants can also be combined, e.g. if the callback failed.
Status reports via callback
As an alternative to a manual query, you can set a URL in your login under Account > Developer > Webhooks, to which our server automatically sends an HTTP request as soon as a new status is available. In order to conserve resources and to get the current status as fast as possible, this method is preferable to the manual query.
To your URL, which can also be called via SSL, then the Get parameters msg_id
, status
and timestamp
for the message ID, the current delivery report and its timestamp are appended.
If we could not reach your Callback URL (caused by request timeout or HTTP Code 500), we will try again up to 6 times every hour. If you have large amounts of delivery reports, a cumulated minute-by-minute transmission of delivery reports is possible. For this please send us a message.
Example
Let’s say you have the following URL specified as status URL:
https://www.yourserver.com/status.php
We send a request to your server:
https://www.yourserver.com/status.php?msg_id=1234567&status=DELIVERED×tamp=2020-01-09+15%3A41%3A30.656
Query delivery reports
You can use the following endpoint to manually query the delivery report of an SMS:
https://gateway.sms77.io/api/status
Parameter | Description |
---|---|
msg_id | The message ID of the SMS. You can obtain it automatically when sending SMS via the API. You can query for multiple IDs by separating them by comma. In this case the API returns a JSON response. |
If no errors occurs you will get the delivery report followed by a line break and the date in format YYYY-MM-DD and the timestamp with milliseconds as response in mime type text/plain.
Possible delivery reports
- DELIVERED
- The SMS was successfully delivered.
- NOTDELIVERED
- SMS could not be delivered. Please check the recipient number if necessary.
- BUFFERED
- SMS was sent successfully, but was cached by the SMS carrier because the recipient isn’t reachable.
- TRANSMITTED
- SMS was sent by the SMS carrier and should arrive soon.
- ACCEPTED
- SMS was accepted by the SMS carrier.
- EXPIRED
- SMS was not received before the end of validity.
- REJECTED
- SMS was rejected by the carrier.
- FAILED
- Error while sending SMS.
- UNKNOWN
- Unknown status report.
Notice:
If you supply a wrong message ID, the API code 600 gets returned as the response body.
Examples
We have made a few examples for you to see this API in action.
Request status for a single SMS
Request:
https://gateway.sms77.io/api/status?p=api-key&msg_id=12345678900
Response:
DELIVERED 2020-01-09 15:41:30.656
Request status for multiple SMS
Request:
https://gateway.sms77.io/api/status?p=api-key&msg_id=12345678900,12345678901
Response:
[
{
"id": "12345678900",
"status": "DELIVERED",
"status_time": "2021-12-16 11:06:35.000"
},
{
"id": "12345678901",
"status": "TRANSMITTED",
"status_time": "2021-12-16 11:57:49.000"
}
]