SMS API Integration Support. Do you need the level of support Andy Murray receives?

At Text Marketer we speak to a good number of software development companies. Usually they are adding an SMS sending facility to an existing piece of software. So this might be used for sending appointment reminders, order confirmations or a huge range of other SMS notifications.

Integrating a system with Text Marketer’s SMS API so that the system can generate simple outbound texts is very straightforward. Things can become slightly more complicated if a system needs to receive texts, process delivery reports or automatically respond to the incoming text. With SMS API integration, the devil, (as so often is the case), is in the detail. Different levels of SMS API complexity needs different levels of support.

Text Marketer SMS API customers can choose the level of support that they need. Every customer has a dedicated SMS API integration technician whose job it is to be on hand to assist whenever they are needed. So if you need the fanatic support of the kind that Andy Murray’s mother provides, we will do our best. We don’t operate a ticketing system where you would have to to raise a support request and then await a response. Customers have the direct telephone number of the integration technician, which they can call at any time.

As well as the human support, we have developed a comprehensive range of SMS API integration documents. The documentation, along with code examples are designed and set out in a straightforward and logical way. We often find that with our support, successfully completing SMS API integration is far less of a hassle than originally anticipated.

We always provide a free testing account for software developers and you will also receive as many free test credits as you need, whether that’s just a few or a few thousand. if you would like to explore our SMS API, please feel free to set up a free account. You will automatically receive 10 free to credits but just drop us a quick line if you need more.

This example code snip it uses the sandbox so your sms wont actually get sent. To make it live change the site parameter, also dont forget to update your username and password parameters.

Send SMS example

Get the number of credits remaining

group

This resource allows you to view and modify a send group.
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:

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

Actions relating to send groups.

• POST method - Used to add number(s) to a group.

POST method

Attempts to add a number or numbers to a group.

Example usage:

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

Post arguments:

NOTE: If you specify a group by it’s name, and the name is not unique, the first matched group will be used.

Example POST response:

<response processed_date="2011-04-07T14:57:00+01:00">
<added quantity="1">
<number>447777000001</number>
</added>
<stopped quantity="0"></stopped>
<duplicates quantity="1">
<number>447777000002</number>
</duplicates>
</response>

• quantity – the number of added/stopped/duplicate numbers
• added – a list of numbers successfully added to the group
• stopped – a list of numbers that were not added to the group since they are members of a STOP group
• duplicates – a list of numbers that were not added to the group since they are already members of the group

Read the advanced specification of this response.

Specific error codes:

Example XML error response:

<response processed_date="2011-04-07T15:04:19+01:00">
<errors>
	<error code="1">Group not found</error>
</errors>
</response>

Example PHP code:

<?php
/**
* POST request on the 'group' resource (add numbers to group)
*/
$url = 'http://www.textmarketer.biz/services/rest/group';
// for testing:
$url = 'http://sandbox.textmarketer.biz/services/rest/group';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$groupName = 'MyGroupName'; // CHANGE THIS!!
$numbersToAdd = '447777000001,447777000002'; // CHANGE THIS!!
$data = array('name'=>$groupName, 'numbers'=>'$numbersToAdd',
'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
$xml_added = $xml_obj->added;
$atts = $xml_added->attributes();
$added = (integer) $atts->quantity;
echo "$added added";
} else {
// handle the error here
var_dump($responseInfo);
var_dump($responseBody);
}
?>

Java SMS code example, click to download

The full API spec can be found here

The API spec can be found here

Sending SMS using C#, example code

PHP it’s self doesn’t have any native ability to multithread, which I remember as being a bit of an irritant when I started using the language, but you can use a couple of tricks to achieve a similar result.

Consider this scenario

Our SMS Gateway interface (or API) is accessed via an RESTful web service (HTTP POST) or our simple HTTP GET api, these services offer a simple way to integrate with us, however there are draw backs the main one being the speed at which you can send data to the interface in a serial fashion.

Imagine the following: Lets assume you want to send 10,000 text messages as fast as possible to the api, your method would do something like the following:

• construct data (your fully formed HTTP request)
• open port
• write data
• read response
• close port
• repeat 10,000 times

With PHP this process is carried out in a linear fashion in the context of a loop, now let’s look at the numbers:

Internet latency to the api is an assumed 10ms, which would put you somewhere in the UK

The ‘system’ that is the speed at which we can read and write back to your script is .5 ms

Total process time is 105000 ms or 105 seconds .. but wouldn’t it be nice to go quicker??

Now this is where in parallel or multi threading would come in handy, if we could kick say 5 of these processes off at once then we could send the same amount of texts in 105 / 5 which is 21 seconds and a vast improvement.

So how can this be done?

Say hello to the Curl Extension http://uk3.php.net/curl this isn’t necessarily included with your vanilla build of PHP so you’ll need to compile it in. The Curl extension offers many extras for the PHP developer one of which will will use to do our multithreading.

It is usually best to explain the idea by example, here ‘s a class called DoMultiThread that shows the basic idea

<?php

class DoMultiThread {

//// i’m not going to simulate a 10,000 volume send but you can get the idea!

// some dummy data an array of 5 names and numbers for constructing unique messages

private $names = array (array (“name” => “peter”, “number” => “077122345566″ ),

array (“name” => “fred”, “number” => “077122345567″ ),

array (“name” => “susan”, “number” => “077122345568″ ),

array (“name” => “jim”, “number” => “077122345569″ ),

array (“name” => “katie”, “number” => “077122345510″ ) );

function __contruct() {

/// function sets up and sends 5 simultaneous threads

/// returns an array of the 5 outputs

$output = $this->execute ();

}

protected function execute() {

$mh = curl_multi_init ();

$handles = array (); /// will hold all our handle instances

/// create our 5 threads, i wouldn’t advise trying many more

foreach ( $names as $item ) {

// create a new single curl handle

$curl_handle = curl_init ();

// our unique transaction / message

$url = “http://www.textmarketer.biz/gateway/?username=user&password=pass&message=Hi ” . $item ['name'] . “&orig=test&number=” . $item ['number'];

// setting several options like url, timeout, returntransfer

curl_setopt ( $curl_handle, CURLOPT_URL, $url );

curl_setopt ( $curl_handle, CURLOPT_HEADER, 0 );

curl_setopt ( $curl_handle, CURLOPT_RETURNTRANSFER, true );

curl_setopt ( $curl_handle, CURLOPT_TIMEOUT, 30 );

// add to the curl multi handle, this allows us to do the multi threading

curl_multi_add_handle ( $mh, $curl_handle );

// we will need to access the indvidual handles later

$handles [] = $curl_handle;

}

// execute the multi handle

$running = null;

do {

curl_multi_exec ( $mh, $running );

// it’s a good idea to reduce load, here it’s 1 micro second

usleep ( 10000 );

} while ( $running > 0 );

// get the content of the transaction, this will contain (in our case) things like the transaction id, credits remaining etc

for($i = 0; $i < count ( $handles ); $i ++) {

// get the content of the handle

$output [] = curl_multi_getcontent ( $handles [$i] );

// remove the handle from the multi handle

curl_multi_remove_handle ( $mh, $handles [$i] );

}

// close the multi curl handle to free system resources

curl_multi_close ( $mh );

return $output;

}

}

?>

Visual C#.Net Console application that demonstrates sending a SMS Message and getting the number of credits remaining using both POST and GET HTTP calls

Application Notes:

• It uses the Sandbox server and the user must add his/her username and password.
• The program was written in Visual Studio 2010.

Many thanks to Andy.

Download Zip file

Email however is a great tool to maintain a thread or conversation, but lacks the penetration that SMS has. To solve this issue at Text Marketer, we have developed a system that uses your standard email client (such as Outlook) to maintain a short conversation with a customer but the communication method is SMS.

A real life example

A recruitment company has several account managers responsible for various vacancies. A vacancy has arisen for a job in IT, the account manager (let’s call him Bill) selects 20 of his best candidates and sends the standard job ad via his email client to our Email to SMS gateway……meanwhile another urgent vacancy has arisen and again Bill selects his top candidates and using email sends them the job ad as a text message. So at this point he has two vacancies sent out to say 40 people. The problem would now arise where by the candidate texts back saying something like “Can you send me more information”, but at this point how does Bill know which vacancy he is asking about? Traditinally he’d have to match up the mobile to the communication he had sent.

The Text Marketer system is different because it also contains the original message with the response, so Bill would see his original job ad, what time and date he sent it and then the response from the candidate with the time it was sent. Now when any candidate texts back he knows which job they are referring to. The system has a thread or conversation element to it, just like normal email. Bill can then just hit reply and send the next part of the communication (perhaps asking him to call in), his reply is automatically converted into SMS by our email gateway and the candidate receives Bill response.

Documents:

How to configure your email to send to Text Marketer

To set up threaded SMS call us on 117 924 9207

TO: <mobile number>@textmarketer.bz
SUBJECT: <username>%<password>

Hello World##

Simple!
The username and password is found in the API settings of your account. You can also set the originator (sender id) there as well, or if you want to set it on a message basis you just do the following:

TO: @textmarketer.bz
SUBJECT: <username>%<password>
Hello World##
James#

Would send an sms from “James”

Lastly if you want to send the same message to mulitple people the format changes somewhat

TO: gateway@textmarketer.biz
SUBJECT: <username>%<password>
Hello World##
James#
 <mobile number>
 <mobile number>
 <mobile number>

As you can see this is a very simple system to use. The sms gateway will accept plain text or html emails so sending from outlook for example is supported. Also it is worth noting that the message can be 612 characters long as concatenation automatically occurs after 160 chars message length.

Our email-to-SMS service provides a simple way for you to send text messages via email.

This is in addition to our simple HTTP SMS Gateway API, explained here, and we also provide a more complex ‘RESTful’ SMS API to send SMS messages and give you access to information about your SMS marketing account (don’t have one? You need to have an account).

There are 3 main ways to use the email to sms gateway;

Option 1 – To send single emails/messages using domain authentication
Option 2 – To send single emails/messages using username/password authentication
Option 3 – To send messages to multiple recipients with a single email (and advanced features)

Option 1 – Send single emails/messages using domain authentication

This option is used when you cannot or do not want to transmit your username and password in the subject field of the email. You set your sending domain in your account, e.g. mycompanyname.com which is what we use for validation when the email comes in. Only emails sent from the domain you set will be accepted (no generic email accounts like hotmail or gmail are acceptable).

Step 1 – enable domain authentication in your Text Marketer account. Go to Settings | Account Settings as shown below.

Under “Email Gateway Settings” enter your domain name (e.g. if your email address was richard@greens.com then your domain name is greens.com) in the field and press submit (do not include the @ sign). The system will return an ‘updated’ message.

Then, click change next to your domain name and make sure it turns from disabled to Active (in red).

Step 2 – now you are ready to send a test message. Format the email address as [mobilenumber]@textmarketer.biz (for example, 447777111999@textmarketer.biz) and send it our gateway. Make sure you add ## to the end of the text in the body you want to send (this tells our system that this is the end of the text to send out and avoids sending things like signatures etc). You can change the message termination string by logging into your account and navigating to “settings” => “Account Settings”.
You don’t have to put anything in the subject line as it’s not used.

Here’s an example message (note the ## added at the end of the text to be sent):

Option 2 – To send single emails/messages using username/password authentication

This option is exactly the same as option 1 apart from you do not need to turn on domain authentication in your account and instead you use your API username and password in the subject field (formed like username%password) of the email for authentication. You can find your API username and password in your  account on the ‘Settings’ | ‘API Settings’ page.

So your email would look like this:

Option 3 – To send messages to multiple recipients with a single email (and advanced features)

1. Create an email to the address shown above
IMPORTANT: this must be the gateway[at]textmarketer.co.uk address, not a [number]@ style address or it will fail.
2. Put your API username and password in the subject field with a % symbol in between (no spaces). You can find your API username and password in your  account on the ‘Settings’ > ‘API Settings’ page but it is usually the same unless you’ve updated your login details.
3. Type the text message you want to send and at the end put two hash symbols “##”
4. Put 1 or many numbers in a single column underneath (it’s always best in international format but UK numbers starting 07…… are OK too).
5. Send the email!

Expanded Instructions / Additional Features

The Email-to-SMS (or email-to-text-message) service allows you to send SMS text messages via email. You must have an SMS marketing account (you can create a free account here) to send text messages via this service.

The actual email address of the email-to-SMS gateway is shown in the screenshot above (gateway@ and the domain is textmarketer.co.uk).

To send a text message to one or more mobile numbers, you will specify the message to send, and the numbers to send to, in an email. You then send the email to our email-to-sms gateway email address (using a specific format/structure).

Let’s say you want to send a text message containing ‘Call us for a quote’ to the UK mobile number 07777123456. To do this your email contents would look like this:

Call us for a quote##
07777123456

The ‘##’ characters simply tell us that this is the end of the message to be sent. And it’s followed by the mobile number. That’s it!

IDENTIFICATION

Your email will contain your account’s API username and password in the email subject. This allows us to verify your identity and deduct credits for the text messages sent from your account.

Your email subject should contain your API username, followed by ‘%’, followed by your API password (You can find your API username and password in your  account on the ‘Settings’ > ‘API Settings’ page.), e.g.

myAPIusername%myAPIpassword

Example

So the complete email (subject and body) would look like this:

Email Subject:

myAPIusername%myAPIpassword

Email Body/Contents:

Call us for a quote##
07777123456

MULTIPLE RECIPIENTS

You want to send a text message via email to more than one mobile number? No problem! Simply list the numbers on separate lines, like this:

Call us for a quote##
07777123456
07777123457

Or put them on the same line, with commas in between to separate the numbers, like this:

Call us for a quote##
07777123456,07777123457

MESSAGE WITH MULTIPLE LINES

A message sent using the email-to-SMS gateway can contain more than more line. Simply ensure the message still ends with ‘##’, e.g.:

Special offer this week on:
- black tights
- green shoes##
07777123456

FROM/SENDER ID

The sender ID is the number/name that your text message will appear as being sent from. When using the email-to-text API this defaults to the sender ID that is set in your account settings (see the ‘Send SMS’ > ‘Default Sender ID’ page). For example, you might want to set the sender ID as the name of your business, or perhaps to your own mobile number.

The sender ID can be any 16-digit number, or any text of up to 11 alpha-numeric characters.

Example

Let’s say you want to send the message ‘Special 2-for-1 offer this week’ to the UK mobile number 07777123456, with a sender ID of ‘Fast Pizzas’. Your email body (contents) would look like this:

Special 2-for-1 offer this week##
Fast Pizzas#
07777123456

The sender ID is ‘terminated’, i.e. ends with, a single ‘#’ character. It can appear before or after the message, so this works too:

Fast Pizzas#
Special 2-for-1 offer this week##
07777123456

ERROR REPORTING

If your email-to-SMS request is successful, with no errors or problems, you will not get any response (unless you’re using the Sandbox service). However, if there are any problems with the format of your email, or problems sending to any of the numbers you specify in the email, you will get a verbose email response with details of the problem(s) encountered.

Note that you will not get any response if your API username or password (included in the email subject) were incorrect, or did not contain the ‘%’ character to separate them.

TESTING/SANDBOX

If you want to test the service without actually sending any text messages, there is a different email address to use for this purpose:

gateway-sandbox@ followed by the same domain: textmarketer.co.uk

It works in the same way as the normal service, except that no text messages will be sent and therefore no credit will be deducted from your account. Also, unlike the normal service, you will get a confirmation email telling you what message would have been sent, and to what numbers, if you had used the normal live service.

keywords

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

Resource URI:

http://www.textmarketer.biz/services/rest/keywords/mykeyword

Actions on the ShortCode keywords (see Short Code SMS Service).

• GET method – get the availability of a given keyword

GET method

Test whether the specified keyword is available on our ShortCode number.

RESOURCE_ID: the keyword of which to test the availability, e.g. ‘mykeyword’ in the example above

Example usage

http://www.textmarketer.biz/services/rest/keywords/buyit

will test whether ‘buyit’ is an available keyword.

Example GET response

<response processed_date="2010-05-06T13:43:18+02:00">
<available>true</available>
<recycle>false</recycle>
</response>

The <available> tag shows whether the keyword is available (true/false) and the <recycle> tag shows whether the keyword is available through ‘recycling’ a disused keyword, i.e. one that was in use previously.

Read the advanced specification of this response.

Specific error codes

N/A

Example PHP code

<?php
/**
 * GET request on the 'keywords' resource
 */
$url = 'http://www.textmarketer.biz/services/rest/keywords/mykeywordtest'; // 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);
	$available =  $xml_obj->available == 'true';
	$recycled =  $xml_obj->recycle == 'true';
	// do something with the result
	if ($available)
		echo "Available ";
	else
		echo "Unavailable ";

	if ($recycled)
		echo "(recycled)";

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

sms

This resource deals with sending SMS to customer.

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

Resource URI:

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

Actions relating to sending SMS messages.

• POST method - Used to send an SMS message.

POST

POST method

Attempts to send the specified SMS message.

Example usage:

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

Post arguments:

* Can be found by logging in to your account, Settings->API Settings

CONCATENATION

CONCATENATION

If you exceed 160 characters you automatically invoke concatenation sending, this has the following consequences: Each message consists of a 153 character ‘chunk’, i.e. no longer 160 chars; the extra characters are used to glue the messages together. Therefore a message that is 307 characters long will require 3 messages to send (153 + 153 + 1).

Example POST response:

<response processed_date="2010-03-23T10:31:39+00:00">
	<message_id>4172870907</message_id>
	<credits_used>1</credits_used>
</response>

• message_id – the unique message ID attributed to the sent SMS
• credits_used – the number of credits used to send the SMS

Read the advanced specification of this response.

Specific error codes:

CONCATENATION

Example XML error response:

<response processed_date="2010-03-24T14:37:41+00:00">
<errors>
	<error code="10">invalid number or not an integer</error>
	<error code="9">invalid number or too short</error>
</errors>
</response>

Example PHP code:

<?php
/**
 * POST request on the 'sms' resource (send an SMS)
 */
$url = 'http://www.textmarketer.biz/services/rest/sms';
//$url = 'http://sandbox.textmarketer.biz/services/rest/sms';

$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!

$data = array('message'=>'hello','mobile_number'=>'447777123123', '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);
}
?>

NOTE

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. Delivery reports, however, confirm to you what has actually happened to the sent message. See the deliveryReport resource.

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);
}

?>

deliveryReports

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

Resource URI:

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

Actions on the list of available delivery reports.

• GET method - Gets a list of available delivery report names

The REST API resource deliveryReports (note the trailing ‘s’) performs actions on the list of available delivery report names, including delivery reports for campaigns.

A delivery report shows the current known status of all messages sent on a given day or for a particular campaign. To access the contents of a particular delivery report – which will contain the status of individual messages – you would use the deliveryReport resource instead - i.e. no trailing ‘s’.

GET

GET method

Get the list of available delivery reports.

Example usage

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

Example GET response

<response processed_date="2010-03-19T15:20:49+00:00">
	<userdirectory>aBcDeFgHiJkLmNoPqRsTuVwZ</userdirectory>
	<reports quantity="2" >
		<report name="test-190310" last_updated="2010-03-19T09:45:04+00:00" extension="csv"/>
		<report name="GatewayAPI_08-03-10" last_updated="2010-03-08T15:45:02+00:00" extension="csv"/>
	</reports>
</response>

Read the advanced specification of this response.

When we receive a delivery 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

Specific error codes

N/A

Note

Although it is expected that you will want to use the deliveryReport resource to get the contents of a delivery report, the response as shown above contains all the information necessary to download the delivery reports in csv format, if that is your preferred method. In this case each report can be accessed via the URL

http://www.textmarketer.biz/DeliveryReports/[dir]/[filename]

where

[dir] = the user directory as found in the response above, i.e. in the above example aBcDeFgHiJkLmNoPqRsTuVwZ
[filename] = the name of the csv file to download, e.g. GatewayAPI_08-03-10.csv

So the complete URL in this example would be:

http://www.textmarketer.biz/DeliveryReports/aBcDeFgHiJkLmNoPqRsTuVwZ/GatewayAPI_08-03-10.csv

Example PHP code

<?php
/**
 * GET request on the deliveryReports resource
 */
$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);
}
?>

credits

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

Resource URI:

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

Actions on the account credits.

• GET method - get the number of credits currently available on your account
• POST method - transfer credits between accounts

GET

GET method

Get the number of credits currently available on your account.

Example usage

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

Example GET response

<response processed_date="2010-03-19T15:19:33+00:00">
<credits>37</credits>
</response>

Read the advanced specification of this response.

Specific error codes

N/A

Example PHP code

<?php
/**
 * GET request on the 'credits' resource
 */
$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);
}

?>

P

POST method

Transfer credits from the source/master account to the target/sub account.

Example usage

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

Post arguments

or

OR you can specify the target account user name and password, rather than the target account number

Example POST

Example POST response

<response processed_date="2010-03-23T10:31:39+00:00">
	<source_credits_before>1000</source_credits_before>
	<source_credits_after>900</source_credits_after>
	<target_credits_before>0</target_credits_before>
	<target_credits_after>100</target_credits_after>
</response>

Read the advanced specification of this response.

Specific error codes

Example XML

Example XML error response

<response processed_date="2010-03-24T14:37:41+00:00">
<errors>
	<error code="0">Invalid number of credits specified: -1</error>
	<error code="1">Invalid destination account number</error>
</errors>
</response>

Example PHP code

<?php
/**
 * POST request on the 'credits' resource (credit transfer)
 */
$url = 'http://www.textmarketer.biz/services/rest/credits';
// uncomment 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,
	// or you could use the target username/password instead of 'target'
	// 'target_username'=>$targetUserName, 'target_password'=>$targetPassword,
	'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 "Source account credits before: $xml_obj->source_credits_before\n";
	echo "Source account credits after: $xml_obj->source_credits_after\n";
	echo "Target account credits before: $xml_obj->target_credits_before\n";
	echo "Target account credits after: $xml_obj->target_credits_after\n";
} else {
	// handle the error here
	var_dump($responseInfo);
	var_dump($responseBody);
}
?>

In addition to our simple HTTP SMS Gateway API, explained here, we also provide a ‘RESTful’ SMS API to give you access to information about your SMS marketing account (don’t have one? Create a free account).

If you are familiar with REST APIs, you may wish to jump to our REST API specification document.

WHAT’S A ‘RESTful’ SMS API?

REST is a term used to describe a type of two-way communication via the Internet. It is an architectural style, not a standard, but makes use of well-known web technologies such as HTTP, XML and MIME types. For more information about REST APIs, read this great description of REST.

At its most simple, our RESTful SMS API allows you to request (‘GET’) information. For example, from this ‘resource’

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

you can access the number of credits available in your account. The response is an XML document that looks like this:

<response processed_date="2010-03-19T09:37:26+00:00">
<credits>37</credits>
</response>

The SMS REST API is that simple!

WHAT ABOUT SECURITY?

Although it’s not apparent from the example above, the interface does require authentication using your SMS API account username/password. We provide two ways of passing this information to the server.

The first is via HTTP Basic Authentication, which is demonstrated by the login box that appears if you click on the resource link above. HTTP Basic authentication can of course be handled within your code. However if you prefer a simpler method, you can pass the parameters via the URL as GET arguments, e.g.

http://www.textmarketer.biz/services/rest/credits?username=myusername&password=mypassword

It is also recommended that you use encrypted communication with the REST Web Services by accessing resources via the HTTPS protocol (https://… etc.).

HOW DOES THE RESTful API HANDLE ERRORS?

An advantage of using a RESTful API is that the underlying technologies already do a lot of the work for us. All responses via the HTTP protocol include headers that give us some information about the response. The headers in the above example would look like this:

Date: Fri, 19 Mar 2010 10:11:40 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 272
Connection: close
Content-Type: application/xml

200 OK

The MIME type (Content-Type) is set to application/xml which identifies the type of content in the response. It is followed by the response status code ’200′ and the status message ‘OK’. This is a standard response to a successful request.

If we had tried to access a resource which didn’t exist, e.g.

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

we would get the following response headers:

Date: Fri, 19 Mar 2010 10:18:23 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 549
Connection: close
Content-Type: application/xml

404 Not Found :  (ERR101)

The status code is 404, which is the HTTP protocol’s standard code for ‘resource not found’. The status message also contains some additional debugging information (ERR91) which you can ignore.

In addition to the status code, the response body contains XML detailing the error. In this example it might look like this:

<response processed_date="2010-03-24T14:45:54+00:00">
<errors>
	<error code="404">Not Found :  (ERR101)</error>
</errors>
</response>

Thus, you can check the header status code for an error code, as well as the response body.

WHAT RESOURCES CAN I ACCESS THROUGH THE REST SMS API?

At the moment, the resource URIs available to you are:

• http://www.textmarketer.biz/services/rest/credits – to get the credits available on your account / transfer credits between accounts
• http://www.textmarketer.biz/services/rest/deliveryReports – to list your delivery reports
• http://www.textmarketer.biz/services/rest/deliveryReport/a_report_name – to access the details of a specific report
• http://www.textmarketer.biz/services/rest/sms – to send an SMS
• http://www.textmarketer.biz/services/rest/keywords – to get the availability of a given keyword (see Short Code SMS Service)

More will be added in the future.

Here are 2 walk-through examples for using the REST SMS API.

EXAMPLE REQUEST 1 – GET CREDITS

Make an HTTP GET request like this:

http://www.textmarketer.biz/services/rest/credits?username=myAPIusername&password=myAPIpassword

Obviously, replace ‘myAPIusername’ and ‘myAPIpassword’ in the URL with the ones you received when you signed up.

When you send this request using your favorite programming language, you should receive the following HTTP headers in response:

Date: Wed, 24 Mar 2010 15:17:28 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 272
Connection: close
Content-Type: application/xml

200 OK

Using your programming language, you can easily extract the status code (200 in this case), which indicates success (200) or failure (not 200). The status code of 200 here shows us the request was successful, i.e. the response contains the number of credits in your account.

Thus the HTTP response body that you receive will contain XML similar to this:

<response processed_date="2010-03-24T15:17:28+00:00">
<credits>10</credits>
</response>

In your programming language you can parse the XML to extract the value of the credits, in this case 10.

But if, for example, you use an incorrect password, the response headers will look like this:

Date: Wed, 24 Mar 2010 15:30:10 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 377
Connection: close
Content-Type: application/xml

403 Forbidden : Your username/password combination did not match an account. (ERR145)

The 403 status code shows that an error occurred (all codes except 200 indicate an error). And the XML response body will also contain:

<response processed_date="2010-03-24T15:29:22+00:00">
<errors>
	<error code="403">Forbidden : Your username/password combination did not match an account. (ERR145)</error>
</errors>
</response>

EXAMPLE REQUEST 2 – SEND SMS

In your programming language, create an HTTP POST request to this URL:

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

Since this is a POST request, you cannot pass the username and password via the URL, so you need to use HTTP Digest Authentication, or simply include these parameters along with the other POST parameters you’ll need:

• message=’my message’
• originator=’me’
• mobile_number=’447777777777′
• username=’myAPIusername’ (replace with your own – or skip this parameter and use HTTP Digest Authentication)
• password=’myAPIpassword’ (replace with your own – or skip this parameter and use HTTP Digest Authentication)

POSTing an HTTP request using the above as POST parameters would send an SMS message of ‘my message’ to the mobile number 447777777777 from “me”.

NOTE: It will not work to pass these parameters as GET arguments (e.g. by appending them to the URL); this is the principle of a REST API.

Your HTTP POST request should return something similar to the following response headers:

Date: Wed, 24 Mar 2010 15:17:28 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 272
Connection: close
Content-Type: application/xml

200 OK

…the ’200′ status code showing that your request was successful. The HTTP response body will consist of XML containing the ID of the SMS sent as well as the number of credits used to send it:

<response processed_date="2010-03-23T10:31:39+00:00">
	<message_id>4172870907</message_id>
	<credits_used>1</credits_used>
</response>

If, however, there was a problem with your request parameters, for example you set mobile_number to ‘garbage’, you would get similar response headers to this:

Date: Wed, 24 Mar 2010 15:30:10 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 377
Connection: close
Content-Type: application/xml

404 Bad request

And the response body would contain XML detailing the precise problems with your request, like this:

<response processed_date="2010-03-24T14:37:41+00:00">
<errors>
	<error code="10">invalid number or not an integer</error>
	<error code="9">invalid number or too short</error>
</errors>
</response>

See the specification of the sms resource for more details of the possible error codes.

TESTING/SANDBOX

A sandbox service is available for testing your code without changing your account or using any credits.

MORE INFORMATION

For detailed information about our RESTful SMS API, please see our REST API specification document.

For reference, a list of the DTDs that correspond to the resources available can be found here.

For an overview of what REST and our RESTful SMS API is all about you may like to read our RESTful SMS API Overview.

If you prefer you can use the simple SMS gateway, rather than our RESTful implementation.

To get straight into the details, jump to:

Quick Start
Error codes

Sandbox

You can preform the following actions using the REST web service:

• send an SMS (sms post)
• get the number of credits available (credits get)
• transfer credits from one account to another (credits post)
• get a list of delivery reports (deliveryReports get)
• get the contents of a specific delivery report (deliveryReport get)
• check availability of a given keyword on our ShortCode number (keywords get)
• check the names and IDs of your send groups (groups get)
• add number(s) to a send group (group post)

Specification of the resources

1. credits
2. deliveryReports
3. deliveryReport
4. sms
5. keywords
6. group
7. groups

QUICK START
Three things are essentially needed to use the REST SMS API:

1. Ability to make a HTTP request
   • e.g. to https://www.textmarketer.biz/services/rest/credits
2. Ability to read the HTTP response headers
   • e.g. ’200 OK’
3. Ability to parse the XML response
   • e.g. <credits>37</credits>

The Request URI Explained

You will make the HTTP request to a request URI such as:

https://www.textmarketer.biz/services/rest/credits

The base request URI is thus composed of :

‘https://www.textmarketer.biz/services/rest/‘ + a string that denotes the resource to be accessed, e.g. ‘credits‘, ‘deliveryReports‘, etc.

You can use http instead of https, but https is recommended.

Note that cAsE matters, i.e. ‘deliveryReports‘ will work, whereas ‘deliveryreports‘ (lower case ‘r’) will return an error.

You must obviously identify yourself during the request. If you know how to handle HTTP Digest Authentication, that is the preferred method of authentication.

Otherwise you should attach the following to the end of the resource URI:

?username=myAPIusername&password=myAPIpassword

Or, in the case of a POST request, such as for sending an SMS, include the username/password parameters in the POST parameters (e.g. see sms post).

In our example, the complete URI that results is:

https://www.textmarketer.biz/services/rest/credits?username=myAPIusername&password=myAPIpassword

And this should return XML containing the number of credits available on your account.

The HTTP Response Headers

The only vital part of the response headers that you need is the status code. 200 means a successful request, all other codes returned will be errors.

If you get an error, the status message may give you some extra information about the error. For more details about the error codes and their meanings, see Error Codes below.

The XML response

The structure of the XML response is generally quite simple. The response to our credits request example would look like this:

<response processed_date="2010-03-19T14:08:40+00:00">
<credits>37</credits>
</response>

Your preferred programming language will have a method for parsing the XML response to obtain the value.

Example PHP code

<?php
/**
 * GET request on the 'credits' resource
 */
$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);
}

?>

See the REST API Code Examples for some more example code that you can use.

That’s the end of the Quick Start. You know to send the request, check the status code is 200, and then parse the XML according to its declared structure.

Error codes

ERROR CODES

The HTTP status codes returned by our REST SMS API follow normal HTTP conventions. An example of the HTTP response headers from a request to our REST API:

Date: Wed, 24 Mar 2010 14:45:54 GMT
Server: Apache/2.2.3 (Red Hat)
X-Powered-By: PHP/5.2.11 ZendServer/4.0
Content-Length: 317
Connection: close
Content-Type: application/xml

404 Not Found :  (ERR101)

You see the status code, 404 on the last line. Their meaning of the status codes in the context of our REST SMS API are as follows:

This list is not exhaustive, any code from the complete list of HTTP status codes may be returned.

IMPORTANT NOTE: Error 503 may be returned if you exceed a certain number of requests per minute. You will see an error message similar to: “Your 201 requests exceed the maximum allowed of 100 requests within 15 minute(s). Please try again later”. This to reduce load on our servers, in order to guarantee a good service to all our users.  There is no restriction on SMS sends.

USEFUL NOTE: the HTTP status message may contain more specific information. If you encounter an unexpected error, the ‘(ERRnn)’ found in the status message is useful in any reports you send us.

In addition to the status codes, an error will also produce an XML response containing details of the error. In this example the XML response might look like this:

<response processed_date="2010-03-24T14:45:54+00:00">
<errors>
	<error code="404">Not Found :  (ERR101)</error>
</errors>
</response>

Some resources, such as http://www.textmarketer.biz/services/rest/sms, have additional error codes specific to the resource. These are documented along with the description of the resource.

Resource Identifier

THE RESOURCE IDENTIFIER

The example of a resource identifier used previously was:

https://www.textmarketer.biz/services/rest/credits

All our REST SMS Web Service resource identifiers take the general form:

PROTOCOL://RESOURCE_NAMESPACE/RESOURCE_NAME[/RESOURCE_ID]

where

PROTOCOL = http|https
RESOURCE_NAMESPACE = www.textmarketer.biz/services/rest
RESOURCE_NAME = credits|deliveryReports|deliveryReport|sms|keywords|etc

RESOURCE_ID = an_ID (optional) which specifies a particular resource element, e.g. a specific delivery report

e.g.

https://www.textmarketer.biz/services/rest/deliveryReport/GatewayAPI_09-02-10

will access a delivery report named ‘GatewayAPI_09-02-10‘.

Resources

RESOURCES

The currently implemented resources are:

1. credits
2. deliveryReports
3. deliveryReport
4. sms
5. keywords
6. group
7. groups

1. credits

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

• GET method - get the number of credits currently available on your account
• POST method - transfer credits between accounts

See the full description of this resource for details.

2. deliveryReports

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

• GET method - Gets a list of available delivery report names

See the full description of this resource for details.

3. deliveryReport

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

• GET method - Gets the contents of a delivery report – the delivery status of sent messages for a given day/campaign.

See the full description of this resource for details.

NOTE: An individual delivery report that is accessed using this resource shows the current known status of all messages sent on a given day, or for a particular campaign. The REST API resource deliveryReports (note the trailing ’s’) gets a list of available delivery report names, including delivery reports for campaigns (see above).

4. sms

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

• POST method - Used to send an SMS message.

See the full description of this resource for details.

5. keywords

http://www.textmarketer.biz/services/rest/keywords/mykeyword

• GET method - get the availability of a given keyword (see Short Code SMS Service)

See the full description of this resource for details.

6. group

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

• POST method - add number(s) to a send group

See the full description of this resource for details.

7. groups

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

• GET method - list the available send groups

See the full description of this resource for details.

Sandbox

TESTING/SANDBOX

A sandbox service is available to allow you to test your integration code without using any credits or executing any function that would modify the data in your account. The service is available at

http://sandbox.textmarketer.biz/services/rest

i.e. only the hostname changes from www.textmarketer.biz to sandbox.textmarketer.biz within the resource URI.

The sandbox will do the same validation of your request as the live REST API and return the appropriate errors, but will not perform any action that modifies your account data or your credits. Nor will it actually send any SMS messages, so no delivery report will be generated.

NOTE: Accesses to the sandbox is limited to a certain number of requests per minute – to reduce load on our servers – in order to guarantee a good service to all our users. Therefore you may prefer to use the Sandbox only to check that individual requests work correctly, rather than testing bulk SMS sends. There is no restriction on SMS sends on the live system.

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.

A code example for sending SMS via a Delphi Pascal language, thanks to Graham Murt for the example code.

{*******************************************************************************
*                                                                              *
*                 TextMarketer Delphi/Pascal Interface                         *
*                                                                              *
********************************************************************************

{

  example use:

  procedure TForm1.Button1Click(Sender: TObject);
  begin
    SendTextMarketerSms(username, password, sender, recipient, message);
  end;

}

unit untTextMarketer;

interface

uses Classes, IdHttp;

const
  C_HTTP_URL  = 'http://www.textmarketer.biz/gateway/';

type
  TTextMarketerSMS = class
  private
    FHttp: TIdHttp;
    FPassword: string;
    FUsername: string;
  public
    constructor Create; virtual;
    destructor Destroy; override;
    function SendSms(AOriginator,
                     ANumber,
                     AMessage: string;
                     AXmlResponse: Boolean): string;
    property Username: string read FUsername write FUsername;
    property Password: string read FPassword write FPassword;
  end;

  function SendTextMarketerSms(AUsername, APassword, ASender, ANumber, AMessage: string): string;

implementation

uses SysUtils;

function SendTextMarketerSms(AUsername, APassword, ASender, ANumber, AMessage: string): string;
var
  ASms: TTextMarketerSMS;
begin
  ASms := TTextMarketerSMS.Create;
  try
    ASms.Username := AUsername;
    ASms.Password := APassword;
    Result := ASms.SendSms(ASender, ANumber, AMessage, True);
  finally
    ASms.Free;
  end;
end;

{ TTextMarketerSMS }

function UrlEncode(const DecodedStr: String): String;
var
  I: Integer;
begin
  Result := '';
  if Length(DecodedStr) > 0 then
    for I := 1 to Length(DecodedStr) do
    begin
      if not (DecodedStr[I] in ['0'..'9', 'a'..'z',
                                       'A'..'Z', ' ']) then
        if DecodedStr[I] = '£' then
          Result := Result + '%C2%A3'
        else
          Result := Result + '%' + IntToHex(Ord(DecodedStr[I]), 2)
      else if not (DecodedStr[I] = ' ') then
        Result := Result + DecodedStr[I]
      else
        begin
          Result := Result + '%20'
        end;
    end;
end;

constructor TTextMarketerSMS.Create;
begin
  inherited;
  FHttp := TIdHTTP.Create(nil);
end;

destructor TTextMarketerSMS.Destroy;
begin
  FHttp.Free;
  inherited;
end;

function TTextMarketerSMS.SendSms(AOriginator, ANumber, AMessage: string;
  AXmlResponse: Boolean): string;
var
  AResult: Boolean;
  AParams: AnsiString;
  AResponse: TStringList;
begin
  AResponse := TStringList.Create;
  try
    AParams := '';
    AParams := AParams + ('?username='+FUsername);
    AParams := AParams + ('&password='+FPassword);
    AParams := AParams + ('&number='+ANumber);
    AParams := AParams + ('&orig='+UrlEncode(AOriginator));
    AParams := AParams + ('&message='+UrlEncode(AMessage));
    if AXmlResponse then AParams := AParams + ('&option=xml');
    try
      Result := FHttp.Post(C_HTTP_URL+AParams, AResponse);
    except
      Result := '';
    end;
  finally
    AResponse.Free;
  end;
end;

end.