Having established your short list of  bulk sms companies, you’ll then probably look at details such as the system itself, pricing, support and so on. There are 2 things that you should watch out for though, that might not be immediately apparant when you’re making your decision about which bulk sms service to use.

Expiring Credits

About 30% of bulk sms suppliers operate a curious policy of expiring sms credits. If you don”t use your bulk sms credits in a given period (usually 12 months), then your unused credits just disappear. We’ve always felt this a particularly harsh approach. After all you’ve purchased your bulk sms credits, it would seem reasonable to have as long as you want to use them. Take a look at our bulk sms price comparison table, which also includes information about whether each company has an expiring credits policy.

Unclear Pricing

You’d expect that when you’re looking at cost per bulk sms credit, that would mean the cost to send one text. Correct? Not necessarily. There are 2 companies that operate a credits systems where it costs more than one bulk sms text credit to send a message to a UK mobile. So a headline price of say 4.2 pence + VAT per credit may actually cost 6.75 pence + VAT to deliver the text. (1.5 credits needed to send a message to a UK mobile.)

The argument here is that when you have international bulk sms services, there are different prices for different counties so you need a system that can handle this. We’re not sure that this is the best way though and we know this causes confusion for buyers, It’s much clearer to have a simple 1 text credit is 1 text sent system.

If you haven’t already done so, you can set a free bulk sms account with Text Markerter here. You can assume that your credits  will never expire and the pricing is on a simple, 1 sms credit is 1 sms sent basis.

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

The 2 easiest methods of integrating Goldmine with our SMS Gateway are using;

1) The email to SMS gateway – http://www.textmarketer.co.uk/email-to-sms-gateway/email-sms.htm
Or
2) The HTTP gateway – http://www.textmarketer.co.uk/blog/2009/05/sms-gateway/text-marketer-apigateway-spec/

It’s a very straightforward task to build a small script in PHP to utilise our SMS Gateway to send out text messages.

The benefit of integrating your SMS Gateway with Text Marketer is that we have the lowest cost per message of any company in the UK.

You can find a sample PHP script for our SMS Gateway here and with a few basic modifications of the user details you should be able to have your application integrated within minutes.

We do also provide code snippets for other languages;

• PHP code example
• Visual C#.Net Console
• Delphi/Pascal Interface
• .NET examples
• ASP examples
• REST examples

If you have any queries or questions, our friendly and highly experienced technical team will be happy to help you out.

After 11 years of building SMS Gateways in PHP and other programming lanuguages, we’re confident we can help you overcome any task.

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.

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.

Simple Example of sending SMS with PHP

This class allows you to send SMS using PHP,  please feel free to modify at will. You just need the username and password from your account login as the constructor arguments. Download PHP 5 SMS API Class

Example:

$sms = new SendSMSXML("myUsername","myPassword");

/// send function args: mobile number, your message, the originator (sender id)

$sms->send("4477777777","my message","me");

As you can see there is nothing to it!

Take a look at the  more involved document describing how you can integrate PHP with the SMS short code service. This example uses a game where by you text in the number of sweets you think is in a jar. You then receive a response depending on how close you were.

To create an interactive game using Text Messaging and to show how easy it is to create interactive experiences using your Text Marketer Account. The example uses both our short code API (to receive the customer responses) and then our  gateway API to send out the ‘answer’.

The Game

Guess the number of sweets in a jar. A simple game where the participant texts in the number of sweets they think is in the jar and then receives a message indicating if they are high,  low , close or have correctly guessed to the number of sweets. Download all the required classes.

Mechanics

Fig 1 shows the how the basic flow of the systems works. The game is initiated by an incoming text message (as shown in orange) to our 88802 shortcode. The text message contains a keyword  in this case sweets and the data you which you need to parse.

Once the text message has been received in your account you can enable a trigger to be sent to your own script residing on your own server. The trigger is a GET request with the parameters added to it as per our short code documentation.

Your application/script can then use the data to geenrate a response. In our case we find out whether the participant has guessed the correct number and we send back an apporprate response using the Text Marketer API  Gateway see documentation for details.

Creating the game and code examples

The Guess number of sweets in a jar game and all the code you need can be downloaded here. It’s written in PHP 5.

Once you have created yourself a free account you need to request a free shortcode keyword from Text Marketer.

Next login into your account and set the url your wish to use for accessing your script. To access the set up screen, select from the menu “Incoming SMS” => “Change Reply Settings” then click “Configure” next to the keyword. You’ll then be able to paste the URL into the API URL window. Then press submit.

The game is broken the code down into 4 classes.

class SweetsInAJar

{

    function __construct()

    {

    $sms = new SendSMSXML("myUsername","myPassword");

    $theData = new ExtractData("sweets",$_GET['message'],$_GET['number']);

    $logic = new MessageLogic();

    $logic->setClosenessRangeInPercent(15);

    if($theData->isValid()){

       $sms->send($theData->getNumber(),$logic->getMessage($theData->getData()),"GuessGame");

    }

    else

    {

       $sms->send($theData->getNumber(),$logic->getFailedMessage(),"GuessGame");

     }

   }

}

Explanation
This is our main class that calls all the relevant objects and class together. Simply the logic works like this:

1. Set up all the objects you need.
2. Set the closeness to the number of sweets you will need to get before the “your are close” message will get sent .
3. If there is data we can use from the incoming message,  select the correct response and send it.
4. Otherwise select the “invalid format message” and send that.

class ExtractData

{
   private $theData;
   private $theMobileNumber;
   private $keyword;
   private $valid=false;
	

   function __construct($keyword,$message,$number)
   {
      $this->keyword = $keyword;
      $this->valid = $this->getMessageInfo($message);
      $this->theMobileNumber = $number;
    }

    public function isValid()

    {		

       return $this->valid;

     }

     public function getData()

     {

       return $this->theData;

     }

      public function getNumber()
      {
        return $this->theMobileNumber;
      }

      private function getMessageInfo($m)
      {
         //remove the keyword and set the result
	 //remove extra spaces
         $m=trim($m);

         $m=str_ireplace($this->keyword,"",$m); /// remove keyword
         $m=ltrim($m); // remove any spaces

         if(is_numeric($m)) {

              $this->theData = $m;
              return true; // is it data?
          }

           else return false;
      }

}

Explanation
This simple class allows us to extract the data we need from the short code response. The response contains the enitre message so we need to remove the keyword and any spaces then check to see if the result is a number.  If it is then the object is “valid” else it’s not valid and we can use this state to send the “invalid format message” as described above.

class MessageLogic

{

    private static $lowGuess ="Bad Luck! There are more sweets in the jar than you think, try again.";
    private static $highGuess="Bad Luck! There are less sweets in the jar than you think, try again.";
    private static $correctGuess="Well done! You have guessed the correct amount.";
    private static $closeGuess="Close Guess! you are within {value}% of the correct answer.";
    private static $badData="We couldn't understand your answer please text in the word SWEETS and your answer, for example SWEETS 300";
    private $numSweets=5678; //default
    private $closenessRange=5;  //5 percent as default 

	
    public function setNumberOfSweets($value)

    {
         $this->numSweets=$value;
    }

    public function setClosenessRangeInPercent($value) //in percent
    {
         $this->closenessRange=$value;
    }

    public function getFailedMessage()

    {
         return self::$badData;
    }

    public  function getMessage($value)
    {
         /// some very simple rules
         if($value==$this->numSweets) return self::$correctGuess;
         $isClose = round(((abs($this->numSweets - $value)) / $this->numSweets) * 100); // calculate how close the number is
         if($isClose < $this->closenessRange) return str_replace("{value}",$this->closenessRange,self::$closeGuess);    // if with in the closeness range return close messsage
         else{
              if($value > $this->numSweets) return self::$highGuess;
              else return self::$lowGuess;
         }
     }
}

Explanation

This is the game logic class, the getMessage function requires the integer that we extracted using the ExtractData class.  There are then some simple rules that select the appropriate message as the returned value.

For more information regarding the bulk sending API click here.

A simple example for sending SMS via a .NET method

Here’s a stand-alone .Net method:

private static string SendSms(string p_userName, string p_password, string p_orig, string p_number, string p_message, bool p_respondInXml) {

StringBuilder requestUrl = new StringBuilder();
requestUrl.Append(“http://www.textmarketer.biz/gateway/“);
requestUrl.Append(“?username=”).Append(HttpUtility.UrlEncode(p_userName));
requestUrl.Append(“&password=”).Append(HttpUtility.UrlEncode(p_password));
requestUrl.Append(“&orig=”).Append(HttpUtility.UrlEncode(p_orig));
requestUrl.Append(“&number=”).Append(p_number);
requestUrl.Append(“&message=”).Append(HttpUtility.UrlEncode(p_message));
if (p_respondInXml) {
requestUrl.Append(“&option=”).Append(“xml”);
}
WebRequest webRequest = HttpWebRequest.Create(requestUrl.ToString());
WebResponse webResponse = webRequest.GetResponse();
Stream responseStream = webResponse.GetResponseStream();
StreamReader streamReader = new StreamReader(responseStream);
return streamReader.ReadToEnd();
}
And here’s an example of calling it:

string response = SendSms(“MyUsername”, “MyPassword”, “MyNumber”, “4477777777″, “This is a test”, true);

For your information here are a list of the supported characters;

?

If you are using our campain bulk sms system then you will be alerted if you use any unsupported characters when you submit the sms campaign.

For SMS Gateway customers, you will receive a fail response for any messages submitted with unsupported characters.

Put that into an ASP page and change the username, password, message and orig in the url string and it will work.  In terms of parsing the XML, this is a useful reference: http://devguru.com/technologies/xmldom/quickref/xmldom_methods.html.  This code does not use the .net framework so it will work in both ASP and ASP.NET pages.  The only weakness in the solution above is the fact that there can be multiple reasons for failure, this solution will only take the first reason, but for some, this will be good enough.  To make the code handle this case, the else block would need a loop and you would use objXMLDoc.documentElement.selectNodes instead of objXMLDoc.documentElement.selectSingleNode.

2 classes available in php 5, SendSMS and SendSMSXML (recommended)

Class Name: SendSMS (depreciated)

This class is a nice and easy way to start sending SMS’s with the Text Marketer system, please feel free to modify at will. You just need the username and password from your account login as the constructor arguments.

Download the PHP 5 SMS API Class

Example of use

<?

$sms = new SendSMS("myUsername","myPassword");
if($sms->send("4477777777","my message","me")) echo "message sent";
else echo "message failed";

?>

Class Name: SendSMSXML

An updated class from SendSMS which uses the XML response and is simpler to use, please feel free to modify at will. You just need the username and password from your account login as the constructor arguments.

Download PHP 5 SMS API Class

Example of use

<?

$sms = new SendSMSXML("myUsername","myPassword");
if($sms->send("4477777777","my message","me")){

 	echo "I have ".$sms->getCreditsRemaining()." left and I used  ".$sms->getCreditsUsed()." credits";

}

else {

     while($error = $sms->getError())

     {

         echo $error;

     }

}

?>

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 :-)