Parameters

To send an on-demand request to retrieve SMS messages that have been received, please send a HTTP POST to the API URL with the following POST parameters.

HTTP Post Parameters Definitions

USERNAME

• Type: string
• Description: This is your Username for your SMS Central account

PASSWORD

• Type: string
• Description: This is your Password for your SMS Central account

ACTION

• Type: string
• Description: To view received SMS messages, please provide the string value ‘read’ (without single quotes) as this POST parameter’s value.

DATESTART

• Type: datetime
• Description: To specify a day and time for how far back you wish to retrieve the received SMS messages, please specify this day and time in datetime format.
  * For example, if you wish to retrieve messages newer than and including 25 December, 2011 and 3:35pm is:

  2011-12-25 15:35:00

DATEEND

• Type: datetime
• Description: To specify a day and time for an end period for which you wish to retrieve the received SMS messages, please specify this day and time in datetime format.

For example, if you wish to receive messages up until and including 25 December 2011, please provide the value of 2011-12-25 23:59:59

STATUS

• Type: string
• Description: This STATUS parameter allows you to specify which type of messages you would like to retrieve, the options, to be provided as values (all characters uppercase) are:
  • ‘ALL’ – this will retrieve all received SMS messages, for the dates specified in DATESTART to DATEEND (or every single message, if no values are provided for those parameters)
  • ‘UNREAD’ – this will retrieve all SMS messages, for the dates specified in DATESTART to DATEEND, which are marked as unread. Please note that retrieving unread messages will result in them consequently being marked as read
  • ‘READ’ – this will retrieve all received SMS messages, which have been marked as read (either by retrieving unread messages via the API, or marking them as read by logging in to your SMS Central account).

CAMPAIGN

• Type: string
• Description: The campaign parameter allows you to retrieve the reply messages to the campaign you may have just sent. By providing the name of the campaign (URL encoded) as per the value provided via the CAMPAIGN parameter when sending an SMS, you can retrieve reply messages to that campaign. For example, you may provide the CAMPAIGN value of the name of your campaign and the STATUS value of 'UNREAD' in order to retrieve new (unread) reply messages to your campaign.

Response

SMS Central will always return a “HTTP/1.1 200 OK” HTTP status code in the header of the response to your HTTP POST.

The ‘content’ of the response to your HTTP POST will be in XML format when messages are received, or a simple string if there was an error with your request.

The XML Response will contain a collection of <message> tags, inside a single <messages> tag.

Each <message> tag will contain the following tags wrapped within:

• <datestamp> - this is the date the message was received
• <direction> - this will always be ‘MO’ which stands for Mobile Originated and represents an inbound message
• <originator> - this is the mobile number of the handset which sent in the message
• <recipient> - this is the mobile number that the handset was sending the message to
• <messagetext> - this is the text message content that was received

Example of a Successful Response To Your Request (type: XML)

<messages>

      <message>

            <datestamp>2011-10-13 21:28:44</datestamp>

            <direction>MO</direction>

            <originator>61xxxxxxxxx</originator>

            <recipient>61xxxxxxxxx</recipient>

            <messagetext>Lorem ipsum dolor sit amet</messagetext>

      </message>

</messages>

Possible Error Responses To Your Request (type: string)