Sending a single SMS message using HTTP
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
- Sending an SMS to a single recipient
- Response from the SMS Gateway
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:
- 220.127.116.11 - 18.104.22.168 (22.214.171.124/23)
- 126.96.36.199 - 188.8.131.52 (184.108.40.206/24)
- 220.127.116.11 - 18.104.22.168 (22.214.171.124/22)
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. 12515550100). No leading "+" is required.|
|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:http://sms.openmarket.com/sms/v1/send?
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:http://sms.openmarket.com/sms/v1/send?
We recommend setting report to 7, so that you receive all possible reports.
|report||Determines whether the SMS Gateway will send delivery reports
to your platform for an individual SMS message.
|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 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:http://sms.openmarket.com/sms/v1/send?
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:
|Format||Response for successful request||Response 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:
Forbidden Bad username/password
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.
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 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=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100 &smsmsg=Hello&response=text&report=7 HTTP/1.1 Host: sms.openmarket.com 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=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&response=text&report=7 &smsmsg=This%20is%20a%20very%20long%20message%20that%20is%20sent%20as%20a%20multipart%20 message. HTTP/1.1 Host: sms.openmarket.com 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=MyMXOneAccount&pass=WrongP4ssw0rD&smsto=12515550100 &smsmsg=Hello&response=text HTTP/1.1 Host: sms.openmarket.com 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 number blacklisted by the carrier
- 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
|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 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.
|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 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.|
|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.
|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||This status occurs only when the request is sent to the broadcast SMS endpoint.
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||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
|10700||Bad username/password||Either the value of the user or pass parameter is not correct.|
|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.|
|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.|
|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.|
500 HTTP status codes
|10900 - 10902||Internal 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.