In our REST API specification document we saw, in general terms, how to make a request to our REST SMS API and how to deal with the response. Here we provide you with some more concrete examples that you can copy & paste!

NOTE: You will want to add additional error checking to the examples below.

In each of the languages used here we create a request, send it, receive the response, and parse its contents.

PHP

Example for getting the number of credits:

$url = 'http://www.textmarketer.biz/services/rest/credits';
$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);
	$credits = (int) $xml_obj->credits;
	// do something with the result
	echo $credits;

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

Example for getting the list of delivery reports:

$url = 'http://www.textmarketer.biz/services/rest/deliveryReports';
$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);
	$atts = $xml_obj->reports->attributes();
	$num_reports = (int) $atts->quantity;

	if ($num_reports > 0)
	{
		echo "$num_reports reports\n";
		$reports = array();
		foreach ($xml_obj->reports->report as $xml_report)
		{
			$atts = $xml_report->attributes();
			$name = (string) $atts->name;
			$updated = (string) $atts->last_updated;
			$reports[] = array('name'=>$name, 'modified'=>$updated);
		}
		// do something with the report details
		var_dump($reports);
	} else {
		echo 'No reports available';
	}
} else {
	// handle the error
	var_dump($responseBody);
}

Example for getting the details of a particular delivery report:

// TODO the URL will change according to the delivery report to retrieve...
$url = 'http://www.textmarketer.biz/services/rest/deliveryReport/GatewayAPI_09-02-10';
$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);
}

Example for sending an SMS:

$url = 'http://www.textmarketer.biz/services/rest/sms';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!

$data = array('message'=>'hello','mobile_number'=>'447777777777', 'originator'=>'me',
	'username'=>$username, 'password'=>$password);
$data = http_build_query($data, '', '&');
// 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);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_POST, 1);
$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);
	// do something with the result
	echo "Message ID: $xml_obj->message_id\n";
	echo "Credits used: $xml_obj->credits_used\n";

	var_dump($responseBody);

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

Example for transferring credits:

<?php
/**
 * POST request on the 'credits' resource (credit transfer)
 */
$url = 'http://www.textmarketer.biz/services/rest/credits';
// for testing:
//$url = 'http://sandbox.textmarketer.biz/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!! - the username of the account you're transferring FROM
$password = 'myAPIpassword'; // CHANGE THIS!!!
$targetAccountNumber = 0; // CHANGE THIS!!

$data = array('quantity'=>'1','target'=>$targetAccountNumber,
	'username'=>$username, 'password'=>$password);
$data = http_build_query($data, '', '&');
// 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);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_POST, 1);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);

// deal with the response
if ($responseInfo['http_code']==200)
{
 // success - you may want to read in the return data here to see how many credits were  left on each account

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

?>

For more details on creating REST requests in PHP, see here.

This class enables you to access your delivery reports in a nice simplified way. You can search for the outcome of a message for a given number, specify the outcome and the number, download all the data for the given date or parse the reports line by line.

The constructor requires the delivery report directory that is shown in your account. 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, roll over this and you can find the directory name at the bottom.

If you have sent a message greater than 160 characters you will find multiple entries for that particular number . For instance if your message was 200 characters you will find 2 reports for that number. A message is built from 160 chunks

Download the PHP 5 Delivery Report Class

Example of use

<?

$reports = new ProcessDeliveryReport ( "Kt65CZMtxlIiEU328ilCBgC38" ); // your delivery report directory
if ($reports->setReportDate ( "20-05-09" )) print_r ( $reports->findNumber ( "44777777777", "r" ) ); // print the array of results
else echo "Not found";

?>

This class is designed around the FREE Text Marketer SMS API, you need to sign up here to use it.

SendSMSNotifier is a singleton class design, incorporating listeners. Your class must include the following public functions: creditAlert($credits_remaining) and failureAlert($error,$number,$message,$error).

Download the class from here

Example of use

class MyTestClass
{

        /// simple array of data in: number, message, sender Id (aka originator) format, ideally the data will come from a database
	private $mySMSdata = array(array("44777777777","Hello World!","Me"),
			                             array("text","This will throw an error, mobile number is text","Me"));

	function __construct()
	{
		$sms = SendSMSNotifier::getInstance("myUsername","myPassword"); // your account login details
		$sms->addListener($this); // Your class gets added to the listeners that will get notified on an event
		$sms->setCreditThreshold(5); // You want o be notified when you have 5 credits left

		foreach($this->mySMSdata as $record) // send some data
		{
			list($number,$message,$sender) = $record;
			$sms->send($number,$message,$sender); // send to the api
		}
		echo $sms->getCredits();
		print_r($this->errors);
	}

	public function failureAlert($error,$number,$message,$originator)
	{
		/// Required function for failure messages, you could stop the sending here or log the results
		$this->errors[] = array($error,$number,$message,$originator);
	}

	public function creditAlert($credits)
	{
		/// Required function for credit alerts, this basic implementation stops sending anymore SMS's
		die("I have nearly run out of credits($credits left), abandon sending!");
	}
}

So here’s what happens. You send a bunch of text messages to the gateway using your class (in this example MyTestClass), if you get a failure such as a badly formatted number your function failureAlert gets called with the parameters of the failure and data, you can then decide on the implmentation. In the above example it just stores them in an array, once you have sent all the data you could then use the data to clean your database etc.

If the credit limit (in the above case this is 5 $sms->setCreditThreshold(5) ) your function creditAlert will get called, in this case we think this is bad so we use the hammer of the die() function to stop the sending, obviously you would handle this much more elegantly :-)