reception/get_inbox

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.

URL

«EAPI URL»/reception/get_inbox/1/1.1

Example

«EAPI URL»/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.

Request parameters

parameter required description
username  
password  
last_retrieved_id  

Response

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

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.

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.