Sending Messages
Use secure HTTPS GET or POST (recommended) to send messages to https://www.bulletinmessenger.net/api/3/sms/out
Simple API Example
Here’s a simple GET example:
https://www.bulletinmessenger.net/api/3/sms/out?userId=yourId&password=yourPassword&to=64222222221&body=hello%20world
Don’t forget to use your password and an international-format number for the recipient, in the “to” parameter.
The complete list of URL encoded parameters for sending messages are:
| Name | 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. Version 3 (/api/3) supports multiple recipients using a space-delimited list |
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. 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. |
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. If undefined a UUID will be generated for you. Not valid with Virtual Numbers or Short Codes. |
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. If undefined this defaults to the "Long Messages" setting configured for your user |
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. See Callback URLs |
NO |
/api/3 |
callbackStatusUrl |
Provide an http or https URL to be called when the status of this message changes. See Callback URLs |
NO |
/api/3 |
Handling a Response
Messenger will respond to each and every HTTP request with one of the following result codes, and an XML response in the body.
| Code | Meaning | Action Required |
|---|---|---|
200 |
Success! |
Message Passed API validation, check the HTTP response XML for details if message subsequently fails Note Messenger versions earlier than /api/3 return a 204 response, so be careful if you are upgrading |
204 |
Success! |
No action required. Valid for /api/1 only |
400 |
Bad Request |
Examine status line for error message |
401 |
Unauthorized |
Check you are using the correct URL as well as userId and password values |
403 |
Forbidden |
Check company limits and address book restrictions and that the recipient is either a) a number, or b) a contact or group. Note companies may be limited in the number of messages sent per day and will get a 403 error if this is exceeded. Contact Support if you need this limit removed |
500 |
Internal Error |
Contact Bulletin |
Important
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.
The body of the response is an XML structure that provides more information about the send attempt.
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:
<?xml version="1.0" ?>
<outbound-message-delivery messageId="FebPromo" isError="true" errorCode="401" errorMessage="Unauthorised">
</outbound-message-delivery>
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".
<?xml version="1.0"?>
<outbound-message-delivery messageId="FebPromo" isError="false">
<recipient msisdn="64211111111" isError="false"/>
<recipient msisdn="64211111112" isError="false"/>
<recipient msisdn="64222222221" isError="true" errorCode="403" errorMessage="Cannot deliver to 64222222221 (Number in Blocked List)"/>
<recipient msisdn="salestem" isError="true" errorCode="403" errorMessage="Cannot deliver to salestem (Contact not in Address Book)"/>
</outbound-message-delivery>