Bulk SMS API - SOAP to SMS Web Service

Simple Object Access Protocol (SOAP) is an XML-based protocol for the exchange of information in a decentralized, distributed environment. Because of SOAP's flexibility and extensibility it is well suited to the rapidly developing messaging market.

We offer an extensive and flexible SOAP API for sending SMS messages to mobile/cell phones around the world. The WSDL is available below and enables rapid integration using modern SOAP development toolkits like gSOAP and .NET.

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.

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

SOAP Servers
Primary http(s)://www.csoft.co.uk/sendsms5
Secondary http(s)://www2.csoft.co.uk/sendsms5

SOAP Servers

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

SOAP Request

Web Service Definition Language (WSDL)

The WSDL files are available at:

Element Descriptions

Use the SubmitMessage call for sending SMS messages as described below. You may also find the Available Credit and Available Messages calls of use. There may be other calls defined within the WSDL but these are not relevant when sending SMS.

We recommend that you only try to send one type of message in each SOAP request, but you can send that message to multiple recipients using the Recipient section. All the element names are case sensitive so "Data" is correct but "data" will not work. To aid readability a plus (+) prefix indicates a complex type, while the indenting and dash (-) prefix indicates an element in the sequence of elements that form part of that complex type. The + and - are not part of the element names, however.

Element Name Required Description
+ SubmitMessage Required Operation request element
   - Username Required An alphanumeric string with a maximum size of 20 characters e.g. "ANOther.61234".
   - PIN Required An alphanumeric string with a maximum size of 20 characters e.g. "123456".
   + Recipient Required This is a wrapper for all the information about the recipient.
      - SendTo Typically required

The number of the mobile phone to which the message should be sent. The number should be in full International Format, including the Country Code. For example 447700912345 for a UK mobile

The message can be sent to multiple recipients by separating each number with a comma e.g. 447700912345, 23412345678, 19145551234, 447700912346.

We suggest that you do not put more than 350 numbers in each request but you can submit as many requests as you need, in series or in parallel.

      - SendToAddressBook Optional

You can specify the name of your Contacts Manager 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

      + SendOptions Optional

These affect the way a message is delivered.

         - SendTimeAbsolute Optional

Specifies the exact date and time that you want the message to be sent. This must be in UTC (GMT) and is a maximum of seven days into the future.

         - SendTimeDelay Optional

Specifies the number of minutes that the message should be delayed. The value must be between 1 minute and 10080 minutes (seven days).

   + Message Required The Message element is essentially just a wrapper and you will need to define the type of message (TextMessage or FlashMessage).
      - TextMessage Either The message is a plain text message. Remember than <CR> and <LF> characters are counted if sent.
      - FlashMessage Either The message between the elements is sent as a flash message and is displayed immediately it is received on the phone. There is no need to press "read"
   - ReplyTo Optional If your account has been set up to change the ReplyTo shown with the message, then you can set it here. See the Two-way SMS page for details of how you can change this. Invalid entries here will be ignored.
   - MessageIdentifier Reserved This section is reserved for use by Connection Software and should be omitted or null.
   - Reserved Reserved This section is reserved for use by Connection Software and should be omitted or null.
+ SubmitMessage (required)
Operation request element
   - Username (required)
An alphanumeric string with a maximum size of 20 characters e.g. ANOther.61234. This is sent to you when you sign-up for the service.
   - PIN (required)
An alphanumeric string with a maximum size of 20 characters e.g. 123456. This is sent to you when you sign-up for the service.
   + Recipient (required)
This is a wrapper for all the information about the recipient.
      - SendTo (typically required)

The number of the mobile phone to which the message should be sent. The number should be in full International Format, including the Country Code. For example 447700912345 for a UK mobile

The message can be sent to multiple recipients by separating each number with a comma e.g. 447700912345, 23412345678, 19145551234, 447700912346.

We suggest that you do not put more than 350 numbers in each request but you can submit as many requests as you need, in series or in parallel.

      - 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

      + SendOptions (optional)
These affect the way a message is delivered.
         - SendTimeAbsolute (optional)
Specifies the exact date and time that you want the message to be sent. This must be in UTC (GMT) and is a maximum of seven days into the future.
         - SendTimeDelay (optional)

Specifies the number of minutes that the message should be delayed. The value must be between 1 minute and 10080 minutes (seven days).

   + Message (required)
The Message element is essentially just a wrapper and you will need to define the type of message (TextMessage or FlashMessage).
      - TextMessage (either)
The message is a plain text message. Remember than <CR> and <LF> characters are counted if sent.
      - FlashMessage (either)
The message between the elements is sent as a flash message and is displayed immediately it is received on the phone. There is no need to press "read"
   - ReplyTo (optional)
If your account has been set up to change the ReplyTo shown with the message, then you can set it here. See two-way for details of how you can change this. Invalid entries here will be ignored.
   - MessageIdentifier (reserved)
This section is reserved for use by Connection Software and should be omitted or null.
   - Reserved (reserved)
This section is reserved for use by Connection Software and should be omitted or null.

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

Character Encoding

We fully support sending messages in any international language (Chinese, Hebrew, Russian, etc.) using the UTF-8 encoding standard. SOAP toolkits typically use the UTF-8 character set by default, so it is unlikely that you need to do anything special in order to send messages in almost any language. If you do experience problems, such as garbled messages, then ensure the handset can display such messages and that the character set in the HTTP POST header and the XML encoding tag are both set to UTF-8 (see the examples below).

SOAP Response

Responses will contain the following elements.

Element Name Required Description
+ SubmitMessageResponse Required Operation response element
   - MessageIdentifier Required A unique alphanumeric string of up to 31 characters that can be used to track each message in the server logs and in the real-time delivery receipts (if enabled). If you submit multiple numbers in the SendTo tag, this will be a comma separated list of id's in the same order as the submitted numbers.
   - Report Required The numeric report code. If you submit multiple numbers in the SendTo tag, this will be a comma separated list of codes in the same order as the submitted numbers.
   - Text Optional A description of the Report designed to provide more information to help in debugging. This may be blank. If you submit multiple numbers in the SendTo tag, this will be a comma separated list of descriptions in the same order as the submitted numbers.
   - Reserved Reserved This whole section is reserved for use by Connection Software and should be ignored when parsing responses.
+ SubmitMessageResponse (required)
Operation response element
   - MessageIdentifier (required)
A unique alphanumeric string of up to 31 characters that can be used to track each message in the server logs and in the real-time delivery receipts (if enabled). If you submit multiple numbers in the SendTo tag, this will be a comma separated list of id's in the same order as the submitted numbers.
   - Report (required)
The numeric report code. If you submit multiple numbers in the SendTo tag, this will be a comma separated list of codes in the same order as the submitted numbers.
   - Text (optional)
A description of the Report designed to provide more information to help in debugging. This may be blank. If you submit multiple numbers in the SendTo tag, this will be a comma separated list of descriptions in the same order as the submitted numbers.
   - Reserved (reserved)
This whole section is reserved for use by Connection Software and should be ignored when parsing responses.

Handling Report Codes

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. You can see the full list of report codes on our Report Codes page. However as a general principle for this API the codes that you should handle for a good client implementation are as follows:

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

Compatibility

The current interface has been validated in-house against gSOAP and Microsoft VB/VC++/VC# .NET for compatibility but many of our clients have reported it working equally well with other languages that support developing SOAP clients.

Sample applications for sending SMS using Microsoft Visual C#, C++ and Visual Basic .NET are available in the sample code section.

.NET

To use the service from a Visual Studio .NET application you need to build a proxy class from our web service definition file (WSDL). Open the project you want add SMS functionality to - this can be an ASP.NET page or a stand-alone Windows form-based application. Right-click on the References folder in the Solution Explorer and choose "Add Web Reference". Type the address for the WSDL file and press Enter. This will download the Web service definition from our server. To create a proxy class for this Web service, simply click the Add Reference button. Then simply instantiate the class and call the method SubmitMessage with the values described above to begin sending SMS.

Unable to generate a temporary class (result=1). error CS0030: Cannot convert type 'csoft.item[]' to 'csoft.item'

If you experience this known .NET issue you need to edit the auto-generated CSoftSmsService.cs file and change public item[][] info to public item[] info. See either the C# sample code for an example solution and the Microsoft issue that relates to this problem. Note that while the issue refers to Biz Talk it is a known issue with .NET also.

Case Sensitivity

All element names in SOAP are case sensitive. It has been reported that some toolkits do not honour this.

Example SOAP Requests

These examples have been formatted for display purposes and so may contain invalid whitespace.

Plain Text Message

To send a plain text message you will need to include at least the Username, PIN, Recipient, and TextMessage elements in your SOAP packet. Remember that SOAP uses the UTF-8 encoding by default so all message text must be encoded as UTF-8. This is especially important for international character sets.

<?xml version="1.0" encoding="UTF-8"?>
< SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
    <SOAP-ENV:Body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <ns2:SubmitMessage>
    <Username xsi:type="xsd:string">Another.12345</Username>
    <PIN xsi:type="xsd:string">123456</PIN>
    <Recipient xsi:type="ns2:Recipient">
        <SendTo xsi:type="xsd:string">447700912345,447700911223</SendTo>
    </Recipient>
    <Message xsi:type="ns2:Message">
        <TextMessage xsi:type="xsd:string">test message</TextMessage>
    </Message>
</ns2:SubmitMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example SOAP Responses

These examples have been formatted for display purposes and so may contain invalid whitespace.

Success response

HTTP/1.1 200 OK
Date: Wed, 18 Jun 2003 09:06:54 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.12 OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Content-Length: 899
Connection: close
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
         xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
         xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/1999/XMLSchema"
         xmlns:ns1="http://www.csoft.co.uk/dtd/sendsms2.xsd"
         xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitMessageResponse xsi:type="ns2:SubmitMessageResponse">
<MessageIdentifier xsi:type="xsd:string">302B461B,302B461C</MessageIdentifier>
<Report xsi:type="xsd:int">99,99</Report>
<Text xsi:type="xsd:string">Test message succeeded,Test message succeeded</Text>
<Reserved xsi:type="ns2:Reserved">
<Field1 xsi:type="xsd:string">&#3;</Field1>
</Reserved></ns2:SubmitMessageResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The report code -2 indicates that the message has been received by Connection Software for processing. See the Report Codes page for more details. Codes.

Failure response

HTTP/1.1 200 OK
Date: Wed, 18 Jun 2003 09:12:15 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.12 OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Content-Length: 855
Content-Type: text/xml; charset=utf-8

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
         xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
         xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
         xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
         xmlns:xsd="http://www.w3.org/1999/XMLSchema"
         xmlns:ns1="http://www.csoft.co.uk/dtd/sendsms2.xsd"
         xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitMessageResponse xsi:type="ns2:SubmitMessageResponse">
<MessageIdentifier xsi:type="xsd:string">302B4645,302B4646</MessageIdentifier>
<Report xsi:type="xsd:int">2,2</Report>
<Text xsi:type="xsd:string">For more detailed information on this Report number, please visit www.csoft.co.uk</Text>
<Reserved xsi:type="ns2:Reserved"></Reserved>
</ns2:SubmitMessageResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The report code 2 indicates an invalid login. See the Report Codes page for more details.

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