Sending a single 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 an SMS message request for a single recipient to the SMS Gateway. 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.

The endpoint, request format, and response from the SMS Gateway described on this page applies only to message requests for one recipient per request. If you are sending the same SMS message to multiple recipients, you may prefer to use the interface described in Broadcasting an SMS.

When sending a message request for a single recipient, you can:

  • send any message type in the Sending Reference (such as plain text, WAP Push, or binary data)
  • send multipart and flash messages
  • use either the HTTP GET or POST request methods


Integrating with the SMS Gateway

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

The SMS Gateway supports HTTP/1.1 persistent connections, enabling the TCP/IP connection to be kept open between submission attempts. If you need to send messages with a high transmission rate, then use several (up to 4) persistent HTTP/1.1 connections concurrently. Pipelining requests is supported but should only be used where necessary (i.e. with high message rates and large latency between your platform and the SMS Gateway). Pipelining is not recommended for HTTP POST requests. If you are interested in HTTP Pipelining, we suggest you read the Mozilla FAQ for more information.

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 a single recipient

To send an SMS message to a single recipient, send an HTTP GET or 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. 447700900750). No leading "+" is required.
smsfrom Sets the originator for the request. This is valid only for requests going through a bulk SMS Gateway account, for services outside of the US. The value can be either an phone number (up to 16 digits) or an alphanumeric string encoded in the Modified Latin-9 character set (up to 11 characters).
other parameters The other parameters required for the type of message (such as plain text, WAP Push, or binary data). See the Sending Reference section for details.

In HTTP GET requests, you will need to add the parameters in the URI. The format required by the SMS Gateway is URL encoded and UTF-8 encoded, where each parameter/value pair is separated by an "&" character. For example:

In HTTP POST requests, the parameters are specified in the body of the request. You should submit POST requests using application/x-www-form-urlencoding encoding. Each parameter/value pair is separated by an "&" character, as per the GET request method.

The format and required parameters for each type of message is described in the Sending Reference section.

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 network, see Delivery Reports.

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

Setting the originator

For Bulk messaging in all regions aside from 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 all messages in the US, and Premium Rate SMS messages in any region, 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.

Choosing the response format

After receiving a request, the SMS Gateway will respond with a HTTP response. The response body will contain either an SMS ID or an error message. You can choose how the information in the response body is formatted using the response parameter. The options are text or legacytext:

FormatResponse for successful requestResponse for failed request
The response body contains an SMS Gateway submit status ID and the SMS ID. For example:
submitstatus: 0
smsid: 1846552894
The response body contains an SMS Gateway submit status code and a text description of the problem. For example:
submitstatus: 10700
detail: Bad username/password
The response body contains just the SMS ID. For example:
The response body contains a text description of the problem. For example:
  Bad username/password

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 the 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 (accepted or rejected) it receives with an HTTP response.

The examples in this section use response=text option for the response format. We recommend that you use this response format.

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 contains an SMS ID which is a positive 64 bit integer used to uniquely identify an SMS message as it passes through the SMS Gateway. For example, the following example shows both the request and response back from the SMS Gateway, including the SMS ID (3999775791):

GET /sms/v1/send?user=MyBulkAccount&pass=P4ssw0rD&smsto=447700900999&smsfrom=ACME
   &smsmsg=Hello%20World&response=text&report=7 HTTP/1.1
Connection: keep-alive

HTTP/1.1 200 OK
Date: Wed, 07 Jul 2010 16:24:56 GMT
Server: Apache
Content-Type: text/plain; charset=iso-8859-1

submitstatus: 0
smsid: 3999775791

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

GET /sms/v1/send?user=MyBulkAccount&pass=P4ssw0rD&smsfrom=58870&smsto=447700900999&response=text&report=7
   message. HTTP/1.1
Connection: keep-alive

HTTP/1.1 200 OK
Date: Wed, 28 Jul 2010 12:28:01 GMT
Server: Apache
Content-Type: text/plain; charset=iso-8859-1

submitstatus: 0
smsid: 3999775791
smsid: 3999775792
smsid: 3999775793

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

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

If there is a problem with acting on a request, the SMS Gateway will return an HTTP rejected request status code (400, 403 or 500). The response body will include an SMS Gateway submit status code (submitstatus:) and a text description (detail:) of the problem. For example:

GET /sms/v1/send?user=MyBulkAccount&pass=WrongP4ssw0rD&smsfrom=58870&smsto=447700900999
   &smsmsg=Hello%20World&response=text HTTP/1.1
Connection: keep-alive

HTTP/1.1 403 Forbidden
Date: Thu, 12 Aug 2010 09:20:49 GMT
Server: Apache
Content-Type: text/plain; charset=iso-8859-1

submitstatus: 10700
detail: Bad username/password

Receiving a 400 (bad request) or 403 (forbidden) HTTP 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
  • it cannot be actioned because of regulatory or general service reasons—for example, the SMS Gateway will reject requests to a MSISDN blacklisted by the network
  • 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 HTTP status codes indicate a problem with the SMS Gateway 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 - 10116 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.
10200 This account cannot send to this country Your account cannot send a message to the MSISDN as it is on a network 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 MSISDN 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.
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.
10209 WAP pushes are not supported on this network The MSISDN 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.
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 mobile 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 This status occurs only when the request is sent to the broadcast SMS endpoint. 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 This status occurs only when the request is sent to the broadcast SMS endpoint. The SMS Gateway cannot accept the broadcast request, as it is currently processing the maximum number of broadcast SMS requests it will accept at the same time. Wait one minute then resubmit the rejected request.
10562 Request still processing This status occurs only when the request is sent to the broadcast SMS endpoint. 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.
10701 Destination is blacklisted The MSISDN is currently on the MSISDN blacklist. Contact your MX Telecom account manager for more information.
10702 Destination is blocked The MSISDN cannot receive the type of SMS message you are sending, or the MSISDN is outside the range of networks 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.
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 account manager if you need to change the addresses in this whitelist.
10705 Maximum messages to this MSISDN exceeded You have reached the maximum number of messages you can send to this MSISDN in a day.
10706 Reverse billing forbidden The MSISDN has not opted in to your Premium Rate service on this Short Code.

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.

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.