Overview

Important: The information and contents displayed in these pages is for the OpenMarket's legacy UK SMS APIs. This information is relevant if only you're still using these APIs. For information on migrating from these APIs, see the API Release Notes. Please note, however, that Reporting is still done through Partner Centre, located here: https://partner.mxtelecom.com/home.

This page covers the following topics:

• Integrating via HTTP 
• Requests coming from OpenMarket
• Validity periods
• Single-shot billing
• Retry strategies

Integrating via HTTP 

The UK SMS HTTP API uses both POST and GET requests via the Internet. The endpoints for these requests from your system are:

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

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

http://sms.openmarket.com/sms/v1/bulksend

https://sms.openmarket.com/sms/v1/bulksend

https://portal.openmarket.com/api/disconnects

The SMS APIs support 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 OpenMarket). Pipelining is not recommended for HTTP POST requests.

Send method options

In HTTP GET requests, you will need to add the parameters in the URI. The format required for HTTP API requests 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=MyAccount&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.

Requests coming from OpenMarket

OpenMarket may send you:

• MO SMS messages
• Delivery reports
• Unsubscribe requests

You must provide a URL for incoming reports to receive these.

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

• 83.166.64.0 - 83.166.67.255 (83.166.64.0/22)
• 83.166.68.0 - 83.166.69.255 (83.166.68.0/23)
• 83.166.72.0 - 83.166.75.255 (83.166.72.0/22)
• 83.166.80.0 - 83.166.83.255 (83.166.80.0/22)
• 208.93.48.0 - 208.93.51.255 (208.93.48.0/22)

Validity periods

You can set a validity period for each SMS message. This is the length of time that OpenMarket and the operator will attempt to send the SMS to the end user. If the time period expires before the message reaches the end user, then OpenMarket or the operator (whichever has the message at the time) will drop it and return a failed delivery report.

In the HTTP API, the validity period is set using the vp parameter. For example, the following request has a validity period of 2 hours (7200 seconds):

http://sms.openmarket.com/sms/v1/send?user=MyAccount&pass=P4ssw0rD&smsto=447700900750&smsfrom=58870&smsmsg=Free%20gift%20instore%20until%204pm%20today&vp=7200

Impact on retry strategies

Mobile operator to end user

If a mobile operator cannot initially deliver an SMS message to an end user, it will use a retry strategy to attempt to send the message. Most operators will retry sending the SMS message for around two weeks before dropping the message and sending a "failed" delivery report. If the message has a validity period set, then the operator will use its standard retry strategy until it either reaches the end user, or the validity period expires.

Validity periods set longer than the operator's own maximum will not extend the retry strategy for the message.

OpenMarket to operator

If there is a problem reaching the operator, and the validity time is very short, then OpenMarket will drop the message if the validity period expires.

Limitations to validity periods

Some operators may ignore the validity period if the time period is more than a few days, or altogether.

Single-shot billing

If a premium rate message cannot be delivered due to billing reasons (for example, end user out of credit), OpenMarket will normally resubmit the message to the mobile operator at regular intervals, up to the expiry time of the message. This increases revenue by improving delivery success rates.

However, to enable you to have more control over premium billing, this behavior can be disabled on a per-message or per-account basis. This behavior is known as single-shot billing.

Supported mobile operators

Single-shot billing is only supported on mobile operators where OpenMarket has control of the billing process.

On most other operator networks, the message is held by the operator until it can be billed or until it expires.

Enabling single-shot billing

On a per-message basis

Individual messages can be marked as single-shot billed via additional parameters in the message-sending interfaces. The HTTP interface uses the billingsingleshot parameter.

On a per-account basis

Please contact us to have single-shot billing enabled.

Retry strategies

If an SMS message cannot be delivered to its destination immediately, OpenMarket will normally make several submission attempts before the message is considered to have failed. This increases messaging reliability and delivery success rates.

Delivery of MO messages and delivery reports to a content provider's server is always done using the general retry strategy. For MT messages, depending on the type of failure, one of three types of retry strategy may be used. Delivery Reports documents the types of failure more precisely.

Billing retry strategy

This strategy applies only to premium MT messages, and is used when a message cannot be delivered due to billing reasons, such as the end user being out of credit.

Such an error is unlikely to be rectified rapidly; however, the user may well add credit to their account during the lifetime of the message; OpenMarket will therefore resubmit the message to the operator at regular periods until the message expires. The exact schedule varies according to individual operator rules; however, a typical schedule is as follows:

• If the initial submission is unsuccessful, a second submission attempt occurs after 6 hours.
• If the second attempt is also unsuccessful, a third attempt is made after a further 18 hours.
• Further attempts are made at 24-hour intervals until the message expires.

This behavior can be disabled by enabling single-shot billing or by setting a short validity period when submitting the message to OpenMarket.

This retry strategy is used in all regions aside from Australia. In Australia, we will only attempt to bill the end user once (due to regulatory requirements). Note that, in each region, this behavior only takes place on mobile operators where OpenMarket has control of the billing process. For other operators, the message is held by the operator until it can be billed, or until it expires.

General retry strategy

This strategy is used for any unexpected error, for both MO and MT messages, and delivery reports. All regions use this retry strategy. Example of such errors are:

• Any failure to deliver an MO message or delivery report to your system, including networking errors, application errors, and so on.
• System problems at the destination operator when submitting MT messages.
• Networking problems between OpenMarket and the destination mobile operator when submitting MT messages.

The aim in this case is to deal gracefully with temporary outages, without utilizing excessive resources due to queuing messages. An exponential strategy is used to meet these requirements:

• If the initial submission is unsuccessful, a second submission attempt occurs after about 30 seconds.
• If the second attempt is also unsuccessful, a third attempt is made after a further 60 seconds.
• A third submission attempt is made after a further 120 seconds.
• The interval is doubled each time, until a total of 10 submission attempts have been made.
• If the 10th submission attempt is still unsuccessful, the message is treated as permanently failed, and no more submission attempts are made. In the case of MT messages, a REJECTED delivery report is then returned.
• The 10th submission attempt therefore typically occurs around four hours after the initial attempt. Note, however, that if the message has a validity period of less than four hours, the message may expire before all submission attempts have been made - in which case, no more submission attempts are made, and a REJECTED delivery report is returned in the case of MT messages.

Note that single-shot billing does not affect retries made under the general retry strategy.

Permanent failures

If it is unlikely that an MT message will ever be delivered in its current state, it is considered to have failed immediately, and a REJECTED delivery report is returned.

Examples of such permanent errors include:

• Invalid/unknown destination number.
• End user barred from receiving premium content.
• Binary messages sent to an operator that does not support them.