» REST SMS Gateway API – deliveryReport resource

This blog post has been superseded with our website documentation

deliveryReport

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

Resource URI:

http://www.textmarketer.biz/services/rest/deliveryReport

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

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

http://www.textmarketer.biz/services/rest/deliveryReport/test-190310

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"
 status="DELIVERED"/>
		<reportrow modified_date="2010-03-19T09:45:00+00:00" mobile_number="447123123456" message_id="12345679"
 status="DELIVERED"/>
	</report>
</response>

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

N/A

Note

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:

http://www.textmarketer.biz/services/rest/deliveryReport/GatewayAPI_12-01-10

Example PHP

<?php
/**
 * GET request on the deliveryReport resource
 */
// TODO the URL will change according to the delivery report to retrieve...
$url = 'http://www.textmarketer.biz/services/rest/deliveryReport/myreportname'; // 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);
curl_close($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
	var_dump($reports);

} else {
	// handle the error
	var_dump($responseBody);
}

?>

Popularity: 8%

Related posts:

1. REST SMS Gateway API – deliveryReports resource
   This blog post has been superseded with our website documentation deliveryReports This document is referred to by the REST SMS Gateway API – Specification...
2. REST SMS API Code Examples
   This blog post has been superseded with our website documentation In our REST API specification document we saw, in general terms, how to...
3. REST SMS Gateway API – credits resource
   This blog post has been superseded with our website documentation credits This document is referred to by the REST SMS Gateway API –...
4. REST SMS Gateway API – Specification Document
   This blog post has been superseded with our website documentation For an overview of what REST and our RESTful SMS API is all...
5. RESTful Web Services SMS Gateway API Overview
   This blog post has been superseded with our website documentation In addition to our simple HTTP SMS Gateway API, explained here, we also...
6. Using the SMS Gateway API, Automating Delivery Report Collection
   This blog post has been superseded with our website documentation Introduction If you are using the API / Gateway to send bulk SMS...
7. SMS Gateway API – Specification
   This blog post has been superseded with our website documentation It is recommended that you use the  RESTful version of the API which has largely superseded this document...
8. PHP 5 Delivery Report Helper Class for our SMS Gateway
   Class Name: ProcessDeliveryReport This class enables you to access your delivery reports in a nice simplified way. You can search for...
9. Changes to Delivery Reporting
   Message id’s are now also included in your delivery report file, this change is only really relevant for API users,...
10. Concatenated “Long Message” SMS feature now Live for the Bulk SMS system and the SMS Gateway
    You can now send text messages longer than 160 characters, in fact up to 612 characters which arrive as 1...