Receiving an SMS via HTTP

Overview

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.

The MX Telecom SMS Gateway can send SMS messages to your platform using HTTP. This page details the format that the HTTP requests take.

Requirements

Your platform will need to accept HTTP GET method requests from the following IP address ranges:

  • 83.166.68.0 - 83.166.69.255 (83.166.68.0/23)
  • 83.166.72.0 - 83.166.72.255 (83.166.72.0/24)
  • 208.93.48.0 - 208.93.51.255 (208.93.48.0/22)

For security, make sure that your platform only accepts requests from that IP range.

You will need to provide us with a URL to your platform. To protect the data while in transit, we recommend using an HTTPS (SSL) URL.

Message format

The SMS Gateway includes the following parameters in the HTTP GET request:

ParameterDescription
smsfromThe mobile number (MSISDN) that the message originates from.
smstoThe Short Code or Virtual Mobile Number that received the SMS message.
smsdateThe time and date that the SMS Gateway received the message, in the format: yyyy-MM-dd hh:mm:ss. This value is the current time and date in London, United Kingdom (either GMT or BST, depending on the time of year).
networkThe originator's network. The SMS Gateway can only determine this value for SMS messages sent to a Short Code. Click here for a list of the network codes that the SMS Gateway passes for this parameter.
For SMS messages sent to a Virtual Mobile Number, the SMS Gateway sends the code UNKNOWN.
smsidA positive 64 bit integer used to uniquely identify the SMS message as it passes through the SMS Gateway. As well as when passing on a Mobile Originated SMS messages, the SMS Gateway will send SMS IDs with delivery reports and HTTP responses.
bitsIndicates the format of the SMS message body, as specified by the smsmsg parameter.
7 The message body is in the Latin-9 (ISO-8859-15) character set.
8 The message body is hexadecimal encoded data. This is commonly used when the message body is binary code.
16 The message body is in UCS-2 Unicode, and both the smsmsg and smsucs2 parameter specify the message body. The smsmsg parameter value is a best-effort 7-bit text representation of the UCS-2 Unicode data carried in the smsucs2 parameter.
smsmsgThe SMS message body. The format is indicated by the bits parameter.
smsudhThe UDH content sent with the SMS message. The SMS Gateway only sends this parameter when the SMS message contains UDH content.
smsucs2This parameter is sent only when the message body is UCS-2 Unicode encoded messages. This parameter is hexadecimal encoded. Messages are commonly UCS-2 Unicode encoded when they contain special characters. The smsmsg parameter contains a best-effort text representation of this data.

When sending HTTP GET requests we will attempt up to 10 message deliveries, until successful, with an exponential delay between sending (30 seconds, 60 seconds, 120 seconds etc).

It is the your responsibility to filter duplicate requests, using the smsid value. These might occur if for some reason we did not receive the HTTP response from a previous attempt within 60 secs (for example, due to packet loss over the Internet).

https://server.com/drpt.cgi?smsfrom=447700900765&smsmsg=Hello+World&smsto=58870&smsid=4172212931&smsdate=2010-04-30+21%3A58%3A00

Response to the SMS Gateway

Your platform should respond with an HTTP 200 response with a non-empty body. This response must be given in a timely manner (within 10 seconds). Currently we do not abandon a request (waiting for the HTTP response) until 60 seconds have passed but this might be reduced in future.