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://usa.bulksms.com:5567/eapi/reception/get_inbox/1/1.0

Example: http://usa.bulksms.com:5567/eapi/reception/get_inbox/1/1.0?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.

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

Examples:

0|records to follow|3

19|4412312345|Hi there|2004-01-20 16:06:40|44771234567|0
20|4412312346|Hello\nagain|2004-01-20 16:07:35|44771234568|0
21|4412312399|Aloha|2004-01-20 16:08:00|44771234568|0

The format of created_time is yyyy-MM-dd HH:mm:ss (24 hour clock). Dates are all in the GMT+2 time zone at present, but it is intended that this will become adjusted to your account's time zone setting in future. 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 will be escaped as \n and \r.

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

11-Jun-2004

• Initial specification created, for version 1.0.