It will cost them one text at their normal network rate. What exactly that is will depend on the individual’s network and tariff but is likely to be in the range of 8-12 pence. Sending a text to a short code is not included in a free text bundle tariff. So it will always cost 8 – 12 pence regardless of the network and tariff.

How much does it cost to send a text to a Txtus, virtual mobile number?

Texts sent to virtual mobile numbers cost one text at the sender’s standard rate. Texts are included in monthly free text allowance, so people on contracts will probably pay nothing at all. Pay as you go customers will be charged 8 – 12 pence depending on the network they’re using.

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 API spec can be found here

Sending SMS using C#, example code

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/

Using txtUs dedicated virtual mobile numbers for your business

A txtUs number gives your business a dedicated virtual mobile number which people can text (but cannot call) enquiries to or to reply to messages you send out to them from your system.

You can add as many txtUs numbers to your account as you wish and they can each have bespoke settings which can be a great solution for a small office environment or call centre where each member of staff could have their own txtUs number for their clients.

A quick 2 min Video Demo of the 2 main uses | See more videos

The unique advantage of the txtUs system is that the full conversation between you and each mobile number is sent to you via email and you simply reply via email. In essence, to answer the ‘how does it work?” question …. exactly like your email does. The only difference being of course that your replies are being sent out the customer as text messages.

Step 1 – Adding a txtUs number to your account

Login to your account. If you don’t have an account, you can set one up here.
Go to “Incoming SMS” | “Add a txtUs reply number”. Simply choose the number you want and press Place Order. This will take you through the Google Checkout system to set up the subscription payment for your txtUs number.

NEW! You can also pay for your txtUs number by recurring invoice rather than with a card

Your subscription may be cancelled at any time in your Google account and you have complete control of all payments.

Step 2 – Applying the settings for your txtUs number

Go to “Incoming SMS” | “Change reply settings” then click “Configure” next to your txtUs number. You will be presented with the screen below.

- Auto reply by SMS settings – If you would like to automatically send a text message back when somebody texts your txtUs number, you can set it here. Simply change active to ‘Y’, enter your text message and press submit.
IMPORTANT NOTE: The text autoresponse is only sent once to any individual mobile number, the first time they text in. This is to avoid them receiving the same autoresponse message over and over if you get into a conversation with them.

- Reply settings – This is where you set how your system handles the text conversations you have via email;

• Active – set to N if you do not wish to have incoming texts emailed to you
• E-mail – set the email address you wish incoming texts to go to.
• Thread Count – This is the amount of history you want included on each conversation email. For example, if you wanted to see the last 5 messages from a person and the last 5 replies you sent them you would set it to 10.
• Use as Sender default – enable this if you want your txtUs number to be the default reply number for text messages you send out from your system

- Advanced (API) settings – only used for programmers to deliver incoming message data to a script URL. Please leave this inactive unless you are sure of what you’re doing.

Step 3 – Testing your new txtUs number / Seeing a conversation in action

Send a text message to your new txtUs number then, if enabled, check your email inbox on the email address you have set (if it doesn’t come pretty instantly, check any spam filters or folders you may have enabled). You will see you have a new message from yourself.

Now reply to that email in the normal way (as you would an email). The only difference being you must end the message you send back with ##. This tells our system that it’s the end of the reply and so doesn’t send all the history contained in the email below.

You will then receive the reply on your phone. If you reply back again, check your email again you will now see the conversation thread developing.

Below is a conversation thread email for example from a company confirming a meeting:

You can also see the name of the person texting in if they are in your Address Book.

Step 4 – Promoting your new txtUs number

Congratulations! Now you are a text enabled business and you can promote your number as you would your telephone number, fax number or email address. See how we do on our enquiries page. As a customer, you are free to use the txtUs logo next to your number which adds impact and encourages use.

Other Common Questions

Getting replies from text campaigns
To enable people to reply to you, you simply have to set the Sender ID as your txtUs number. When you have a txtUs number your account will automatically do this as the default, which you can change if you wish.

You will see a new setting on your send screens, “Use Reply Number”. Simply tick this to use your txtUs number:

Charges
You are only charged for messages you send out, not for incoming messages. The cost of this is just 1 credit per 160 characters as per normal charges.

Cancellation
You can cancel your number at any time. There are no fixed contract lengths. To do this simply log in to your Google Checkout Account and cancel your subscription payments.

Logs
All of your conversations are stored in a log. Go to “Incoming SMS” | “Reply Data” to download your full log for your txtUs number.

You can cancel your keyword or TxtUs number from within your Text Marketer account.
To do this this go to Incoming SMS – Change Reply Settings.
Click Cancel next to the keyword or TxtUs number.
You’ll then be asked to confirm that you wish to cancel the subscription.
By confirming, you subscription will immediately be cancelled.

You can also cancel you subscription by logging in directly to your Google account.

To do this, simply login to your Google account and cancel your subscription with Google. Text Marketer does not hold your Google login or credit card details. See Google Help for more information.

As soon as your monthly payment has been cancelled your keyword will automatically be removed from your account.

Please note that if you need to download data from the short code log, do this before cancelling your keyword as the data cannot be retrieved once a keyword has been cancelled.

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.

But that is only part of the story. Just as crucial to reliability are the systems in place that connect to the networks. There’s no point in have a direct Network connection if the servers are prone to falling over on a regualr basis. The chain is only as strong as the weakest link, so the saying goes.

So when companies are assessing different sms gateway providers, they should be asking where the provider’s systems are hosted. Server hosting companies vary enormously in quality and offer different services level agreements. SMS gateway providers need to be using specialist hosting companies that will guarantee server ‘up’ time.

In order to eliminate any server issues, Text Marketer uses Rack Space who is recognized as the global market leader in server hosting. They offer a guarantee of 100% up time.

In addition to bullet proof server hosting, Text Marketer has also developed a system architecture that maximizes the reliability of the sms service. Now for non-techies, all this means is that we’ve done all we can to make sure your bulk sms campaigns are delivered as planned. For the more technically minded, you may be interested in a quick overview of how this is achieved.

1. Our servers are based in a load balanced, clustered environment.
The idea is that internet load is balanced between machines and should one machine fall over another can take its place. The application server is the machine that does the processing of our code.

2. Our servers have RAID 1 (or mirrored) disks
This is where you have 2 hard disks in the server that mirror each other, should one fail, the system can keep running.

3. We use 64 bit Unix
All this really means is that we are using the most up to date operating system on our servers.

4. Managed backup
We have systems in place that back our data up to an off-line storage medium. This means should everything fail we still have the data to rebuild our systems.

If you have any specific technical queries, Nick Rich, our Technical Director is the man to speak to. He can be contacted on 0117 2050202

Following customer research, we have now built into all accounts the ability to upload numbers straight from Excel, without having to save the database as a .csv or .txt file.
This improvement will save time when uploading your numbers and makes sending your bulk sms campaigns even easier.

When you are preparing your database for upload, make sure that your list of numbers is in column A and that there is no column header. Duplicates and badly formatted numbers are automatically removed in the upload process.
The following mobile number formats can be processed.
07900122321
447900122321
7900122321
+447900122321
Please see our detailed instructions if you would like more information on uploading numbers to a group.

We’re always looking for ways of improving our systems and big thanks to all our customers who gave us such useful feedback. If you do have any ideas for how you think your Text Marketer account can be improved, please let us know, we’d love to hear from you.

Now obviously each company needs to tailor the text message specifically for their own target market. There are however a few golden rules that can help you get the best possible response from your bulk text campaign.

Below these, we have also included a few example template messages that we hope provide you with inspiration.

Don’t Use Text Speak

Some of your target audience won’t mind ‘text speak’ at all but a good many of them will be infuriated by it! Text speak can be confusing and can project an unprofessional image.

Don’t Cram In Too Many Points?

A text is only 160 characters so don’t be tempted to crowbar in loads of offers. Keep it simple, concise and clear.

Tell Your Audience Who You Are.

This may seem an obvious point but don’t assume your audience will immediately know who the text is from. Within your account, you can change the sender name so that the customer knows who it’s from before the text is even opened.

Have A Strong ‘Call To Action’.

Make sure that you make it clear what you want the customer to do. Don’t just quote your phone number but ask the customer to dial it. E.g Call us now on 080012345678

Use An ‘Attention Grabber’

Try to start your text with an attention grabber that will arouse curiosity and compel the customer to read on. This is usually a single or couple of words, often in capitals. The word ‘news’ is particularly effective.

Template SMS Messages…

NEWS! EJ Wines are now extending their 20% discount offer until 6 pm this Friday. For amazing offers on all our wines, call us now on 01234567890. www.ejwines.co.uk

Weather forecast is cold and wet. Cosy up at The Rock Inn from £125.00 for 2 nights B+B. Roaring fire, local ales, fine wines and dining. Call 0123456789 or reply ROCK to this text.

Beat the queue! Show this text at Metropolis Nightclub before 10pm tonight and we’ll take you through the members’ only entrance. Free single shot at the bar with this text.

MOT NOW DUE! Your car is now due for its MOT. Please call Mullins Ford now on 012345 67890 to book your car in. www.mullinsford.co.uk

JOB ALERT! Please call Access Recruit now on 012345 67890. We have a number of exciting new vacancies that match your skills and experience. www.accessrecruit.net

A massive 50% off all sports products at Campus Leisure this weekend. Logon now to www.campusleisure.biz. This offer will end at 7 pm on Sunday, so logon now and quote code X13.

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.

API customers can now send messages up to 612 characters long. If you exceed 160 characters you automatically covert to concatenation sending, this has the following connotations. Each message consists of a 153 character ‘chunk’ (not 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.

The API xml response has also be updated to include the element:

<credits_used></credits_used>

This element contains the number of credits used for that message send.

API bulk sending specification