API FAQ

API FAQ

Security

Can we use HTTPS for added security?

Yes. The interface is the same as HTTP, so the only change will be in the protocol portion of the URL used (https:// for SSL).

We recommend that HTTP (SSL) is used where ever security and message integrity is required for an application.

How do I get the values for the 'user' and 'password' fields?
Your user ID and password will be provided after you signup. If you need further assistance please contact Support.
Does the password expire?
No, your password will not expire
How can we request a new password?
Use the password retrieval feature available on the login page

Technical

Can I see when a recipient received a message on their handset?
Yes. Although a few networks do not provide the message status information, most do and they will be shown with the message in the Messenger Inbox
Can I see when a recipient reads a SMS message I sent them?
No. Standard SMS does not provide this sort of information. The closest you can get is if the carrier notifies us when the message is received on the handset.
When sending SMS by email can I tell if the person received it?

Yes. When sending an email set the option for a “read receipt” (each email system has a different way of doing this so see the relevant vendor for more information).

When a message is processed with a read receipt request, Messenger waits for a few minutes and sends an email back that has the status information for each recipient. If you have login credentials you can also view this information in the Messenger Inbox.

Can I send in different languages?

Yes. Some languages may not display correctly on some handsets and carrier networks.

If you are using a UTF-16 language (Chinese, Cyrillic etc), your character payload per SMS message part decreases to 70 characters in the first part, and 134 characters in the second part and 201 in the third part.

This means if you send a message that is 100 characters (for example) in a UTF-16 language, you will be charged for 2 messages.

Are messages delivered immediately?

Bulletin attempts to send all messages to the carriers within seconds of receiving them, but SMS is a best effort, store and forward process which means that the carriers may have their own queuing, delivery and expiry policies.

Once Bulletin has passed the message to the carrier delivery is beyond our control, however, we will request status updates and use these to keep you informed of the of the message if these are available.

You can use the status information to decide whether you should resend the message or use an alternative communication method.

How Many Messages can be sent per minute?

If individual (customised) messages are prepared and sent then about 3000 per minute can be sent through the Bulletin API. The speed of message delivery will also be impacted by:

  • Network connection speed between your client and Bulletin.
  • Method of connecting to Bulletin Connect (HTTP is faster than a SOAP connection).
  • The destination carrier. Some carriers throttle message delivery based on their network requirements.

SPAM

Bulletin Services must not be used for unsolicited SPAM or marketing messages. Users that do so may have the service restricted or cut off.

Download the NZ Unsolicited Electronic Messages Legislation and ensure your service and procedures adhere to this Act. Users residing in other countries or sending messages to other countries (outside of NZ) must ensure that they comply with all applicable local laws.

What are the possible values NUR 'error' field?
The error field contains any string value the carrier returns to us and is very carrier/SMSC/UAS/developer dependent.
Is the purpose of the messageId solely for the use of the sender?

Yes. Any replies to messages you send out will also include a messageId that will link the reply to your original message.

The ID provided by your service is a string of up to 36 characters. If you are persisting this information to a database, that would be the field type to use.

Can I set the SMS expiration period?
No. Not at this time. If you require this feature then contact Sales.
What is the best way to retrieve incoming messages from the Messenger API?

There are two options (Polling and Pushing) to retrieve incoming messages, replies and status updates and it will depend on your network setup, resources and application requirements as to which best suits.

Polling is a client initiated connection to the Messenger API server and reduces firewall and proxy issues that can occur with the push method. More detail available about polling available here

The Push option has the Messenger Server connecting to a REST end point on your server each time a message (reply or status) is processed. More detail about Pushing via Callbacks available here

Does the 160 character limit for single messages apply before, or after URL encoding?
Before. The URL encoding is required in order for the request to be submitted to the Messenger API. Once we receive it it is decoded and then submitted to the the carrier in a format that they require. If you are not setting a fragmentationLimit on your request then ensure that the message length is less than 160 characters before URL encoding it.
What content-types does Messenger API support?
We support Plain-Text and Unicode characters. We do not support Ringtones, IMelody, Operator Logos, or MMS

Benefits and Restrictions

Can I send to more than one recipient?

Yes. The to parameter can be a SPACE Separated List of numbers in International format.. For example: to=642715414141 6178542544 12059955852

Ensure you URLencode the parameters.

Can I send and receive SMS by email using the API?
Yes. You can send an SMS using Email2SMS through Messenger
How does Bulletin handle Mobile Number Portability in New Zealand?

Mobile Number Portability (MNP) allows mobiles to change networks while retaining their phone number. Bulletin receive a file each day which contains details of numbers that have ported. This file is provided by a third party working in association with the carriers and it generally takes 2-3 days for a ported number to appear in this file after a number has changed networks. During the short time between the handset changing networks and us being told of the change, the handset will not receive messages.

Any long term issues with ported numbers should be raised with Support.

Recipient Issues

Where do replies go?

All replies to messages sent from Messenger appear in the Inbox in the web site. Replies are attached to the original message in a ‘thread’ so you can keep track of your conversations.

If you have configured a ‘callback url’ messages will also be delivered to your own server.

If you have the Messenger app installed, messages will also be delivered to the app.

If you have ‘forward2mobile’ enabled, messages will be forwarded to your phone.

Why is the recipient receiving the same message repeatedly?

This is rare but it does occur when the there is a communication glitch between the recipient’s handset and their network, that stops the phone from acknowledging that it has received the SMS.

When this happens the carrier continues to attempt to deliver the same message (as per its store and forward procedures) until it receives an acknowledgment from the phone. This situation results in multiple messages on the handset if the handset does not acknowledge properly (if they all have the same sender number and you are not using short codes then this is probably the situation).

We have found that doing a hard restart of the phone fixes the issue. The recipient should simply pull the battery from the handset, wait a few seconds, reinsert the battery and power the handset up again.

Why might a message not be delivered from a Short Code?
Below are some possible scenarios which can prevent the delivery of messages sending from short codes:

  • By default, some mobile service providers in North America block message deliveries initiated from short codes. In such cases, the recipients (i.e. the handset owners) must contact their mobile service provider directly to unlock such blockages.
  • Some mobile numbers, which have been ported from one network to another, may also experience non-delivery of short codes messages. In such cases, the previous mobile service provider will reply “STOP ALL” to the sender of all the short codes messages to prevent further deliveries. In such cases, the recipients (i.e. the handset owners) must contact their current and/or their previous mobile service providers directly to unlock such blockages.
  • Short codes messages cannot be delivered to recipients using Virtual Numbers, as the sender will be unable to bill the Virtual Numbers holder properly. It is recommended that the recipients to not use Virtual Numbers in such cases.
  • Short codes messages will not be delivered if a recipient has previously replied to a sender with any of the following (case insensitive) keywords: stop cancel end quit unsubscribe The delivery of any future short codes message from that sender will be halted. The recipient must contact the sender to resume the deliveries.

Branding and Marketing

Can the source number be set when sending a message?
Yes. To use this feature please contact Support with details of the numbers you want to use and you will be provided with instructions. Generally this is used when sending via Premium Billed Short Codes rather than the Bulletin default threading range of numbers.
Can the recipient see a name instead of a number when they receive a message?

Yes. Some networks do allow you to set a word or string of words as the number recipients see as the sender of an SMS. This is done by setting the from part of the message payload To use this feature please contact Sales with details of the strings you want to use.

Source headers can be any alphanumeric with the following restrictions: + No more than 11 characters in total + Use only alphanumeric characters (eg: a-z or A-Z, or 0-9) + No symbols or spaces.

Unable to reply

When using this feature the recipient will not be able to reply to the message. Please ensure you have alternative contact instructions in the message to allow users to unsubscribe.

More Information

What's the difference between the Messenger API and Bulletin SMPP?

Bulletin SMPP is purely an enterprise service for very large volume customers who want, for example, their own instance.

The Messenger API is an enhanced version of Bulletin SMPP but is instead integrated with our Messenger product, meaning that you can access reports, messages etc online. You can signup for the Messenger API online, whereas the Bulletin SMPP service requires a business relationship to be established.

Where can I get a copy of the 'service rules'?

You can request a copy of the Service Rules from Support. As these are dictated by mobile network providers, they are subject to change.

Please provide an email address that they can be sent to.

Does Bulletin offer Carrier Lookup functionality?
Bulletin subscribes to the Ported Number Database and uses this to route messages. This is not exposed to third parties as per conditions of use so can only be used for routing and not for look-up purposes.
When is a message billed to my account?
Messages are charged when submitted to the carrier.