Bulletin Messenger - Developer Guide

Skip to end of metadata
Go to start of metadata

Redirection Notice
This page should redirect to Bulletin API Developer Guide in about 3 seconds.

Back to Knowledge Base
Back to User Guide


About Bulletin API

Table of Contents



Signing Up to Messenger

This Bulletin API Developer Guide provides information on the simple REST based API for application developers and software integrators. Before using Bulletin API you must be subscribed to the Bulletin Messenger service - this is automatic for online signups. Be sure to view the terms of service and feel free to contact us if you have any questions.

Before you start you will need:

  • a valid email address
  • nothing else

The email address is used to validate your account and can also be used to send SMS via email once you are in the system. There is not much point using a one time email address as you will never be able to send SMS from it will you?

Or, if you have assimilated with Google then you can login using your Google ID.
Before you start you will need:

  • a valid Google account
  • a bit of trust

Once you have these at hand visit https://www.bulletin.net/sign-freetrial/messenger to signup.

As a bonus we will even give you a few free messages so you can see how it all works before you part with some of your hard earned cash.

You will receive an email full of information so read it and have a look at the links so you can get the most out of Messenger.


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. 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 messagesusing the available feeds.

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.

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.


Sending via an API



HTTP Method

URL to Use

Sending Messages



Example URL String

Don't forget to use your password and international number for the recipient.


Sending Messages

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

Name (case sensitive)



Min. Version


User name for authentication (same as used for logging into the website). User name and password may be passed as form encoded parameters, or in the HTTP Authorization header in Basic format.




Your account password




Destination Number (MSISDN or Address book item (contact or group). For numbers, include the country code but do not include leading zeros, spaces, brackets or other formatting characters. You can send a message to multiple recipients by space-delimiting items.
Version 3 (/api/3) supports multiple recipients using a space-delimited list




The Message to send. Messages can be up to 480 characters long, although this can be controlled by fragmentationLimit. 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). Set contentType to "text/plain; charset=UTF-16" to support richer alphabets.




Your Message Source MSISDN that you wish to use so that recipients can identify you.
Only numbers or source strings that you have registered against your account can be used.
If undefined then the default value will be used from your account settings.




An identifier that you can use to track message status information for retrying due to errors or delays. Maximum 36 characters.
If undefined a UUID will be generated for you




Sets maximum number of SMS message parts to use for Multipart SMS Messages. Gateways may not respect this setting, which may result in longer messages being delivered without warning.
If not defined this defaults to the "Long Messages" setting configured for your user




"text/plain" or "text/plain; charset=UTF-16"




Provide a mailto, http, or https URL to be called when replies are made to this message. More details below




Bulletin API will respond to each and every HTTP request with one of the following result codes, and an XML response in the HTTP body.



Action Required



Message Passed API validation, check the HTTP response XML for details if message subsequently fails
Note that Bulletin Messenger versions earlier than /api/3 returned a 204 response, so be careful if you are upgrading



No action required
Valid for /api/1 only


Bad Request

Examine status line for error message



Check you are using the correct URL as well as userId and password values



Check company limits and address book restrictions and that the recipient is either a) a number, or b) a contact or group.
note prepay users are limited to 100 messages per day and will get a 403 error if you exceed that. contact us Bulletin if you need this limit removed


Internal Error

Contact Bulletin


It is important to note that the API may return a 200 Success result but still fail due to invalid contact name or possibly insufficient funds. You should get into the habit of checking the response XML for any issues in particular if sending to multiple recipients and/or members of your address book.


The following response indicates that processing was at least partially successful. The "salestem" error is likely due to a typo in the request, which should've been "salesteam".

The following XML response example indicates a fundamental problem with the request which resulted in no messages being sent. In this case due to an authentication problem:


Callback URLs

Bulletin API will call your provided URL each time a reply is received to a message that was sent with the callbackUrl property defined. Callback URLs can include variables that Messenger will populate dynamically at runtime.

Replies that trigger an HTTP or HTTPS callback process will retry for up to 48 hours if your service does not return a valid HTTP result code such as 200, 204, 301, 307.
Any codes in the 400+ range will result in retry. To avoid duplicate messages being posted to your service ensure you issue a HTTP 200 status code.

If the reply has NOT been successfully acknowledged within 48 hours it will be removed from the retry queue and can viewed on-line only.

The currently supported URL formats, which must be URL encoded prior to inclusion in the request, are mailtohttp and https.

mailto protocol

The mailto protocol is used for Email Notifications, and supports two optional parameters:

Parameter Name




Controls the Subject used in the email notification

NO. If undefined will default to "RE:"


Controls the Body of the email sent in the email notification

NO. If undefined will default to the body of the message sent by the recipient

Step 1: URL Encode your mailto parameters (if used)

Replace the newlines (\n below) with %0A and spaces with %20. Any other characters should also be encoded

Subject=Message: {!messageId}&Body={!body}\n\n-- \nIn Reply to {!messageId}\n\n

to get the encoded string below

Step 2: Concatenate the mailto string together as below

Step 3: Finally URL Encode the entire string, for use as the "callbackUrl" parameter

Note, this does result in 'double' encoding of the mailto parameters if used. This is correct and required.

Response format:

  • If the Body parameter has been defined, the body of the email delivered contains the evaluated value of the Body parameter, plus the original outbound message.
  • If the Body parameter has not been defined, the body of the email delivered contains the message sent by the recipient, plus the original outbound message.

e.g. Given the URL shown in the above example, if the original SMS was "Sign up for our competition", with a messageId of "FebPromo", and the recipient replied with "Yes Please", the email body delivered would be:

Yes Please

In Reply to FebPromo

>> Sign up for our competition

http and https protocol

These protocols are used to provide web-based notifications of message replies. These protocols have no optional parameters and all properties and values are URL encoded when they are submitted to your web server.

Messenger will use the POST method to communicate with your service and expects a HTTP 200 status code result in return.

Example URL:

URL Encoded:

Response format:

The http and https response is a simple XML document, containing the following properties:




Indicates the message that this reply is associated with


The date the reply message was received, formatted as ISO-8601 in the UTC Timezone


The recipient's display name, if any


The recipient's phone number


The content of the SMS message received from the recipient, formatted as CDATA.

callbackUrl values for the HTTP and HTTPS protocols support these variables:




The value of the messageId parameter in the original request, or the system-generated UUID if messageId was undefined in your original message


The content of the SMS reply sent by the recipient in response to the original message.
We do not recommend including this at part of an http URL as it and the rest of the values are included in the XML document


The recipient's MSISDN/phone number


The "display name" of the recipient, as used to send the original message



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.


Like Us on Facebook Follow Us On Twitter Share with Linkedin Watch on YouTube