Broadcasting an SMS message using HTTP
Overview
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.
Contents
- Integrating with the SMS Gateway
- Sending an SMS to multiple destinations
- Response from the SMS Gateway
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://sms.openmarket.com/sms/v1/bulksend https://sms.openmarket.com/sms/v1/bulksend
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 MX Telecom IP address range:
- 83.166.68.0/23 (i.e. 68.0 to 69.255)
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:
| Parameter | Description | |
| 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:
user=MyMXOneAccountThe "%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:
user=MyMXOneAccountWe recommend setting report to 7, so that you receive all possible reports.
| Parameter | Description | |
| report | Determines whether the SMS Gateway will send delivery reports
to your platform for an individual SMS message.
Default: 0 | |
| 0 | The SMS Gateway does not send any delivery reports to your platform. | |
| 1 | Enables BUFFERED (intermediate) reports. | |
| 2 | Enables DELIVERED (successful) reports. | |
| 3 | Enables BUFFERED and DELIVERED reports. | |
| 4 | Enables FAILED (failure) and REJECTED reports. | |
| 5 | Enables BUFFERED, FAILED and REJECTED delivery reports. | |
| 6 | Enables DELIVERED, FAILED and REJECTED delivery reports. | |
| 7 | Enables 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:
user=MyUKBulkAccountFor 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.
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
- in the US, specify how the end user opted in to your service to satisfy T-Mobile's requirements. See Adding T-Mobile US opt in details for more information.
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:
12515550100,4276184166,0
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 12515550100,3900457830,0 12515550123,3900457831,0 12515550145,3900457832,0
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:
. . . 12515550100,3900457830,0 12515550100,3900457831,0 12515550123,3900457832,0 12515550123,3900457833,0 12515550145,3900457834,0 12515550145,3900457835,0
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 12515550100,3900457830,0 12515550123,3900457831,0 12515550145,,10702
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 status | Detail | Description |
| 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 status | Detail | Description |
| 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 - 10112 | 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. |
| 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: push_siexpires=2011-02-27T14:00:00 |
| 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:
http://sms.openmarket.com/sms/v1/bulksend https://sms.openmarket.com/sms/v1/bulksendRequests 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 status | Detail | Description |
| 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 status | Detail | Description |
| 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.
