Textlocal Logo

API Documentation

Helpful Information

Here is some general info you may find useful while using the Textlocal API.

Message Lengths

An SMS message is 160 characters in length, however multiple messages can be strung together to create a single long message. This is achieved by 2 or more individual SMS messages being sent at the same time and by using 7 hidden characters to string the messages together, it arrives and is read on the handset as one.

This can make calculating long message costs complicated, as a single message can be up to 160 characters but multiple conjoined messages are calculated in multiples of 153, 160 characters minus the 7 hidden characters to merge the messages together.

<= 160 1 credit
> 160 2 credits
> 306 3 credits
> 459 4 credits
> 612 5 credits
> 766 The message will be truncated to 765 characters.

Note: Message lengths are a restriction of SMS and are imposed by the networks, not Textlocal. The above credit costs are based upon sending to local numbers.

Message Delivery Status'

Our message reporting API's return a delivery status. The meaning of each status is detailed below.

D Message was delivered successfully.
U The message was undelivered.
P Message pending, the message is en route.
I The number was invalid.
E The message has expired.
? Unknown, we have not received a delivery status from the networks.

Note: There are many reasons a message can be set to status "U". For example the handset may have been switched off or out of signal range for a long period of time, usually more than 48 hours.

Default Contact Groups

Every Textlocal account comes with two default groups, contacts and opt-outs. These groups can be accessed via the API in the same way as user or API created groups, using the following groups ID's

5 The contacts group.
6 The opt-outs group.


The Textlocal API supports both POST and GET requests, while there are cases where GET can prove useful or sometimes be the only option for a developer, we highly recommend the use of POST. We suggest this for security reasons and because there is a limit to how many characters you can send via GET (approx. 8000). If you do opt to use GET you must URL encode your parameter values as detailed below.

URL Encoding

URLs can only be sent over the Internet using the ASCII character-set. Seeing as your API requests will often contain characters outside the ASCII set we highly recommend URL encoding your parameter variables for GET requests. This will stop errors occurring or improperly formatted requests being sent. A quick Google of "URL Encode" plus the language you will be developing in, will give information on how to go about this.

Note: URL encoding is only required for GET requests and there is no need to encode POST parameters.