Receiving unsubscribe notifications 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.

This page details the format of unsubscribe notifications sent by the SMS Gateway to your platform. These notifications identify when an end user should no longer be considered subscribed to your service. You can receive a unsubscribe notification via either email or an HTTP GET request sent by the SMS Gateway.

Contents

Sources of unsubscribe notifications

Unsubscribe notifications can be sent out whenever an end-user is removed from a partner's reverse-billing whitelist. End-users may be removed from whitelists for any of the following reasons:

  • Number no longer active: if we receive confirmation that a user's number is no longer active on a particular network, it will be removed from all partners' whitelists.
  • Sending "STOP" to a Shared Short Code. Because we are unable to determine which partner's service the STOP was intended for, we will remove the user's number from the shared Short Code whitelists of all partners who have MT accounts on the Shared Short Code.
  • Call to our automated or staffed customer-care lines (particularly in the case of Shared Short Codes where the PhonePayPlus customer-care line is provided by MX Telecom).

Enabling HTTP notifications for unsubscribes

Normally, notifications of unsubscribes are sent via email; however, in order to facilitate automated processing of these notifications, they can also be sent via HTTP using the interface described below. To have this enabled, please contact us.

Message format

Unsubscribe notifications will take the form of an HTTP GET request to your server, using the parameters included in the table below:

ParameterDescription
msisdn The MSISDN being removed
shortcode The short code to remove this MSISDN from.
date Date and time of request in yyyy-MM-dd HH:mm:ss format
source The source of the request (max length of 50 characters):
IVR (call to automated removal service), STOP (MO STOP SMS sent in), UnknownSubscriber (user is no longer a valid subscriber on this network), UNKNOWN (other)

For example, a request to remove 447884436692 from 81111 and 82222 at 2005-08-29 19:12:45 triggered by a call to our IVR automated removal service:

http://something.customer.com/test?msisdn=447884436692&shortcode=82222&date=2005-08-29+19%3A12%3A45&source=IVR

We will retry a request which fails after a timeout (currently 60 seconds). It is the partner's responsibility to filter duplicate requests—these might occur if for some reason we did not receive the HTTP response from a previous attempt within 60 secs (perhaps because the reply took longer than that or there was a network outage etc).

Response to the SMS Gateway

The system expects to receive a non-empty HTTP 200 response to the request. If a 200 response is not given within a timeout (currently 60 seconds) then the request will be retried.

Security considerations

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

  • 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)

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