Broadcasting an SMS message using HTTP


OpenMarket now offers a RESTful and feature-rich Global SMS API. Compared to the existing MX Telecom APIs, the Global SMS API provides:

  • Automated originator selection, which selects the correct short code or VMN for any country or territory
  • Our highest level SLA and increased messaging capacity
  • Better security through Basic authentication
  • A test environment for new and migrating customers

as well as a host of other benefits. While we will continue to support our existing SMS APIs, we believe that our Global SMS API offers some exciting features and benefits that you'll want to take advantage of, and future feature development will be focused on the Global SMS API. For more information, see the Release Note on our Docs and Resources website.

Note that currently the Global SMS API does not support Premium Rate messaging. Existing Premium Rate customers should continue to use the MX Telecom APIs.

This page describes how to send a broadcast SMS message request to the SMS Gateway via HTTP or HTTPS. It includes integration requirements, examples of the response to expect back from the SMS Gateway, and a full list of the error messages the SMS Gateway will return if there is a problem with the request.

When sending a broadcast SMS message request to the SMS Gateway, you can:

  • send any message type in the Sending Reference (such as plain text, WAP Push, or binary data)
  • send multipart and flash messages
  • send the SMS message to up to 10 000 recipients
  • use the HTTP POST request method

This page describes how to send an SMS message to multiple recipients. See Sending a Single SMS for information on sending an SMS message to a single recipient using either the GET or POST request method.


Integrating with the SMS Gateway

Your platform must be able to send HTTP POST requests via the Internet to the SMS Gateway. The possible endpoints for these requests are:  

HTTP/1.1 is enabled so, if sending multiple requests, the TCP/IP connection should be kept open between requests. Pipelining is not recommended for HTTP POST requests.

To receive delivery reports for each SMS message, your platform must provide a URL for incoming reports from the SMS Gateway. Your platform should only receive these reports from the following IP address ranges:

  • - (
  • - (
  • - (

See Delivery Reports for more information.

Sending an SMS to multiple destinations

To send a broadcast SMS request, send an HTTP POST request to one of the SMS Gateway endpoints, with the following parameters in the response body:

user The SMS Gateway account you are sending the message through.
pass The password for the SMS Gateway account.
smsto The MSISDN of the message recipient in international format (e.g. 12515550100). No leading "+" is required.
For SMS message requests to multiple recipients, separate each MSISDN with a line break (e.g. smsto=12515550100%0A12515550123%0A12515550145).
submitid A text string up to 30 characters that uniquely identifies the broadcast request in the SMS Gateway. You should ensure that each new broadcast request uses a unique ID. For example, if you were sending daily broadcasts, you could use the current date, e.g.: "broadcast1_2010-10-01".
other parameters The other parameters required for the type of message, as described in the Sending Reference section.

You should submit POST requests to the SMS Gateway using application/x-www-form-urlencoding encoding. Each parameter/value pair is separated by an "&" character, and must be URL encoded and UTF-8 encoded.

For example, to send a plain text SMS message saying "hello" to the numbers 12515550100, 12515550123 and 12515550145, use these parameters in the request:


The "%0A" between each number is a URL encoded line break.

Using the correct SMS Gateway account

If you have an MX One account, you can use this account to send a Standard Rate broadcast request to any carrier.

If you do not have an MX One account, you will need to group the numbers by carrier and send each group through the correct SMS Gateway account for that carrier.

Premium Rate SMS Gateway accounts are linked to individual carriers and tariff rates. If you are planning on sending Premium Rate SMS messages using a broadcast request, you will need to group the numbers by carrier and send each group through the correct SMS Gateway account for that carrier and tariff.

Adding delivery reports

Delivery reports provide feedback to your platform concerning the delivery of MT messages. We highly recommend using delivery reports to monitor the progress of your SMS messages.

To receive a report back for a message, you need to include the report parameter in the message request. For example, to receive all types of delivery reports for the previous example, set report to equal 7:


We recommend setting report to 7, so that you receive all possible reports.

reportDetermines whether the SMS Gateway will send delivery reports to your platform for an individual SMS message.
Default: 0
0The SMS Gateway does not send any delivery reports to your platform.
1Enables BUFFERED (intermediate) reports.
2Enables DELIVERED (successful) reports.
3Enables BUFFERED and DELIVERED reports.
4Enables FAILED (failure) and REJECTED reports.
5Enables BUFFERED, FAILED and REJECTED delivery reports.
6Enables DELIVERED, FAILED and REJECTED delivery reports.
7Enables BUFFERED, DELIVERED, FAILED and REJECTED delivery reports.

For an overview of delivery reports, a description of how to interprete them, and a list of the availability by carrier, see Delivery Reports.

For a description of the format of delivery reports sent via HTTP, see Receiving Delivery Reports.

Setting the originator

For Standard Rate messaging in all regions bar the US, you must set an originator for the message using the smsfrom parameter. You can set this to a number (up to 16 digits) or an alphanumeric text string (up to 11 characters). For example:


For Premium Rate SMS messages in any region, and all messages in the US, the originator is set for each account and cannot be changed. The SMS Gateway will ignore the smsfrom parameter if it is sent in these requests.

Carrier-specific requirements

Where possible, OpenMarket removes the complexity of sending messages to multiple carriers. However, there are several carriers where you services may need to provide additional parameters or use a different messaging workflow. For information on these, please see US Carrier-Specific Requirements.

Other options

For each message type, you can additionally:

  • use the note and subaccount parameters to add optional reporting notes
  • use the vp parameter to alter the length of time the SMS Gateway should attempt to reach each end user (if they cannot be reached initially)
  • for Premium Rate messages, use the billingsingleshot parameter to set the request to only attempt billing once

Response from the SMS Gateway

The SMS Gateway acknowledges all requests it receives with an HTTP response.

  • Accepted requests return an HTTP 200 status code. For broadcast SMS message requests, this will show whether the request was accepted for all or some of the numbers.
  • Rejected requests return an HTTP 400, 403, or 500 status code. The SMS Gateway rejects requests when there is a problem with the request format. No SMS messages are sent.

Accepted requests (200 HTTP status code)

When a request is accepted, the SMS Gateway returns an HTTP response with a 200 status code. The response body will contain a list, separated by line breaks, in the following format:

number,SMS ID,submitstatus 

For example:


The SMS ID is a positive 64 bit integer that uniquely identifies an SMS message as it passes through the SMS Gateway. Each SMS message accepted in the request is given a unique SMS ID. As well as in these HTTP responses, the SMS Gateway will also send SMS IDs with delivery reports and when passing on Mobile Originated SMS messages.

The submitstatus identifies the status of the request. If there is no issue with sending the SMS message to the number then the submit status will be 0. If the SMS Gateway has determined there would be a problem sending an SMS to the number, then an SMS ID is not returned. Instead, a 5 digit submit status code is listed for the number.

This example response shows that the SMS Gateway will send the SMS message to the numbers 12515550100 12515550123 and 12515550145, and has assigned SMS IDs to these numbers (3900457830 to 3900457832). The submit status code for each number is set to 0:

HTTP/1.1 200 OK
Date: Wed, 05 Aug 2009 11:05:08 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked


If the request is for a multipart SMS message, then each part of the message is given an SMS ID, so the response from the SMS Gateway will include multiple SMS IDs for the same number on separate lines. For example:


You can track the delivery of each SMS message through its SMS ID in the delivery reports sent by the SMS Gateway.

Problems with sending the SMS to an individual MSISDN

In the next example, the SMS Gateway has determined that it cannot send the SMS message to the number 12515550145 and so returns the error code 10702:

HTTP/1.1 200 OK
Date: Wed, 05 Aug 2009 11:05:08 GMT
Server: Apache/1.3.26 (Unix) mod_ssl/2.8.8 OpenSSL/0.9.6a
Content-Type: text/plain
Transfer-Encoding: chunked


This is still an accepted request. The SMS Gateway will send the SMS message to any number that came back with an SMS ID.

The possible per-message submit status codes are:

Submit statusDetailDescription
10200 This account cannot send to this country Your account cannot send a message to the number as it is on a carrier in a country you cannot send messages to. Talk to your MX Telecom account manager about sending messages to this region.
10201 Invalid msisdn The number appears to be an incorrect length or includes non-numerical characters.
10202 Invalid optin There is a problem with the specified opt-in parameters (optin1, optin1ts, optin2, or optin2ts). The SMS Gateway checks that these values use the correct format and that all necessary parameters are included. For example, if you specify optin1=other:<value> you must include the optin1ts parameter.
See Adding T-Mobile US opt in details for more information.
10209 WAP pushes are not supported on this network The number is on a network that does not support WAP Pushes. You will need to send the URL to the end user as a plain-text SMS with the URL included.
10701 Destination is blacklisted The number is currently on the MSISDN blacklist. Contact your MX Telecom business development manager for more information.
10702 Destination is blocked The number cannot receive the type of SMS message you are sending, or the number is outside the range of carriers that the SMS Gateway can send that type of message to.
10703 Credit limit exceeded The request was rejected as sending the SMS messages would exceed your monthly per-account credit limit.
10705 Maximum messages to this MSISDN exceeded You have reached the maximum number of messages you can send to this number in a day.
10706 Reverse billing forbidden The number has not opted in to your Premium Rate service on this Short Code.

The SMS Gateway can send delivery reports for any problem that occurs with the delivery of each individual SMS message. You can use the SMS ID in the delivery report to track each message. See delivery reports for more information.

Rejected requests (400, 403 and 500 HTTP status codes)

If there is a problem with acting on a request, the SMS Gateway will return a rejected request status code (400, 403 or 500).

Receiving a 400 (bad request) or 403 (forbidden) status code indicates that there was the following type of problem with the request:

  • an authentication error
  • the request is not from a whitelisted IP address
  • there are missing or invalid parameters
  • you have exceeded a daily limit or credit limit

The request should not be retried until you have resolved the problem.

Note that, in some cases, the SMS Gateway will ignore an optional parameter in a request (for example, smsfrom in the US) if it would stop the message from being sent.

The 500 status codes indicates that there was a problem with receiving your request. You should retry the request after a minute.

The following tables list the possible reasons for requests being rejected.

400 HTTP status codes

Submit statusDetailDescription
10001 - 10025 Required parameter <name> missing The request has an invalid or missing parameter (<name>). Either the parameter is missing from the request or it is misspelled in the request.
10100 - 10115 Bad <name> parameter The value for a required parameter <name> is invalid. For example, you would get this response if you specified a letter rather than a number for the report parameter. Check that the value uses the correct format before resubmitting the request. These errors are returned for required parameters but not optional parameters.
10203 Message too long The message is too large to send in its current format. This will be either because it exceeds the number of parts the message type can have (between 2 and 5 parts), or you have not requested it to be sent as a multipart message. Either resubmit a shorter message or send the message as a multipart message.
10204 Failed to decode message The SMS Gateway could not decode the message content as it was not correctly hex-encoded. The message type you are sending requires the message contents to be hex-encoded.
10207 Request type unknown The format of the request did not include all the parameters you require to send any message type. For example, you would receive this error message if your request contained only the user, pass and smsto parameters.
10210 Submitid too long The value of the submitid parameter exceeds the maximum allowed length (30 characters).
10500 Bad image data The image sent in the request was not correctly hex-encoded.
10501 Could not decode image data The image was correctly hex-encoded, but is not in an image format supported by the SMS Gateway. The SMS Gateway supports BMP, GIF, JPEG and PNG.
10551 Invalid URL Your request included a parameter that requires a URL. The value of this parameter must begin with either either http:// or https://. The SMS Gateway will also check that URLs with a 'www' subdomain include 3 'w' characters.
Format the URL correctly before resending the request.
10552 Invalid expiration date The value of the push_siexpires parameter must be a date in the format yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss, where 'T' is literally the character T. For example:
10553 Action requires si-id You have specified push_action=4 in a WAP Push message request. This action deletes a WAP Push on an end user's cell phone. You must also specify the push_siid parameter to identify the WAP Push you wish to delete.
10554 Invalid push type For WAP Push message requests only. The value you specified for the pushtype parameter is incorrect. For WAP Push Service Indication requests, you must specify 0 for this parameter.
10560 Only http method POST is accepted You have specified one of these endpoints for the message:
Requests to these endpoints must be sent via HTTP POST.
10561 Too many concurrent requests You have sent multiple broadcast requests at the same time. The SMS Gateway will process up to two broadcast requests at a time. Wait one minute then resubmit the rejected request.
10562 Request still processing The request has the same submitid of a request you have very recently sent (within the last minute). After the SMS Gateway has finished processing the original request, it will return a HTTP 200 response. If you are attempting to send a different request, then change the value of the submitid parameter before resubmitting the request.

403 HTTP status codes

Submit statusDetailDescription
10700 Bad username/password Either the value of the user or pass parameter is not correct.
10704 You are not authorized to send messages from that IP address The request did not come from one of the IP addresses in the whitelist you provided to MX Telecom. You can only submit requests from the IP addresses in your whitelist. Contact your MX Telecom business development manager if you need to change the addresses in this whitelist.

500 HTTP status codes

Submit statusDetailDescription
10900 - 10902 Internal error
Provisioning error
There was a problem that stopped the SMS Gateway from receiving your request. Retry the request after a minute.

Multiple requests with the same submit ID

The submitid uniquely identifies the broadcast request in the SMS Gateway and you should ensure that each new broadcast request uses a unique ID.

If the SMS Gateway receives two requests with the same submitid value within a 24 hour period, then it will not action the second request. Instead, it will return the results of the first submitted request. This is regardless of whether there are differences between the values or parameters of the two requests. Each time a request is submitted with the same submitid value in a 24 hour period, the 24 hour window restarts.

However, in case the same value for submitid is accidentally re-used over the lifetime of your accounts, if requests with the same submitid value are separated by more than 24 hours, then the SMS Gateway will consider them as separate requests.

Unexpected characters in the response

If you receive unexpected characters in an HTTP response from the SMS Gateway, it may be because the SMS Gateway is using "chunked" transfer coding, which is part of the HTTP 1.1 specification. These are normally stripped out by the browser or other transfer agent you are using to interface with the SMS Gateway. However, you may see these characters while connecting to the SMS Gateway via Telnet. You can ignore these characters if you see them.