Deprecated - please use the JSON API instead.


Note: Messages can be routed back to you via HTTP, which is the preferred way for you to messages. Using get_inbox to poll for messages is not recommended. 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 the internet.

This API allows you to retrieve incoming messages received on your account.





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.

Request parameters

parameter required description


Your incoming messages are returned in a simple delimited format:



Possible values for status_code are:

status_code description
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.

Response data

field description
msg_id an integer identifier unique to this incoming message.
sender the number that the incoming message was sent from.
message the message sent.
recieved_time the time the message was received, relative to the time zonr in your Profile.
msisdn the number that the incoming message was sent to.
refering_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.


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.