Receiving Delivery Reports via 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.

The MX Telecom SMS Gateway can return Delivery Reports for each message sent through the SMS Gateway. These reports provide feedback regarding the delivery status of each SMS message.

This page describes the format of Delivery Reports sent to your platform. For information about enabling and interpreting delivery reports, see Delivery Reports.

If messages are sent with delivery reports enabled (and the networks concerned support reports) then delivery reports will be added to the online billing system automatically.

To receive a report back for a message, you need to include the report parameter in the message request. See Optional Parameters for more information.


Receiving a delivery report using HTTP

If a sending account has an HTTP (or HTTPS) URL associated with it then the SMS Gateway will push SMS delivery reports back to the application.

Message format

The parameters are similar to the HTTP SMS Receiving interface; however certain additional fields are available, and some are used differently.

Example report:
smsfrom The number of the end user you are sending a message to.
smsdate The timestamp of the delivery report. Format: yyyy-MM-dd HH:mm:ss.
smsmsg Defined below.
reason The detailed delivery reason code. This is passed as a decimal number; for example "1610612736". Before it can be used, this code should be converted to hexadecimal; for example, "0x60000000". For information on interpreting this value, see Delivery Report Reason Codes.
note The note passed with the original MT message request. This field is only present if a note was provided.
smsto Can be ignored.
shortcode Can be ignored.

The smsmsg field will be of the format:


For example:

REPORT <37954551> <BUFFERED>

<SMS ID> is a positive 64 bit integer used to uniquely identify an SMS message as it passes through the SMS Gateway. This ID is assigned when the message is first submitted to the SMS Gateway, and the HTTP response returned for the request includes this ID. <STATUS> is the delivery report type code. These codes are explained here.

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 (sub 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.


To ensure the authenticity of the HTTP requests you should only accept requests from the following IP addresses:

  • - (
  • - (
  • - (

The HTTP endpoint can be an HTTPS (SSL) URL to protect the data whilst in transit.