Bulk SMS API - HTTP to SMS Web Service

Use the HTTP to SMS Web Service API to send bulk SMS text messages reliably and globally in seconds. The API is simple to integrate with, particularly from websites using AJAX, PHP, Perl and other similiar scripting languages. Our sample code page provides lots of examples to help you get started.

Servers, Security & Failover

We have multiple servers, two of which are available for public use with this API, so that in the event of an failure you should still be able to connect to us. At least one of these servers should always be available and for maximum reliability we strongly urge you to write your application to failover to the secondary server should the primary not be available for any reason.

We support both HTTP and HTTPS protocols but we strongly urge you to use HTTPS for greater security of your account information. You may use a GET rather than a POST but GET suffers from truncation limitations and has greater security issues, since you can very easily see the entire message including your Username and PIN on the URI line.

The HTTP API will authenticate you using your account Username and PIN (not Password). These will have been sent to you when you signed up.

HTTP Servers
Primary http(s)://www.csoft.co.uk/webservices/http/sendsms
Secondary http(s)://www2.csoft.co.uk/webservices/http/sendsms

HTTP Servers

Primary
http(s)://www.csoft.co.uk/webservices/http/sendsms
Secondary
http(s)://www2.csoft.co.uk/webservices/http/sendsms

HTTP Request

The HTTP POST request body comprises a set of tag=value pairs separated by ampersands (&) that specify the content that you want to send. For example, to send the message "Hello World" you would send a request like this:

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 75
    
Username=ANOther.12345&PIN=123456&SendTo=447700912345&Message=Hello%20World

Header Fields

When using the POST command you must specify the correct HTTP headers. In particular, the following must be set;

Host: www.csoft.co.uk
Content-Length: <the length of the query string>
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close

Character Encoding

See for information about how to URL encode plain text messages that contain special characters (such as space, ampersand, and quote). There is also a useful reference at on the subject.

If you wish to send messages in international character sets (such as Chinese, Hebrew, Russian, etc) use the Unicode encoding standard. When sending messages using the UTF-8 character set, be sure that the receiving phone device can accept and display messages in that language and note that the maximum size of a single message is then reduced to 70 utf-8 characters.

Each octet of the UTF-8 character you are encoding must be encoded as a separate hex encoded character. For example, to send the Hebrew Alef (Unicode 5D0) character you would use the following HTTP POST:

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 68

Username=ANOther.12345&PIN=123456&Message=%D7%90&SendTo=447700912345

Parameter Description

Parameter Required Description
Username Required This was sent to your email and looks something like ANOther.61234
PIN Required This was sent to your mobile/cell phone and looks something like 123456
SendTo Required The number of the phone that you wish to send to. The number should be in full International Format, including the Country Code. For example 447700912345 for a UK mobile. You can put more than one number in here in which case you should separate the numbers with a comma - for example 447700912345, 447700912346. We suggest that you do not put more than 350 numbers in each request.
SendToAddressBook Optional You can specify the name of your Address Book to use as the list of numbers to send your content to. To specify a group within that Contacts Manager, suffix the Contacts Manager Name with a double colon and the group name. e.g. SendToAddressBook=ContactsManagerName::Friends/
ReplyTo Optional If you have two-way service numbers then you can set the ReplyTo (MSISDN) that the message appears to come from. You can also use the query to determine which numbers are available to you.
Message Either The text of the SMS message. Special characters, such as space and ampersand, must be URL encoded according to the HTTP specification. See Encoding Characters.
FlashMessage Either Flash messages appear on the screen of the mobile without the user having to select "read message". The text of the flash message. Special characters, such as <space>, must be encoded according to the HTTP specification. See Encoding Characters.
SendTimeDelay Optional Specifies the number of minutes that the message should be delayed. The value must be between 1 minute and 10080 minutes (7 days).
SendTimeAbsolute Optional Specifies the date and time that you want the message to be sent. This must be in UTC (GMT). The format follows the ISO 8601 Standard (excluding timezone offset) YYYY-MM-DDTHH:MM:SS.
ResponseFormat Optional Allows you to control the format of the response for easier parsing. See ResponseFormat lower down this page.

Parameter description

Username (required)
This was sent to your email and looks something like ANOther.61234
PIN (required)
This was sent to your mobile/cell phone and looks something like 123456
SendTo (required)
The number of the phone that you wish to send to. The number should be in full International Format, including the Country Code. For example 447700912345 for a UK mobile. You can put more than one number in here in which case you should separate the numbers with a comma - for example 447700912345, 447700912346. We suggest that you do not put more than 350 numbers in each request.
SendToAddressBook (optional)
You can specify the name of your Address Book to use as the list of numbers to send your content to. To specify a group within that Contacts Manager, suffix the Contacts Manager Name with a double colon and the group name. e.g. SendToAddressBook=ContactsManagerName::Friends
ReplyTo (optional)
If you have two-way service numbers then you can set the ReplyTo (MSISDN) that the message appears to come from. You can also use the PermittedReplyTo query to determine which numbers are available to you.
Message (either)
The text of the SMS message. Special characters, such as space and ampersand, must be URL encoded according to the HTTP specification. See Encoding Characters.
FlashMessage (either)
Flash messages appear on the screen of the mobile without the user having to select "read message". The text of the flash message. Special characters, such as <space>, must be encoded according to the HTTP specification. See Encoding Characters.
SendTimeDelay (optional)
Specifies the number of minutes that the message should be delayed. The value must be between 1 minute and 10080 minutes (7 days).
SendTimeAbsolute (optional)
Specifies the date and time that you want the message to be sent. This must be in UTC (GMT). The format follows the ISO 8601 Standard (excluding timezone offset) YYYY-MM-DDTHH:MM:SS.
ResponseFormat (optional)
Allows you to control the format of the response for easier parsing. See ResponseFormat lower down this page.

Efficiency Considerations

If you plan to send multiple messages then, using HTTP 1.1, you may remove the Connection:close header and take advantage of a Keep-Alive connection. Note that the server will timeout and terminate your connection, however, if you do not send each message in quick succession. Furthermore, if you are sending the same message to multiple recipients do not send each as a separate HTTP POST. It is more efficient (and very much faster) to include each number as a comma separated list in the same packet (see below).

HTTP Response

The Server will only respond back once the whole SendTo list has been processed. If the message is successfully sent to everyone on the SendTo list then the Server will respond with a success message, or messages. If any of the numbers fail, it will continue to process the list, but the response will depend on the optional ResponseFormat chosen in the HTTP request. The default is format 0.

When ResponseFormat=0 the response is:

<report number><space><hyphen><space><report message>

For example

HTTP/1.1 200 OK
Date: Tue, 10 Dec 2002 14:33:38 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.7
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Transfer-Encoding: chunked
Connection:close
Content-Type: text/html;

171 - Invalid login. Username or PIN are missing or invalid.

When ResponseFormat=1 the response format is a tag=value style that is more appropriate for parsing. It uses the new report codes and the associated unique Message Identifier but will only return a single value for each tag, irrespective of how many numbers were submitted at once. If a failure occurs, the response will be the last failure. If all the messages succeed, the response will be for the last number.

HTTP/1.1 200 OK
Date: Tue, 10 Dec 2002 14:33:38 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.7
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Transfer-Encoding: chunked
Content-Type: text/html;

MessageIdentifier=30106CCE&Report=2&Text=Invalid%20Login&Units=0

When ResponseFormat=3 the response format is a tag=value style that is more appropriate for parsing. It uses the new report codes and the associated unique Message Identifier and will return a value for each tag for each number submitted, with multiple values separated by a comma.

HTTP/1.1 200 OK
Date: Tue, 10 Dec 2002 14:33:38 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.7
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Transfer-Encoding: chunked
Content-Type: text/html;

MessageIdentifier=30106CCE,30106CCF&Report=%2D2,15&Text=Accepted%20by%20csoft%3A%20queued,Out%20of%20credit

Response fields

Parameter Type Size Description

MessageIdentifier

string 15 A unique identifier for the message. You can use this to match against the message history and/or delivery receipts.
Report numeric 3 A report code.
Text string 255 Any descriptive text associated with the response. This is optional, may be left out or be blank and is subject to change without notice.
Units numeric 3 This shows the number of messages charged. Multipart messages & some binary messages may be sent as more then 1 message.

Response parameters

MessageIdentifier
A unique identifier for the message. You can use this to match against the message history and/or delivery receipts.
Report
A report code.
Text
Any descriptive text associated with the response. This is optional, may be left out or be blank and is subject to change without notice.
Units
This shows the number of messages charged. Multipart messages & some binary messages may be sent as more then 1 message.

Handling Report Codes

The full list is available from the report code pages.

There are a lot of different report codes listed, and you do not need to handle them all since many of them are never returned by API's. The full list is available from the report code pages, but for this API, the codes that you should definitely handle for a good client implementation are as follows. If using ResponseFormat=1 or ResponseFormat=3 you will get these codes:

Acceptance codes

-3, -2, 99

Error codes

-1, 2, 3, 5, 6, 7, 8, 11, 12, 13, 14, 15, 20, 76, 98

Examples

You can download free sample code in some of the most common programming languages to get you started and there are some content based examples below.

Sending a plain text SMS message

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 76

UserName=ANother.12345&PIN=123456&SendTo=447700912345,447700911223&Message=Connection%20Software&ResponseFormat=1&DeliveryServiceOption=Economy

Sending a flash SMS message

Flash messages appear on the screen of the mobile without the user having to select "read message". Flash messages are suitable for fast changing information that needs to visible immediately.

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 81

Username=ANOther.12345&PIN=123456&SendTo=447700912345&FlashMessage=Golf%20Course

Dealing with Errors

  • If you are unable to establish a TCP/IP connection with www.csoft.co.uk then it is vital that you automatically failover to www2.csoft.co.uk.
  • If you receive a response code indicating an error condition DO NOT automatically retry your request. For example if you are Out of Credit you will still be Out Credit. If you do enter a retry loop we may block your IP address as repeated retries may appear to us to be a Denial of Service attack.

Your session is about to expire

You will be logged out in seconds.

Do you want to stay signed in?

Yes, keep me signed in     No, Sign me out