 | 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:
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?
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. |
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 HTTP API interface is composed of ONE method only:
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. |
|
Sending via an API
API URL
|
|
Sending Messages
Name (case sensitive) | Description | Required? | Min. Version |
|---|---|---|---|
userId | 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. | YES | /api/1 |
password | Your account password | YES | /api/1 |
to | 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. | YES | /api/1 |
body | 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. | YES | /api/1 |
from | Your Message Source MSISDN that you wish to use so that recipients can identify you. | NO | /api/3 |
messageId | An identifier that you can use to track message status information for retrying due to errors or delays. Maximum 36 characters. | NO | /api/3 |
fragmentationLimit | 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. | NO. | /api/3 |
contentType | "text/plain" or "text/plain; charset=UTF-16" | NO | /api/3 |
callbackUrl | Provide a mailto, http, or https URL to be called when replies are made to this message. More details below | NO | /api/3 |
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.
|
|
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. 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 mailto, http and https. mailto protocolThe mailto protocol is used for Email Notifications, and supports two optional parameters:
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:
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:
http and https protocolThese 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:
callbackUrl values for the HTTP and HTTPS protocols support these variables:
| Example: |
top
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.
|