Winter Sale

15% Free SMS - find out more here

REST SMS Gateway API – deliveryReport resource

  • Why not share:
  • Social sharing button for Facebook
  • Social sharing button for Linkedin
  • Social sharing button for Twitter
  • Social sharing button for Googleplus
  • Social sharing button for Pinterest

This blog post has been superseded with our website documentation


This document is referred to by the REST SMS Gateway API – Specification Document.

Resource URI:

Actions on a specific delivery report.

  • GET method - Gets the contents of a delivery report

An individual delivery report shows the current known status of all messages sent on a given day, or for a particular campaign. Whereas the REST API resource deliveryReports (note the trailing ’s’) gets a list of available delivery report names, including delivery reports for campaigns (see here).


GET method

Gets the contents of a delivery report – the status of delivery of sent messages on a given day or for a given campaign.

It is important to understand the difference between the status of a message in a delivery report, and getting a success or failure when using the API to send a message.

A ‘success’ response from the SMS send only confirms that the number and message appear to be in the correct format – this does not mean that the number actually exists, or that the message was received by the recipient.

Whereas a delivery report – which you retrieve through this ‘deliveryReport’ resource – confirms to you what has actually happened to the sent message. This may change over time, i.e. a delivery report may not show a status for a given message 10 minutes after the message was sent, but may show a status after an hour. The status of messages can change up to 24 hours after the message was sent. Therefore you may prefer to wait for 24 hours after sending an SMS before trying to retrieve its delivery report.

The possible outcomes for a sent message in a delivery report are: “DELIVERED”,”REJECTED”,”FAILED”, “NON-UK”  or no report at all.

  • “REJECTED” means that the relevant operator rejected the message and did not attempt to deliver it.
  • “FAILED” probably means that the number does exist (or at least not anymore).
  • “DELIVERED” means the message was received on the handset.
  • “NON-UK” you are on a UK only route and have tried to send a non UK number.

Occasionally there is no delivery report status for a given message at all. This can be due to a failure at the operator end because of exceptionally high load or other problems.

Example usage

will get the contents of the delivery report named ‘test-190310′. This is the delivery report for the campaign you would have sent named ‘test’.

RESOURCE_ID: the name of the delivery report to retrieve

Example GET response

<response processed_date="2010-03-19T15:24:30+00:00">
	<report name="test-190310" last_updated="2010-03-19T09:45:04+00:00" extension="csv">
		<reportrow modified_date="2010-03-19T09:45:00+00:00" mobile_number="447123123456" message_id="12345678"
		<reportrow modified_date="2010-03-19T09:45:00+00:00" mobile_number="447123123456" message_id="12345679"

The XML response contains individual reportrow’s that give the delivery status of an individual message.

  • ‘message_id’ is a unique ID for the message that was sent
  • ‘modified_date’ is the last date the delivery status for that message ID was updated
  • ‘mobile_number’ is the number the SMS was sent to

Read the advanced specification of this response.

Specific error codes



When we receive a status report from the operator this gets added to a delivery report with a standardised name. The naming format is as follows:

“GatewayAPI_DD-MM-YY” where DD is the day in the month, MM is the month and YY is the year, each being in a 2-digit format.

So for example:

GatewayAPI_04-01-09     is valid
GatewapAPI_12-12-09     is valid
GatewayAPI_1-1-9        is invalid

Thus to get the delivery report for messages sent on 12th January 2010, you would use the URI:

Example PHP

 * GET request on the deliveryReport resource
// TODO the URL will change according to the delivery report to retrieve...
$url = ''; // CHANGE THIS!!!
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";

// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
	$xml_obj = simplexml_load_string($responseBody);

	$reportRows = array();
	foreach ($xml_obj->report->reportrow as $xml_reportRow)
		$atts = $xml_reportRow->attributes();
		$mobile = (string) $atts->mobile_number;
		$updated = (string) $atts->last_updated;
		$msgID = (int) $atts->message_id;
		$status = (string) $atts->status;
		$reports[] = array('mobile'=>$mobile, 'modified'=>$updated, 'messageID'=>$msgID, 'status'=>$status);
	// do something with the report details

} else {
	// handle the error


No related posts.