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