sms POST method

=20

Send a text message to the specified recipient.

POST arguments

The following POST parameters should be used in a POST request.

=20

POST arguments
Concatenation
Supported Characters=
What is = the meaning of success or failure?

=20

Parameter	Value
message	The textual content of the message to be sent= . Up to 612 characters (see Concatenationbelow) from the GSM alphabet.= The SMS characters we can support are documented below. Please ensure that= data is also encoded in UTF-8.
to	The recipient (or recipients) you are sending= the message to. If you want to send to multiple numbers, use a comma delim= ited 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 di= splayed to the recipient, e.g. 447777123123 for a UK number.
email	Available to = txtUs Enterprise customers only. Specifes the email address fo= r incoming responses. If you specify an email address, you must specif= y an originator that is a txtUs Enterprise<= /a> number that is on your account, or you will get an error respo= nse.
validity	Optional. An integer from 1 to 72, indicating= the number of hours during which the message is valid for delivery. Messag= es which cannot be delivered within the specified time will fail.
custom	Optional. An alpha-numeric string, 1-20 chara= cters long, which will be used to 'tag' your outgoing message and will appe= ar in delivery reports, thus facilitating fltering of reports.
schedule	Optional. The date/time to schedule the messa= ge for sending. ISO 8601 format. Scheduled messages will not use any credit= s 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, fo= r authentication. Not required if you use HTTP Basic Authentication instead= .
password	The password of the source/master account, fo= r authentication. Not required if you use HTTP Basic Authentication instead= .
~~mobile_number~~	The mobile number of the intended recipien= t, in international format, e.g. 447777123123. Only one number is allowed. = To send a message to multiple recipients, you must call the API for each nu= mber. This parameter will be maintained for backwards compatibilit= y reasons. You should use the 'to' parameter.

=20

Concatenation

=20

If you exceed 160 characters you automatically invoke concatenation send= ing. This will mean that each message consists of a 153 character =E2=80=98= chunk=E2=80=99, i.e. no longer 160 characters.
The extra characters a= re used to 'glue' the messages together.
Therefore a message that is = 307 characters long will actually require 3 text messages to send (153 + 15= 3 + 1). Although it will appear as one long message to the recipient, it wi= ll use 3 credits to send.

=20

Supported Characters

=20

Please note we expect the data to be encoded in UTF-8 so for exa= mple à is C3 A0

See supported characters.

=20

What is the me= aning of success or failure?

=20

There is a diference between a successfully sent message, and a successf= ul delivery. Successfully sending a message using the API only means that t= he number and message appear to be in the correct format and that the messa= ge was queued for sending =E2=80=93 this does not mean that the destination= number exists, or that the message was received by the recipient.

=20

A delivery report =E2=80=93 which you can retrieve through the d= eliveryReport resource =E2=80=93 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. Therefor= e you may prefer to wait for 72 hours after sending an SMS before trying to= retrieve its delivery report.

=20

Example successful response bo= dy XML:

=20

<?xml version=3D"1.0" encoding=3D"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=3D"2011-04-14T12:01:01+01:00">
=09<message_id>1006486913</message_id>
=09<scheduled_id>0</scheduled_id>
=09<credits_used>1</credits_used>
=09<status>SENT</status>
</response>

=20

Response meanings:

XML tag/attribute	Meaning
message_id	The unique ID of the message sent. You can us= e 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 i= n the POST variables), the ID will be zero.
scheduled_id	The unique ID of the scheduled message. You c= an use this ID later to delete a previously scheduled message. Unless the m= essage has been scheduled for a future date, the ID will be zero.
credits_used	The number of credits used to send the messag= e. 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 SCHEDULE= D. Indicates whether the message was put in a queue for processing as soon = as resources allow (QUEUED), sent immediately (SENT), or scheduled for futu= re sending at your request (SCHEDULED).

=20

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 mess= age.
7	The message is invalid or missing.
8	The message contains unsupported characters (the= se will be listed in the error message).
9	The mobile numbers are invalid or too short.<= /p>
10	The mobile numbers are invalid or not an inte= ger.
11	The validity value is out of range.
12	The custom value is non-alphanumeric or out o= f range.
13	The mobile number is in a STOP group.
30	Invalid email address format.
31	An email address was specified, but the origi= nator specified was not a txtUs number on your account.
32	If specified, the validity period (in hours) mus= t be between 1 and 72 inclusive.
33	If specified, the custom feld must be alpha-nume= ric and up to 20 characters in length.
34	The 'schedule' parameter is not in ISO 8601 d= ate format.

=20

Example error response body XML:

=20

<?xml version=3D"1.0" encoding=3D"ISO-8859-1"?&=
gt;
<!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=3D"2011-04-14T12:11:27+01:00">
<errors>
=09<error code=3D"10">invalid number or not an integer</=
error>
=09<error code=3D"9">invalid number or too short</error&=
gt;
=09<error code=3D"7">invalid message or missing</error&g=
t;
=09<error code=3D"4">invalid originator or missing</erro=
r>
</errors>
</response>

=20

DTD for sms POST:

=20

<?xml version=3D"1.0" encoding=3D"UTF-8"?>
<!--
 =09PUBLIC ID : -//textmarketer.co.uk//DTD Web Services REST 1.6//EN
=09 SYSTEM ID : http://api.textmarketer.co.uk/services/rest/DTD/sms_post.dt=
d
-->
<!ELEMENT response (message_id, scheduled_id, credits_used, status)>
<!ATTLIST response
=09 processed_date CDATA #REQUIRED
>
<!ELEMENT message_id (#PCDATA)>
<!ELEMENT scheduled_id (#PCDATA)>
<!ELEMENT credits_used (#PCDATA)>
<!ELEMENT status (#PCDATA)>

=20