Sending via an API

HTTP API

A lightweight API provides the simplicity that you're looking for when wanting to enable your applications to send SMS messages. Sending a message is as easy as POSTing a web form.
The following limits are in place for this API.

1. Only one recipient per connection. If you need to send to multiple recipients then you will need to loop through your recipient list sending to one each time.
2. Message Status is not reported back via the API. The status will be updated and can be viewed by logging in to Bulletin Messenger or by requesting a list of recent messages using the available feeds.
3. Replies are not handled by the API. Replies can be viewed by logging in to Bulletin Messenger or by requesting a list of recent messages using the available feeds.
4. Message length is ignored by the API and messages are not split into parts.

   If your needs exceed these limits then consider using Bulletin Connect which offers a carrier grade API using a setup that is very similar to that described here but without the restrictions. See the Feature Comparison Matrix for information on what features are available in each of the Bulletin messaging API's.

HTTP Overview

The HTTP API interface is composed of ONE method only

1. to send a single message

To use the API simply post method parameters to the Bulletin Messenger server in the same way that a browser would submit a form.

To do this method parameters are first HTML form encoded and then submitted in an HTTP POST. This is simple and well supported in almost all development environments.

N.B. The number and order of parameters may vary. While the parameter names described in this document will not change, additional parameters may be added to the API from time to time.

Bulletin Messenger API URL

Sending Messages

Use secure HTTPS POST to send messages to https://www.bulletinmessenger.net/api/1/sms/out.
Recognised URL encoded parameters for sending messages are:

Name (case sensitive)	Description	Required?
userId	User name for authentication (same as used for logging into the website)	YES
password	A SHA1 hash of your account and password details. Failure to provide this will result in an Authentication error even if you provide the password. See the SHA1 Password Hash section for more information on generating the hash or login to http://bulletinmessenger.net and view your Messenger Settings for the correct string to use.	YES
to	Destination Number or Addressbook item (contact or group)	YES, one item only
body	Message Payload	YES

Bulletin Messenger will respond to each and every HTTP request with one of the following result codes.

The userId and password are supplied to you by Bulletin Wireless when you sign up for a Bulletin Messenger account. You may pass them to the server as form encoded parameters, or in the HTTP Authorization header in Basic format.

The to parameter is the destination Number (MSISDN or Addressbook item such as a Contact or Group. For numbers, include the country code but do not include leading zeros, spaces, brackets or other formatting characters. To send a message to multiple recipients POST multiple times or configure groups in your online Addressbooks.

The body parameter is used to pass the message. Messages can be up to 160 characters long. The allowable character set may vary depending on the destination network. In general characters from the GSM default character set are safe (see GSM 03.38). If you send longer messages they will be logged as POSTed but only the first 160 characters will be sent. Note, this may change at anytime and result in longer messages being delivered without warning.

Receiving Messages

You can not receive individual messages/replies using the API. Access the http://bulletinmessenger.net web site to view your incoming messages or use the Message Feeds to access message logs using your code/application.

Receiving Message Receipt (status information)

You can not receive individual message receipts using the API. Access the http://bulletinmessenger.net web site to view the status of your messages or use the the Message Feeds to access message logs (including status information) using your code/application.

SHA1 Password Hash

The Bulletin Messenger API requires a SHA1 hash of the password. Failure to provide this will result in an 401 authentication error even if you provide the correct password.

You can copy and paste the correct hash from http://bulletinmessenger.net in your Messenger Settings.

To generate the SHA1 hash for the API you can use any appropriate library (eg the javascript one here) and follow these steps.

1. Generate an SHA1 hash of your account password
2. encode as base 64 (refer to this as password-hash)
3. Generate an SHA1 hash of account username + password-hash (no spaces),
4. encode as base 64 (refer to this as the api-hash)