Home Knowledge Base Developer Zone XML API Documentation

XML API Documentation

in Developer Zone Tags: api, error codes, xml

To download our DTD files click here
Jump to Section

XML API Version 1.0

The XML API allows you to perform various actions such as sending and receiving messages, credit information and contacts.

A valid XML API request consists of an authentication section followed by as many other sections as required in any order. For example, in one API request, you could send one message to three recipients, another message to another recipient, check your inbound messages and add a contact.

The XML Document should be posted uriencoded, with a UTF-8 character set as parameter ‘xml’ to https://my.fastsms.co.uk/xmlapi

Test form

You can enter plain text in here and the request will be run on the server, with the resultant XML posted to the screen.

If an error occurs, you will be returned details of the error. For an example, see the failed login example response below. For a full list of status codes and meanings, click here

Important Note:This is an interface to the real API, so if you paste in valid XML to send a message, it will be sent to the phone.

Authentication with token

Request

Element Type Description
apirequest Array Container for your request
user Array Container for user related details
token Alphanumeric Used to authorize your application at FastSMS server. Required for every API call you make. You can get your token on account settings page:https://my.fastsms.co.uk/account/settings. Please note that token is updated when you change password for your FastSMS account.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
	<user>
		<token>[alphanumeric]</token>
	</user>
</apirequest>

Response

Element Description
apiresponse Container for NetMessenger response
userresponse Container for user related details
status Possible values for status are: loggedin, rejected, failed.
loggedin– access credentials are valid, your request was handled successfully.
rejected– Unknown user or password, or user has been suspended
failed– An error occurred retrieving the user details
userid Your user ID within NetMesenger
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>12203</userid>
	</userresponse>
</apiresponse>

Authentication with username and password

Request

Element Type Description
apirequest Array Container for your request
user Array Container for user related details
username Alphanumeric Your user name. Used to authorize your application at FastSMS server. Required for every API call you make.
password Alphanumeric Your password. Used to authorize your application at FastSMS server. Required for every API call you make.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
	<user>
		<username>[alphanumeric]</username>
		<password>[alphanumeric]</password>
	</user>
</apirequest>

Response

Element Description
apiresponse Container for NetMessenger response
userresponse Container for user related details
status Possible values for status are: loggedin, rejected, failed.
loggedin– access credentials are valid, your request was handled successfully.
rejected– Unknown user or password, or user has been suspended
failed– An error occurred retrieving the user details
userid Your user ID within NetMesenger
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>12203</userid>
	</userresponse>
</apiresponse>

Application

Request

Element Type Description
application Array Container for application related details
name Alphanumeric A name of your application. Optional element.
version Alphanumeric A version of your application. Optional element.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
	<application>
		<name>[alphanumeric]</name>
		<version>[alphanumeric]</version>
	</application>
</apirequest>

Response

No response is given.

Working with Messages

Checking Your Credit Level

Request

Element Type Description
creditcheck Empty element Include an empty creditcheck element to request your current credit level from NetMessenger. Do not include any value or attribute into this element.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<creditcheck />
</apirequest>

Response

Element Type Description
creditcheckresponse Decimal digit Current credit level of your NetMessenger account.
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
	</userresponse>
 
	<creditcheckresponse>173.69</creditcheckresponse>
 
</apiresponse>

Sending a message

Request

Element Type Description
sendsms Array Container of message sending request. May have a “batch” numeric attribute, which is not stored in the system, but simply used as a method in which to differentiate responses.
source Alphanumeric Will appear on mobile phones as “from” name. In example, it can be a name of your company.
destinations Array Container for message destinations. Destinations are your sending targets. They can be one of three types: mobile number, contact and distribution list. You should provide at least one destination for your message.
destination Number Use this element to specify a mobile number you want to send to. Number should be in international format, but without “+” symbol in the beginning. For the UK, mobile number starting with 077 will work as well. Example of Russia-based mobile number in international format: 79221094234.

Element may have a ref optional alphanumeric attribute, which may be used to tie a response with your request.
contact Numeric, ID Use this element to send to a contact with known ID from your contact list. Contact list is available here: https://my.fastsms.co.uk/contacts.

Element may have a ref optional alphanumeric attribute, which may be used to tie a response with your request.
list Numeric, ID Use this element to send bulk messages to your marketing lists. Note: distribution list you try to send to should exist in the NetMessenger (so you have its ID). Also, make sure your list is not empty: your message should have actual targets to go to.

Element may have a ref optional alphanumeric attribute, which may be used to tie a response with your request.
message Alphanumeric The body of your message. Required element. Alphanumeric string. Max length for the message body is 456 characters. Message body that is longer than 160 symbols, will be split into several messages on the NetMessenger’s side.
sourceton

 

 Number Source Type Of Number (optional element) – Specify the Type of Number for the source address. Only fill in this field if you know what a source TON is.
schedulefor XML date/time The date that the message should be sent (in Standard XML format, Lexical representation)
udh UDH User Data Header for the message (optional element). Only fill this in if you know that the UDH for your message is.
dcs DCS Data Coding Scheme for the message (optional element). Only fill this in if you know that the DCS for your message is.
validityperiod Numeric, seconds The period in seconds that the message will be tried for (maximum 86400 = 24 hours). Once this expires, the message will no longer be attempted to be delivered.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<sendsms batch="[numeric]">
		<source>[alphanumeric]</source>
 
		<destinations>
			<destination ref="[alphanumeric]">[number]</destination>
			<contact ref="[alphanumeric]">[ID]</contact>
			<list ref="[alphanumeric]">[ID]</list>
			<!-- ... (at least one and as many of the above three as required) -->
		</destinations>
 
		<message>[alphanumeric]</message>
 
		<!-- Optional parameters -->
 
		<sourceton>[number]</sourceton>
 
		<schedulefor>[time/date]</schedulefor>
 
		<udh>[UDH]</udh>
		<dcs>[DCS]</dcs>
		<validityperiod>[numeric, seconds]</validityperiod>
 
	</sendsms>
</apirequest>

Response

Element Type Description
smsresponse Array Container of message sending response. May have a “batch” numeric attribute, which is not stored in the system, but simply used as a method in which to differentiate responses.
destination Array Container for info about message you have sent a request for. Has a “number” attribute, when your send was successful. Actual number depends on what you had in your request (see request description above).

  • When you send to “destination” (raw mobile number), you just get it back in response.
  • When you send to “contact”, you get mobile number of that contact, as it is in your contact list.
  • When you send to distribution list, you get a mobile number of the last list entry.

This element also may have a “ref” attribute (if you’ve used it in your request), which is not stored in NetMessenger, but passed back in the response for your convenience, so you could be able to tie it with your request.
messageid Numeric, ID ID of the message you sent at NetMessenger. If your message 160 characters or shorter, you will get back one messageid item with part parameter set to “1”. Otherwise you may get several messageid items. Each of them will have numeric incremental part parameter, and will have different message ID values.

Message IDs are different, because long message is broken at NetMessenger into several 160-character pieces (parts), and each part considered as a separate sms message. Anyhow, the response contains the whole array of IDs – for your convenience.
status Alphanumeric Status of your message at NetMessenger by the moment of response.
error Array Container for the info about error, when your send was unsuccessful.
code Numeric Code of the error occurred while send attempt. For the whole error code list refer this list
message Alphanumeric Brief text of error description
Example Response

In this example, a message was sent to one number, two contacts and two distribution lists.
Note that when sending to a distribution list, the Number and Message ID for the last message in the list is returned.

<?xml version="1.0" encoding="UTF-8"?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<smsresponse batch="1">
 
		<destination number="447777777778" ref="dest1">
			<messageid part="1">18003466</messageid>
			<status>sent</status>
		</destination>
 
		<destination ref="contact1">
			<error>
				<code>-200</code>
				<message> Invalid Contact</message>
			</error>
		</destination>
 
		<destination number="447777777779" ref="contact2">
			<messageid part="1">18003467</messageid>
			<messageid part="2">18003468</messageid>
			<status>sent</status>
		</destination>
 
		<destination ref="list1">
			<error>
				<code>-408</code>
				<message>Distribution List is Empty</message>
			</error>
		</destination>
 
		<destination number="447777777776" ref="list2">
			<messageid part="1">18003469</messageid>
			<messageid part="2">18003470 </messageid>
			<status>sent</status>
		</destination>
	</smsresponse>
 
</apiresponse>

Checking the Status of a Message

Request

Element Type Description
messagestatuscheck Array Container for array of message ID elements (messageid).
messageid Numeric, ID Numeric value, at least one element is required. Should be ID of the message you want to check a status for.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<messagestatuscheck>
		<messageid>[numeric]</messageid>
		<messageid>[numeric]</messageid>
	</messagestatuscheck>
 
</apirequest>

Response

Element Type Description
messagestatuscheckresponse Array Container for the message status check response.
message Array Container for message details, 1 per each message you requested status info for.
messageid Numeric ID of the message, as it was in your request.
status Alphanumeric Status value, returned by NetMessenger for that message ID.
Message statuses available are listed here.
Example Response
<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
	</userresponse>
 
	<messagestatuscheckresponse>
		<message>
			<messageid>2</messageid>
			<status>Unknown Message ID</status>
		</message>
		<message>
			<messageid>18003448</messageid>
			<status>DELIVERED</status>
		</message>
	</messagestatuscheckresponse>
</apiresponse>

Working with Contacts

Retrieve all contacts

Request

Element Type Description
retrieveallcontacts Empty element with attribute Include an empty retrieveallcontacts element to request a full list of your contacts stored in the NetMessenger. Do not include any value into this element. This element should have a mode attribute, value of such an attribute can be “id” or “full”. If set to “id”, you’ll get a list of IDs for all the contacts stored in the NetMessenger (faster option). If you set mode attribute to “full”, response will contain full contact list, where you’ll get ID, name, mobile number and email for each contact in the list.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<contacts>
		<retrieveallcontacts mode="[id|full]" />
	</contacts>
 
</apirequest>

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the contact details, including ID, name, mobile number and email.
contactid Numeric, ID ID of the contact record.
name Alphanumeric Contact name, as it’s stored in the NetMessenger. Provided only if your request had retrieveallcontacts element with mode attribute set to “full”.
number Numeric, mobile number Contact mobile number in the international format, as it’s stored in the NetMessenger.

Provided only if your request had retrieveallcontacts element with mode attribute set to “full”.
email Valid email Contact email, as it’s stored in the NetMessenger.

Provided only if your request had retrieveallcontacts element with mode attribute set to “full”.
Example Response

In this example, all contacts were requested in id mode.

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
	</userresponse>
 
	<contactsresponse>
		<contact>
			<contactid>49445</contactid>
		</contact>
		<contact>
			<contactid>49455</contactid>
		</contact>
	</contactsresponse>
 
</apiresponse>

Retrieve a specific contact

Request

Element Type Description
contacts Array Container for the list of contacts you want to retrieve.
contact Array Container for the request details for the specific contact you want to retrieve. To get a contact from NetMessenger you should add “action” attribute to this element, with value set to “retrieve”. You also can add optional alphanumeric “ref” attribute, if you want to tie you request to NetMessenger’s response.

Also, please note that you should include at least one child element: contactid or number, whichever suits you better.
contactid ID, numeric Use this element to pass ID of the contact you want to get details for.
number Alphanumeric Use this element to pass a mobile number of the contact you want to get full details for. Number should be in international format, without “+” character in the beginning. For the UK, numbers starting with 077 will work as well. Example: 79221094234 (Russia-based number).
Example Request

If you want to retrieve a contact by ID:

<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<contacts>
		<!-- the ref is used to tie the response to the request only, not stored -->
		<contact action="retrieve" ref="retr_contact1">
			<contactid>264</contactid>
		</contact>
		<!-- … -->
	</contacts>
 
</apirequest>

If you want to retrieve a contact by mobile number:

<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<contacts>
		<!-- the ref is used to tie the response to the request only, not stored -->
		<contact action="retrieve" ref="retr_contact1">
			<number>447777777777</number>
		</contact>
		<!-- … -->
	</contacts>
 
</apirequest>

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the contact details, including ID, name, mobile number and email.
contactid Numeric, ID ID of the contact record.
name Alphanumeric Contact name, as it’s stored in the NetMessenger
number Numeric, mobile number Contact mobile number, as it’s stored in the NetMessenger
email Valid email Contact email, as it’s stored in the NetMessenger
Example Response
<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<contactsresponse>
 
		<contact ref="retr_contact1">
			<contactid>49450</contactid>
			<name>Fred</name>
			<number>447777777777</number>
			<email></email>
		</contact>
 
	</contactsresponse>
 
</apiresponse>

Create a contact

Request

Element Type Description
contacts Array Container for the list of contacts you want to create.
contact Array Container for the request details for the specific contact you want to create. To create a contact at NetMessenger you should add “action” attribute to this element, with value set to “create”. You also can add optional alphanumeric “ref” attribute, if you want to tie you request to NetMessenger’s response.
name Alphanumeric Use this element to pass a name of the contact you want to create.
number Numeric, mobile number Use this element to pass a mobile number of the contact you want to create. Number should be in international format, without “+” character in the beginning. For the UK, numbers starting with 077 will work as well. Example: 79221094234 (Russia-based number).
email Valid email Valid email address for the contact you want to create.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<contacts>
 
		<!-- the ref is used to tie the response to the request only, not stored -->
		<contact action="create" ref="create_contact1">
			<name>[alphanumeric, only for create or edit]</name>
			<number>[alphanumeric for create or edit, optional for retrieve]</number>
			<email>[alphanumeric, only for create or edit]</email>
		</contact>
		<!-- … -->
	</contacts>
 
</apirequest>

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the contact details, including ID, name, mobile number and email.
contactid Numeric, ID ID of the new contact record. This ID is assigned by NetMessenger automatically upon creation.
error Alphanumeric If an error occurs during processing your request, response will contain this element. Value of this element will be a brief text description of the error.
Example Response

If contact was added successfully:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<contactsresponse>
 
		<contact ref="create_contact1">
			<contactid>49450</contactid>
		</contact>
	</contactsresponse>
 
</apiresponse>

If there was an error:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
	</userresponse>
 
	<contactsresponse>
		<contact ref="create_contact1">
			<error>One or more fields are invalid</error>
		</contact>
	</contactsresponse>
 
</apiresponse>

Edit contact

Request

Element Type Description
contacts Array Container for the list of contacts you want to create.
contact Array Container for the request details for the specific contact you want to create. To create a contact at NetMessenger you should add “action” attribute to this element, with value set to “edit”. You also can add optional alphanumeric “ref” attribute, if you want to tie you request to NetMessenger’s response.
contactid Numeric, ID Use this element to pass an ID of the contact record you want to update.
name Alphanumeric Use this element to pass a new name of the contact you want to update.
number Numeric, mobile number Use this element to pass a new mobile number of the contact you want to update. Number should be in international format, without “+” character in the beginning. For the UK, numbers starting with 077 will work as well. Example: 79221094234 (Russia-based number).
email Valid email New valid email address for the contact you want to update.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<contacts>
 
		<!-- the ref is used to tie the response to the request only, not stored -->
		<contact action="edit" ref="edit_contact1">
			<contactid>542</contactid>
			<name>John Smith</name>
			<number>447777777777</number>
			<email></email>
		</contact>
		<!-- … -->
	</contacts>
 
</apirequest>

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the specific contact details, including ID, name, mobile number and email.
status Alphanumeric If your edit request was processed successfully, you will get this element with value set to “Saved”.
error Alphanumeric If an error occurs during processing your request, response will contain this element. Value of this element will be a brief text description of the error.
Example Response

If the record was updated successfully:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<contactsresponse>
		<contact ref="edit_contact1">
			<status>Saved</status>
		</contact>
	</contactsresponse>
 
</apiresponse>

If there was an error:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<contactsresponse>
		<contact ref="edit_contact1">
			<error>One or more fields are invalid</error>
		</contact>
	</contactsresponse>
 
</apiresponse>

Delete all contacts

Use this method with care! When it’s processed successfully, it wipes out all your contacts from the NetMessenger’s database.

Request

Element Type Description
contacts Array Container for the action requested. Usually there will be a contact list, but for this method, you should just include one child element – deleteallcontacts
deleteallcontacts Empty element Include this element into your request when you want to delete all the contacts you have in the NetMessenger’s database. Do not include any attribute or value into this element.
Please note: contacts will be deleted permanently.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<contacts>
		<deleteallcontacts />
	</contacts>
 
</apirequest>

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
deleteallcontacts Array Container for response details specific for deleteallcontacts request. Has child elements, which may be status, number of contacts deleted and/or error details.
status Alphanumeric Resulting status of your request. Can be one of the following:
“DELETED” (if you had contacts and they were deleted successfully)
“NO CONTACTS TO DELETE” (if you had no contacts to delete)

“ERROR”, if your request triggered an error while processing.
When status is an “ERROR”, NetMessenger adds to response an error element with error code and description as child elements.
contactdeletetotal Numeric Total number of contacts you have just deleted. If the status element (see above) will be “NO CONTACTS TO DELETE” or “ERROR”, you will get zero here.
error Array When your request was handled with an error, you will get error details in this element.
code Numeric Code of the error occurred. Refer to this list for all error codes.
message Alphanumeric Brief description of the error occurred.
Example Response

If you deleted all the contacts successfully:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<contactsresponse>
		<deleteallcontacts>
			<status>DELETED</status>
			<contactdeletetotal>8</contactdeletetotal>
		</deleteallcontacts>
	</contactsresponse>
 
</apiresponse>

If you have no contacts to delete:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<contactsresponse>
		<deleteallcontacts>
			<status>NO CONTACTS TO DELETE</status>
			<contactdeletetotal>0</contactdeletetotal>
		</deleteallcontacts>
	</contactsresponse>
 
</apiresponse>

If there was an error:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<contactsresponse>
		<deleteallcontacts>
			<status>ERROR</status>
			<contactdeletetotal>0</contactdeletetotal>
			<error>
				<code>-300</code>
				<message>DB Error</message>
			</error>
		</deleteallcontacts>
	</contactsresponse>
 
</apiresponse>

Inbound Numbers and SMS Templates

Get a List of Inbound Numbers

Request

Element Type Description
getinboundnumbers Empty element Send this element with your request to get a list of all inbound numbers existing in your account at NetMessenger. Do not include any attributes or child elements.

Note: you should purchase inbound numbers via NetMessenger interface first to use this method.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<getinboundnumbers />
 
</apirequest>

Response

Element Type Description
getinboundnumbersresponse Array Container for the inbound number list.
msisdn Array Container for response details about specific inbound number.
id Numeric, ID ID of the specific inbound number
number Numeric, mobile number Number in the international format, without “+” sign in the beginning. I.e.: 447777777777
Example Response
<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<getinboundnumbersresponse>
		<msisdn>
			<id>142</id>
			<number>447777777777</number>
		</msisdn>
		<msisdn>
			<id>356</id>
			<number>447777777778</number>
		</msisdn>
	</getinboundnumbersresponse>
</apiresponse>

Check for Inbound Messages

Request

Element Type Description
inboundcheck Empty element with attributes Send this element with your request to get inbound messages stored in the NetMessenger’s database. You can use two attributes in this element:
lastid (numeric) – ID of the message you want to use as a starting point for response. In this case NetMessenger will respond with the list of messages with IDs which were received later the message you’ve specified.

from (xml date/time) –  a date you want to use as a starting point for response. NetMessenger will provide a list of messages which were received after this date/time.

Date format: YYYY-MM-DDTHH:MM:SS+/-TZ:TZ example: 2009-05-09T13:23:50+01:00 (more about format).

If this date will not be specified, NetMessenger will use a span of the last 7 days by default.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<inboundcheck lastid="345" from="2009-05-09T13:23:50+01:0"/>
 
</apirequest>

Response

Element Type Description
inboundcheckresponse Array Container for the response part with details about inbound messages.
sms Array Container for the details about specific inbound message.
messageid Numeric, ID ID of the specific inbound message
source Numeric, mobile number Source of the specific inbound message. A mobile number this specific message was sent from, in international format.
destination Numeric, mobile number Target number for the specific message. This is one of your MSISDNs (inbound numbers), in international format.
Example Response
<?xml version="1.0" encoding="UTF-8"?>
<apiresponse>
  <userresponse>
    <status>loggedin</status>
    <userid>4</userid>
  </userresponse>
  <inboundcheckresponse>
    <sms>
      <messageid>23464567567</messageid>
      <source>
      447777777777
      </source>
      <destination>447777777778</destination>
      <receivedtime>2009-05-09T13:23:50+00:00</receivedtime>
      <body>
      This is an example message
      </body>
    </sms>
    <sms>
      <messageid>34574574</messageid>
      <source>
      447777777777
      </source>
      <destination>447777777778</destination>
      <receivedtime>2009-05-09T13:27:17+00:00</receivedtime>
      <body>
      This is another example message
      </body>
    </sms>
  </inboundcheckresponse>
</apiresponse>

Get the Templates from NetMessenger

Request

Element Type Description
getsmstemplates Empty element with attribute Use this element to request a list of your sms templates stored in the NetMessenger. Include the lastid numeric parameter to specify which template you want response to start with. Do not include any child elements here.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<getsmstemplates lastid="1192" />
 
</apirequest>

Response

Element Type Description
getsmstemplatesresponse Array A container for the part of the response with sms template list.
template Array A container for the part of the response with details about specific sms template
templateid Numeric, ID ID of the specific sms template
name Alphanumeric Name of the specific sms template.
body Alphanumeric Body of the specific sms template. Max length of the body is 456 characters. Note: is the body is longer than 160 symbols, it will produce up to 3 actual messages (160 symbols or less per each).
Example Response
<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
  <userresponse>
    <status>loggedin</status>
    <userid>4</userid>
  </userresponse>
  <getsmstemplatesresponse>
    <template>
      <templateid>1192</templateid>
      <name>template 1</name>
      <body>
      This is an SMS Template
      </body>
    </template>
    <template>
      <templateid>1193</templateid>
      <name>Renewal Reminder</name>
      <body>
      Dear #Name#, your account is due for renewal in the next 7 days
      </body>
    </template>
  </getsmstemplatesresponse>
</apiresponse>

Working with Distribution lists

Retrieve all Distribution Lists

Request

Element Type Description
retrievealllists Empty element Use this element to request the set of your distribution lists stored in the NetMessenger. Response will include IDs and titles of your distribution lists. Do not include any child elements here.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<retrievealllists />
	</distributionlists>
 
</apirequest>

Response

Element Type Description
distributionlistsresponse Array A container for the part of the response with details of your distribution lists.
distributionlist Array Container for the details on the specific distribution list.
listid Numeric, ID ID of the specific distribution list. You can use it for further list entries request.
title Alphanumeric Title of the specific distribution list.
Example Response
<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
		<distributionlist>
			<listid>1693</listid>
			<title>Footy Team</title>
		</distributionlist>
		<distributionlist>
			<listid>1692</listid>
			<title>My Phones</title>
		</distributionlist>
	</distributionlistsresponse>
 
</apiresponse>

Get Details of Specific Distribution List

Request

Element Type Description
getdetails Empty element with attribute Use this element to request list details and entries for the specific distribution list. Include listid numeric parameter to specify an ID of the list you want to retrieve. Do not include any child elements here.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<getdetails listid="1693" />
	</distributionlists>
 
</apirequest>

Response

Element Type Description
distributionlist Array Container for the response part with list details and list entries you requested for.
listid Numeric, ID ID of the list you requested.
title Alphanumeric Title of the list you requested.
entries Array Container for the array of the list entries.
entry Array Container for the details of the specific entry.
entryid Numeric, ID ID of the specific entry record
number Numeric, mobile number Mobile number of the specific list entry, should be in the international format without “+” symbol in the beginning, i.e.: 447777777777
name Alphanumeric Name of the specific list entry. I.e., this could be a person name.
email Valid email A valid email address for the specific entry.
mailmerge1… mailmerge5 Alphanumeric

Mail merge fields. Consider them as custom extension fields for the distribution list entry.

When this element is a child of the “distributionlist” element, its value is a name of the mail merge field (in example, let it be “handset model”).

When this element is a child of the “entry” element, its value should be an actual value of the mail merge field assigned to the specific entry (let it be “Nokia 6820” for our example).

You can use up to 5 mail merge fields in your distribution lists.
Example Response
<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
		<distributionlist>
			<listid>1692</listid>
			<title>My Phones</title>
			<mailmerge1>make</mailmerge1>
			<mailmerge2>model</mailmerge2>
			<entries>
				<entry>
					<entryid>67602</entryid>
					<number>447777777777</number>
					<name>Me</name>
					<email></email>
					<mailmerge1>Nokia</mailmerge1>
					<mailmerge2>6820</mailmerge2>
				</entry>
				<entry>
					<entryid>67801</entryid>
					<number>447777777778</number>
					<name>Me</name>
					<email>me@nowhere.com</email>
					<mailmerge1>Motorola</mailmerge1>
					<mailmerge2>V3</mailmerge2>
				</entry>
				<entry>
					<entryid>67806</entryid>
					<contactid>49455</contactid>
					<name>Me as a contact</name>
					<email>me@nowhere.com</email>
					<mailmerge1>Sony Eriksson</mailmerge1>
					<mailmerge2>C905</mailmerge2>
				</entry>
			</entries>
		</distributionlist>
	</distributionlistsresponse>
 
</apiresponse>

Add, Replace and Merge a Distribution List

Request

Element Type Description
addlist Array

Use this element to add a new distribution list. You will need to provide a title for a new list as a child element (see title element).

First, NetMessenger will check a title of the list you try to add. If you have no any existing distribution lists with such title, NetMessenger will add it.

For a case when list with such a title already exists, you should set onexisting attribute to one of the following values (if such an attribute will not exist in your request, NetMessenger will consider it as existing and set to “skip”):

“skip” – if you want to leave the existing list untouched. In this case, when NetMessenger will find existing list with duplicate title during adding a new list, it will just stop sorting your request.

“replace” – if you want to replace existing list. In this case NetMessenger will replace existing list details and entries with those you sent with your addlist request.

“merge” – if you want to merge entries of the new list with the existing one. Note: if duplicate entry is encountered in the existing list, and existing list doesn’t allow duplicates, it will be replaced with the details of the entry from the new list.

“append” – if you want to append entries of the new list to the existing one. Note: if duplicate entry is encountered in the existing list, and existing list doesn’t allow duplicates, such entry will be skipped.

 

Note: you can use ref alphanumeric attribute if you want to tie your request with the response from the NetMessenger.

 
title Alphanumeric Title of the list you want to apply action to.
allowduplicates Numeric Value can be “1” or “0”. Indicates if your list allows duplicates. When duplicates are not allowed, NetMessenger will replace (while list merge), or skip (while list append) duplicate records in existing lists.

Also, when you add a list using replace action, a value of this element will be used as a setting for a new list.
mailmerge1… mailmerge5 Alphanumeric

Mail merge fields. Consider them as custom extension fields for the distribution list entry.

If this element is a child for addlist, it’s value should be set to mail merge field name (i.e., “car make”). Note, merge fields are used only when your onexisting attribute for the addlist element is set to “replace”.

If this element is a child for entry element, it’s value should be actual content of the field for the specific entry (i.e., “bmw”).

You can use up to 5 mail merge fields in your distribution lists.
entries Array Container for the array of the list entries.
entry Array Container for the details of the specific entry.
entryid Numeric, ID ID of the specific entry record
number Numeric, mobile number Mobile number of the specific list entry, should be in the international format without “+” symbol in the beginning, i.e.: 447777777777
name Alphanumeric Name of the specific list entry. I.e., this could be a person name.
email Valid email A valid email address for the specific entry.
Example Request

If you want to add a new list:

<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<addlist ref="newlist_143">
			<title>My List Name</title>
			<entries>
				<entry>
					<entrynumber>447777777777</entrynumber>
					<entryname>Me1</entryname>
					<entryemail></entryemail>
				</entry>
				<entry>
					<entrynumber>447777777778</entrynumber>
					<entryname>Me2</entryname>
					<entryemail>me@nowhere.com</entryemail>
				</entry>
			</entries>
		</addlist>
	</distributionlists>
</apirequest>

If you want to replace an existing list, and do not want it to have duplicates (existing entries will be replaced when duplicates are encountered):

<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<addlist onexisting="replace" ref="replacelist_352">
			<title>My Existing List Name</title>
			<allowduplicates>0</allowduplicates>
			<mailmerge1>Account Number</mailmerge1>
			<mailmerge2>Reference</mailmerge2>
			<entries>
				<entry>
					<entrynumber>447777777777</entrynumber>
					<entryname>Me1</entryname>
					<entryemail></entryemail>
					<mailmerge1>34653</mailmerge1>
					<mailmerge2>ABC123</mailmerge2>
				</entry>
				<entry>
					<entrynumber>447777777778</entrynumber>
					<entryname>Me2</entryname>
					<entryemail></entryemail>
					<mailmerge1>34654</mailmerge1>
					<mailmerge2>ABC124</mailmerge2>
				</entry>
			</entries>
		</addlist>
	</distributionlists>
 
</apirequest>

If you want to merge your data with an existing list:

<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<addlist onexisting="merge" ref="mergelist_2342">
			<title>My Existing List Name</title>
			<entries>
				<entry>
					<entrynumber>447777777777</entrynumber>
					<entryname>Me1</entryname>
					<entryemail></entryemail>
				</entry>
			</entries>
		</addlist>
	</distributionlists>
 
</apirequest>

If you want to append your data to an existing list:

<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<addlist onexisting="append" ref="appendlist_524">
			<title>My List Name</title>
			<entries>
				<entry>
					<entrynumber>447777777777</entrynumber>
					<entryname>Me1</entryname>
					<entryemail></entryemail>
				</entry>
			</entries>
		</addlist>
	</distributionlists>
 
</apirequest>

Response

Element Type Description
addlist Array Container for the response part related to your addlist request. May have a “ref” alphanumeric attribute, the same as you had in your request so you could tie request and response.
status Alphanumeric Status of the action you requested for. Can be one of the following:
CREATED– if new list have been added successfully.
SKIPPED– if there is a list with the same title as the list in your request, and onexisting attribute was set to “skip” or was not specified.
REPLACED– if there was a list with the same title, which have been replaced with the new list you’ve sent in your request (in case you’ve set onexisting attribute to “replace”).
MERGED– If there is a list with the same title as list in your request and you had “onexisting” attribute set to “merge” in your request.
APPENDED– If there is a list with the same title as list in your request and you had “onexisting” attribute set to “append” in your request.
FAILED– if there was an error during processing your request.
listid Numeric, ID ID of the list which NetMessenger applied an action to.
title Alphanumeric Title of the list which NetMessenger applied an action to.
entries Array Container for the details about entry processing totals.
replacetotal Numeric Total number of the existing list entries replaced with duplicate entries from your request.Note: If the action was to replace the list, then all entries are appended to a new list, so the replacetotal will be 0 in this case.
appendtotal Numeric Total number of your list entries appended to the existing list.
skiptotal Numeric Total number of the list entries skipped during processing your request.
invalidtotal Numeric Total number of entries considered as invalid during processing your request.
failtotal Number Total number of entries which were processed with error.
Example Response

When you successfully added a new list (list ID is for the new list):

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
 
		<addlist ref="ref1">
			<status>CREATED</status>
			<listid>23534654</listid>
			<title>My List Name</title>
			<entries>
				<replacetotal>0</replacetotal>
				<appendtotal>10</appendtotal>
				<skiptotal>0</skiptotal>
				<invalidtotal>0</invalidtotal>
				<failtotal>0</failtotal>
			</entries>
		</addlist>
 
	</distributionlistsresponse>
 
</apiresponse>

When you tried to add a new list, but you already have a list with such a title and onexisting attribute is not set or set to “skip” (list ID is for existing list):

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
		<addlist ref="ref2">
			<status>SKIPPED</status>
			<listid>23534654</listid>
			<title>My List Name</title>
			<entries>
			</entries>
		</addlist>
	</distributionlistsresponse>
 
</apiresponse>

When you successfully replaced an existing list (all entries are appended to a new list, so the replacetotal will be 0):

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
		<addlist ref="ref1">
			<status>REPLACED</status>
			<listid>23534654</listid>
			<title>My List Name</title>
			<entries>
				<replacetotal>0</replacetotal>
				<appendtotal>10</appendtotal>
				<skiptotal>0</skiptotal>
				<invalidtotal>0</invalidtotal>
				<failtotal>0</failtotal>
			</entries>
		</addlist>
	</distributionlistsresponse>
 
</apiresponse>

When you successfully merged your data with an existing list, and that list doesn’t allow duplicates:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
	</userresponse>
 
	<distributionlistsresponse>
		<addlist ref="ref1">
			<status>MERGED</status>
			<listid>23534654</listid>
			<title>My List Name</title>
			<entries>
				<replacetotal>5</replacetotal>
				<appendtotal>5</appendtotal>
				<skiptotal>0</skiptotal>
				<invalidtotal>0</invalidtotal>
				<failtotal>0</failtotal>
			</entries>
		</addlist>
 
	</distributionlistsresponse>
 
</apiresponse>

When you successfully appended your data to an existing list, and that list doesn’t allow duplicates:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
 
		<addlist ref="ref1">
			<status>APPENDED</status>
			<listid>23534654</listid>
			<title>My List Name</title>
			<entries>
				<replacetotal>0</replacetotal>
				<appendtotal>5</appendtotal>
				<skiptotal>5</skiptotal>
				<invalidtotal>0</invalidtotal>
				<failtotal>0</failtotal>
			</entries>
		</addlist>
 
	</distributionlistsresponse>
 
</apiresponse>

When there was an error while handling your request:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
 
		<addlist ref="ref2">
			<status>FAILED</status>
			<listid>23534654</listid>
			<title>My List Name</title>
			<entries>
			</entries>
		</addlist>
 
	</distributionlistsresponse>
 
</apiresponse>

Delete a Distribution List

Request

Element Type Description
deletelist Array Use this element in your request if you want to delete a distribution list at NetMessenger. Element may have a “ref” alphanumeric attribute if you want to tie your request with the response from API.
title Alphanumeric Title of the distribution list you want to delete.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<deletelist ref="dellist_8234" >
			<title>My List Name</title>
		</deletelist>
	</distributionlists>
 
</apirequest>

Response

Element Type Description
deletelist Array Container for the part of the response related to the delete action. May have a ref alphanumeric attribute (the same as those you used in your request).
title Alphanumeric Title of the deleted list.
status Alphanumeric Action status. Can be one of the following:
DELETED– if the list was deleted successfully
ERROR– if there was an error while processing action.
error Array Container for the details on the error (if any occurred while processing your request).
code Numeric Code of the error occurred. For the full error code list click here. Typical error codes you may get for the delete action are:

-516 (if the list you try to delete does not exist)

-301 (if list deletion failed)
message Alphanumeric Brief text description for the error.

Descriptions for typical errors are:

“Unknown List” – for 516 error code

“DB Error” – for the 301 error code
Example Response

If you successfully deleted the list:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
	</userresponse>
 
	<distributionlistsresponse>
		<deletelist ref="ref1" >
			<title>My List Name 1</title>
			<status>DELETED</status>
		</deletelist>
	</distributionlistsresponse>
 
</apiresponse>

If the list you tried to delete doesn’t exist:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
	</userresponse>
 
	<distributionlistsresponse>
		<deletelist ref="ref2">
			<title>My List Name 2</title>
			<status>ERROR</status>
			<error>
				<code>-516</code>
				<message>Unknown List</message>
			</error>
		</deletelist>
	</distributionlistsresponse>
 
</apiresponse>

If there was an error while trying to delete a list:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
 
		<deletelist ref="ref3">
			<title>My List Name 3</title>
			<status>ERROR</status>
			<error>
				<code>-301</code>
				<message>DB Error</message>
			</error>
		</deletelist>
 
	</distributionlistsresponse>
 
</apiresponse>

Delete All Distribution Lists

Request

Element Type Description
deletealllists Empty element Use this element in your request if you want to delete all distribution lists at NetMessenger. Do not include any child element or attribute here.
Example Request
<?xml version="1.0" encoding="UTF-8"?>
<apirequest version="1">
 
	<user>
		<token>[alphanumeric]</token>
	</user>
 
	<application>
		<name>Example Application</name>
		<version>1.0</version>
	</application>
 
	<distributionlists>
		<deletealllists />
	</distributionlists>
 
</apirequest>

Response

Element Type Description
deletealllists Array Container for the part of the response related to the delete-all-lists action.
status Alphanumeric Action status. Can be one of the following:
DELETED– if the list was deleted successfully
NO LISTS TO DELETE– if you have no distribution lists at NetMessenger
ERROR– if there was an error while processing action.
distributionlistdeletetotal Numeric Total number of the deleted distribution lists.
error Array Container for the error details, when there is any.
code Numeric Code of the error occurred. For the full error code list click here.
message Alphanumeric Brief text describing an error occurred.
Example Response

If you successfully deleted all lists:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
 
		<deletealllists>
			<status>DELETED</status>
			<distributionlistdeletetotal>8</distributionlistdeletetotal>
		</deletealllists>
 
	</distributionlistsresponse>
 
</apiresponse>

If you have no lists to delete:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
 
		<deletealllists>
			<status>NO LISTS TO DELETE</status>
			<distributionlistdeletetotal>0</distributionlistdeletetotal>
		</deletealllists>
 
	</distributionlistsresponse>
 
</apiresponse>

If there was an error while handling your request:

<?xml version="1.0" encoding="UTF-8" ?>
<apiresponse>
	<userresponse>
		<status>loggedin</status>
		<userid>4</userid>
 
	</userresponse>
 
	<distributionlistsresponse>
 
		<deletealllists>
			<status>ERROR</status>
			<distributionlistdeletetotal>0</distributionlistdeletetotal>
			<error>
				<code>-300</code>
				<message>DB Error</message>
			</error>
		</deletealllists>
 
	</distributionlistsresponse>
 
</apiresponse>

Appendix

Date Format

Standard XML format – http://www.w3.org/TR/xmlschema-2/#dateTime:

3.2.7.1 Lexical representation

The ·lexical space· of dateTime consists of finite-length sequences of characters of the form: ‘-‘? yyyy ‘-‘ mm ‘-‘ dd ‘T’ hh ‘:’ mm ‘:’ ss (‘.’ s+)? (zzzzzz)?, where

  • ‘-‘? yyyy is a four-or-more digit optionally negative-signed numeral that represents the year; if more than four digits, leading zeros are prohibited, and ‘0000’ is prohibited (see the Note above (§3.2.7); also note that a plus sign is not permitted);
  • the remaining ‘-‘s are separators between parts of the date portion;
  • the first mm is a two-digit numeral that represents the month;
  • dd is a two-digit numeral that represents the day;
  • ‘T’ is a separator indicating that time-of-day follows;
  • hh is a two-digit numeral that represents the hour; ’24’ is permitted if the minutes and seconds represented are zero, and the dateTime value so represented is the first instant of the following day (the hour property of a dateTime object in the ·value space· cannot have a value greater than 23);
  • ‘:’ is a separator between parts of the time-of-day portion;
  • the second mm is a two-digit numeral that represents the minute;
  • ss is a two-integer-digit numeral that represents the whole seconds;
  • ‘.’ s+ (if present) represents the fractional seconds;
  • zzzzzz (if present) represents the timezone (as described below).

 

For example, 2002-10-10T12:00:00-05:00 (noon on 10 October 2002, Central Daylight Savings Time as well as Eastern Standard Time in the U.S.) is 2002-10-10T17:00:00Z, five hours later than 2002-10-10T12:00:00Z.

Message Statuses

Status Description
Pending The message has not yet been sent
Sending The message is in the process of being sent
Sent The message has been sent
Delivered The message has been delivered
Expired The message could not be delivered within the specified validity period
Undeliverable The message was undeliverable, e.g. phone number does not exist
Failed The message failed, e.g. an error occurred connecting to the supplier
Rejected The message was rejected, e.g. the phone number is too long
Deleting The message is in the process of being deleted
Deleted The message was deleted
Unknown The status of the message is unknown

Error Codes

Code Description
-100 Not Enough Credits
-101 Invalid CreditID
-200 Invalid Contact
-300 General Database Error
-301 Unknown Error
-302 Return XML Error
-303 Received XML Error
-400 Some numbers in list failed
-401 Invalid Destination Address
-402 Invalid Source Address – Alphanumeric too long
-403 Invalid Source Address – Invalid Number
-404 Blank Body
-405 Invalid Validity Period
-406 No Route Available
-407 Invalid Schedule Date
-408 Distribution List is Empty
-409 Group is Empty
-410 Invalid Distribution List
-411 You have exceeded the limit of messages you can send in a single day to a single number
-412 Number is blacklisted
-414 Invalid Group
-501 Unknown Username/Password
-502 Unknown Action
-503 Unknown Message ID
-504 Invalid From Timestamp
-505 Invalid To Timestamp
-506 Source Address Not Allowed (Email2SMS)
-507 Invalid/Missing Details
-508 Error Creating User
-509 Unknown/Invalid User
-510 You cannot set a user’s credits to be less than 0
-511 The system is down for maintenance
-512 User Suspended
-513 License in use
-514 License expired
-515 No License available
-516 Unknown List
-517 Unable to create List
-601 Unknown Report Type
-701 No UserID Specified
-702 Invalid Amount Specified
-703 Invalid Currency Requested

0