Using the SMS Gateway API, Automating Delivery Report Collection
Introduction
If you are using the API / Gateway to send bulk SMS you can collect your delivery reports from the server, which is a good way of removing bad numbers from your data.
Delivery Reports and the API
It is important to understand the difference between getting a “failure” (or success) message at the API/Gateway and a delivery report. The HTTP GET response from the gateway only confirms that the number and message appear to be in the correct format this does not mean that the number exists. Delivery reports confirm to you what has actually happened to the message, the following outcomes are possible: “DELIVERED”,”REJECTED”,”FAILED” and no report at all.
- “REJECTED” means that the message was rejected by the relevant operator and did not attempt to deliver it.
- “FAILED” probably means that the number does exist (or at least not anymore).
- “DELIVERED” message received on the handset.
Occasionally we don’t received a delivery report at all, this can be down to a failure at the operator end due to high load or other problems.
Delivery Reporting
It most cases we receive a delivery report from the operator, this gets appended to a file in your delivery report directory using a standardised filename for each day of the week. The naming format is as follows:
“GatewayAPI_DD-MM-YY.csv” where DD is the day in the month in 2 digit format, MM is the month and YY is the year, so for example:
GatewayAPI_04-01-09.csv is correct
GatewapAPI_12-12-09.csv is correct
GatewayAPI_1-1-9.csv is incorrect
The contents of a typical file
20-05-09 10:50,447777777777,DELIVERED 20-05-09 15:15,447777777776,DELIVERED
The url for collecting the delivery report
http://www.textmarketer.biz/DeliveryReports/[dir]/[filename]
To find your delivery report directory, log into your system click the menu heading “Reports” then select “Delivery Reporting”, you will see a green icon (see below), roll over this and you can find the directory name at the bottom.
So an example url would like like:
http://www.textmarketer.biz/DeliveryReports/jdjd8447fj9fj94kv4/GatewayAPI_05-05-09.csv
Example PHP5 Code for handling delivery reporting
<?php
class ProcessDeliveryReport {
private $dir;
private static $REPORT_URL = "http://www.textmarketer.biz/DeliveryReports/";
private $data;
private $lines;
function __construct($dir) {
// Your delivery report url such as "jfjfij596tghg85" include no / slashes
// You can find the directory in your system under delivery reports and the green ?
$this->dir = self::$REPORT_URL . $dir;
}
public function setReportDate($the_date) {
// Use this function first to set the reporting date you wish to examine
// $the_Date in DD-MM-YY format "07-09-09" or "today"
if ($the_date == "today")
$filename = $this->dir . "/GatewayAPI_" . date ( "d-m-y", time () ) . ".csv";
else {
if (count ( explode ( "-", $the_date ) ) < 3)
return false; // probably wrong fromat
list ( $day, $month, $year ) = explode ( "-", $the_date );
$filename = $this->dir . "/GatewayAPI_$day-$month-$year.csv";
}
if ($this->data = file_get_contents ( $filename )) {
$this->lines = explode ( "\r\n", $this->data );
return true;
} else
return false;
}
public function getWholeReport() {
// returns the whole file
return $this->data;
}
public function findNumber($number, $status = false) {
// $number is mobile number in international format for example 44777777777
// $status (optional) status can be "d","f","r" for delivered, failed or rejected
if ($status) {
switch (strtoupper ( $status )) {
case "D" :
$status = "DELIVERED";
break;
case "F" :
$status = "FAILED";
break;
case "R" :
$status = "REJECTED";
break;
default :
$status = false;
}
}
$found = false;
foreach ( $this->lines as $line ) {
if (! $status) {
if (strstr ( $line, $number ) !== false)
$found [] = $this->lineFormat ( $line );
// dont break as there could be more than one instance of the number during the day
} else if (strstr ( $line, $number ) !== false and strstr ( $line, $status ) !== false)
$found [] = $this->lineFormat ( $line );
}
return $found; // return an array of the number keyed array
}
public function getNextLineArray() // returns a keyed array of each line in the report
{
$current_arr = each ( $this->lines );
return $this->lineFormat ( $current_arr ['value'] );
}
private function lineFormat($line) {
list ( $d, $m, $s ) = explode ( ",", $line );
return array ("delivered" => $d, "mobile number" => $m, "message status" => $s );
}
}
/// example of use
$reports = new ProcessDeliveryReport ( "Kt65CZMtxlIiEU328ilCBgC38" );
if ($reports->setReportDate ( "20-05-09" ))
print_r ( $reports->findNumber ( "44777777777", "r" ) );
?>
Popularity: 9%

Discussion
What do you think? Leave a comment. Alternatively, write a post on your own weblog; this blog accepts trackbacks [trackback url].