| Parameter | Value |
|---|---|
| message | The textual content of the message to be sent. |
| to | The recipient (or recipients) you are sending the message to. If you want to send to multiple numbers, use a comma delimited list. Try to include the international code, for example 44 in the UK. |
| originator | A string (up to 11 alpha-numeric characters) or an international mobile number (up to 16 digits) of the sender, to be displayed to the recipient, e.g. 447777123123 for a UK number. |
Available to txtUs Enterprise customers only. Specifes the email address for incoming responses. | |
| validity | Optional. An integer from 1 to 72, indicating the number of hours during which the message is valid for delivery. Messages which cannot be delivered within the specified time will fail. |
| custom | Optional. An alpha-numeric string, 1-20 characters long, which will be used to 'tag' your outgoing message and will appear in delivery reports, thus facilitating fltering of reports. |
| schedule | Optional. The date/time to schedule the message for sending. ISO 8601 format. Scheduled messages will not use any credits until sent, however the API response will indicate the number of credits that will be used when the message is sent. |
| check_stop | If set to 'true', prior to sending the number(s) will checked against the STOP group. |
| username | The username of the source/master account, for authentication. Not required if you use HTTP Basic Authentication instead. |
| password | The password of the source/master account, for authentication. Not required if you use HTTP Basic Authentication instead. |
|
Concatenation
If you exceed 160 characters you automatically invoke concatenation sending. This will mean that each message consists of a 153 character ‘chunk’, i.e. no longer 160 characters.
The extra characters are used to 'glue' the messages together.
Therefore a message that is 307 characters long will actually require 3 text messages to send (153 + 153 + 1). Although it will appear as one long message to the recipient, it will use 3 credits to send.
Supported Characters
Please note we expect the data to be encoded in UTF-8 so for example à is C3 A0
See supported characters.
What is the meaning of success or failure?
There is a diference between a successfully sent message, and a successful delivery. Successfully sending a message using the API only means that the number and message appear to be in the correct format and that the message was queued for sending – this does not mean that the destination number exists, or that the message was received by the recipient.
A delivery report – which you can retrieve through the deliveryReport resource – confrms to you what has actually happened to the message. This may change over time, e.g. a delivery report may show a 'PENDING' status for a message 10 minutes after the message was sent, but may show a 'DELIVERED' status after an hour.
The status of messages can change for up to 72 hours after the message was sent. Therefore you may prefer to wait for 72 hours after sending an SMS before trying to retrieve its delivery report.
Example successful response body XML:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE response PUBLIC
"-//textmarketer.co.uk//DTD Web Services REST 1.6//EN"
"http://api.textmarketer.co.uk/services/rest/DTD/sms_post.dtd">
<response processed_date="2011-04-14T12:01:01+01:00">
<message_id>1006486913</message_id>
<scheduled_id>0</scheduled_id>
<credits_used>1</credits_used>
<status>SENT</status>
</response> |
Response meanings:
| XML tag/attribute | Meaning |
|---|---|
| message_id | The unique ID of the message sent. You can use this ID to fnd the status of the sent message in the delivery report. For SCHEDULED messages (i.e. where you have specified a 'schedule' parameter in the POST variables), the ID will be zero. |
| scheduled_id | The unique ID of the scheduled message. You can use this ID later to delete a previously scheduled message. Unless the message has been scheduled for a future date, the ID will be zero. |
| credits_used | The number of credits used to send the message. If the message is scheduled for future sending, this value indicates how many credits will be used when it is sent. |
| status | Values possible are SENT, QUEUED, or SCHEDULED. Indicates whether the message was put in a queue for processing as soon as resources allow (QUEUED), sent immediately (SENT), or scheduled for future sending at your request (SCHEDULED). |
Specific errors:
| Code | Meaning |
|---|---|
| 1 | Bad username or password. |
| 2 | You have zero credits. |
| 3 | The originator is invalid or too long. |
| 4 | The originator is invalid or missing. |
| 5 | The message is invalid or too long. |
| 6 | You have insufcient credits to send this message. |
| 7 | The message is invalid or missing. |
| 8 | The message contains unsupported characters (these will be listed in the error message). |
| 9 | The mobile numbers are invalid or too short. |
| 10 | The mobile numbers are invalid or not an integer. |
| 11 | The validity value is out of range. |
| 12 | The custom value is non-alphanumeric or out of range. |
| 13 | The mobile number is in a STOP group. |
| 30 | Invalid email address format. |
| 31 | An email address was specified, but the originator specified was not a txtUs number on your account. |
| 32 | If specified, the validity period (in hours) must be between 1 and 72 inclusive. |
| 33 | If specified, the custom feld must be alpha-numeric and up to 20 characters in length. |
| 34 | The 'schedule' parameter is not in ISO 8601 date format. |
Example error response body XML:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE response PUBLIC
"-//textmarketer.co.uk//DTD Web Services REST 1.6//EN"
"http://api.textmarketer.co.uk/services/rest/DTD/errors.dtd">
<response processed_date="2011-04-14T12:11:27+01:00">
<errors>
<error code="10">invalid number or not an integer</error>
<error code="9">invalid number or too short</error>
<error code="7">invalid message or missing</error>
<error code="4">invalid originator or missing</error>
</errors>
</response>
|
DTD for sms POST:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<?xml version="1.0" encoding="UTF-8"?>
<!--
PUBLIC ID : -//textmarketer.co.uk//DTD Web Services REST 1.6//EN
SYSTEM ID : http://api.textmarketer.co.uk/services/rest/DTD/sms_post.dtd
-->
<!ELEMENT response (message_id, scheduled_id, credits_used, status)>
<!ATTLIST response
processed_date CDATA #REQUIRED
>
<!ELEMENT message_id (#PCDATA)>
<!ELEMENT scheduled_id (#PCDATA)>
<!ELEMENT credits_used (#PCDATA)>
<!ELEMENT status (#PCDATA)>
|