Sending a single SMS message using HTTP

Overview

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:

  http://sms.openmarket.com/sms/v1/send
  https://sms.openmarket.com/sms/v1/send

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 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 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:

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. 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:

http://sms.openmarket.com/sms/v1/send?user=MyBulkAccount&pass=P4ssw0rD&smsto=447700900750&smsfrom=58870&smsmsg=Hello%20World&response=text

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?user=MyBulkAccount&pass=P4ssw0rD&smsto=447700900750&smsfrom=58870&smsmsg=Hello%20World&report=7

We 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 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:

http://sms.openmarket.com/sms/v1/send?user=MyBulkAccount&pass=P4ssw0rD&smsto=447700900750&smsfrom=Acme1234&smsmsg=Hello%20World

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
text (recommended)	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
legacytext (default)	The response body contains just the SMS ID. For example: 1846552894	The response body contains a text description of the problem. For example: Forbidden 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
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=MyBulkAccount&pass=P4ssw0rD&smsfrom=58870&smsto=447700900999&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=MyBulkAccount&pass=WrongP4ssw0rD&smsfrom=58870&smsto=447700900999
   &smsmsg=Hello%20World&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 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 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.
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: 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 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: http://sms.openmarket.com/sms/v1/bulksend https://sms.openmarket.com/sms/v1/bulksend 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 status	Detail	Description
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 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.

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.