Delivery reports HTTP Api documentation

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&timestamp=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

Request Parameters
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"
	}
]

Gateway

Delivery reports