This api allows you to retrieve incoming messages received on your account. You should by preference use HTTP relaying - only use get_inbox if you have no option, e.g. if you are behind a firewall, or if you are not permanently connected to this Internet.

Getting started

URL: http://textnigeria.vsms.net:5567/eapi/reception/get_inbox/1/1.1

Example: http://textnigeria.vsms.net:5567/eapi/reception/get_inbox/1/1.1?username=john&password=
abcd1234&last_retrieved_id=65876

Procedure: the first time that you use get_inbox, you should specify last_retrieved_id=0. This will return all the messages in your Inbox. You must now record the highest message_id returned (i.e. the message_id of the last item returned), and the next time you call get_inbox, you must specify last_retrieved_id to be this last id. This will ensure that you only retrieve messages that have not been retrieved before.

Specification

Required parameters

• username
• password
• last_retrieved_id

Optional parameters

• out_format: currently only simple (the default) is available.

Possible values for status_code:

• 0: Results to follow
• 22: Internal fatal error
• 23: Authentication failure
• 24: Data validation failed
• 40: Temporarily unavailable

You should not depend on the text of status_description remaining constant - depend only on the numeric value of status_code.

Returned data

• msg_id: an integer identifier unique to this incoming message.
• sender: the number that the incoming message was sent from.
• message: the message sent.
• received_time: the time the message was received, relative to the time zone set in your Profile.
• msisdn: the number that the incoming message was sent to.
• referring_batch_id: the integer identifier that was returned (by send_sms) at the time when the original message was submitted, if this message is in reply to another previously sent. If this incoming message is not a reply, this field will be set to zero.
• encoding: 7bit/8bit/16bit.

Returned data format (simple)

Your incoming messages are returned in a simple delimited format:

status_code|status_description|extra_info
msg_id|sender|message|received_time|msisdn|referring_batch_id|encoding

Examples:

0|records to follow|3

19|4412312345|Hi there|2011-01-20 16:06:40|44771234567|0|7bit
20|4412312346|234f345a324b6b523a|2011-01-20 16:07:35|44771234568|0|8bit
21|4412312399|This is a Unicode message ☺|2011-01-20 16:08:00|44771234568|0|16bit

The format of received_time is yyyy-MM-dd HH:mm:ss (24 hour clock), in your account's configured time zone. message_id is a unique integer id per message.

Another example:

23|invalid credentials|

The number of records that will be returned from a single request is limited, currently to 1000 messages.

Newlines and carriage returns in the message body output are escaped as \n and \r.

The HTTP response is UTF-8 encoded.

Previous versions

Documentation for older versions of this API can be found here.

Versioning

New features will be added to existing API versions provided the features are backwards compatible. If they are not backwards compatible, a new version will be declared, but the previous version(s) will remain available. Therefore, if you find yourself switching versions, you should look carefully at the Changelog below for incompatibilities.

ChangeLog

05-Sep-2011 Updated to version 1.1. Switched to UTF-8 (no need to decode Unicode any longer). Appended output field to indicate encoding (7bit/8bit/16bit). 30-Mar-2009 Fixed outdated comments regarding the time zone of received_time. 01-Nov-2005 referring_msg_id field renamed to referring_batch_id. 11-Jun-2004 Initial specification created, for version 1.0.