Optional parameters common to all messages types


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 describes the optional parameters when sending an SMS message. They are valid for any SMS message sent through the SMS Gateway. For information about integrating with the SMS Gateway, see either Sending a Single SMS or Broadcasting an SMS.

The options are:

Changing the originator of the message

The smsfrom parameter sets the originator for bulk SMS messages for services outside of the US. You can set either a phone number or alphanumeric value as the originator of the message.

In the UK, there is no regulatory restriction on what you can set as the originator for bulk sending. For example, this request sends a plain text message with the originator set to the Short Code 58870:


This request sends a plain text message with the originator set to ACMEDentist:

smsfrom Either a phone number (up to 16 digits) or an alphanumeric string encoded in the Modified Latin-9 character set (up to 11 characters). This parameter is mandatory for bulk services in all regions accept the US.

Regulatory requirements means that you cannot change the originator for:

  • Premium Rate SMS messages in any region
  • Standard Rate SMS messages in the US
In these instances, the originator is always your service's Short Code. If you do set the originator, the SMS Gateway will ignore the value.

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:


We recommend setting report to 7, so that you receive all possible reports.

reportDetermines whether the SMS Gateway will send delivery reports to your platform for an individual SMS message.
Default: 0
0The SMS Gateway does not send any delivery reports to your platform.
1Enables BUFFERED (intermediate) reports.
2Enables DELIVERED (successful) reports.
3Enables BUFFERED and DELIVERED reports.
4Enables FAILED (failure) and REJECTED reports.
5Enables BUFFERED, FAILED and REJECTED delivery reports.
6Enables DELIVERED, FAILED and REJECTED delivery reports.
7Enables 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.

Adding subaccount and note details to a request

You can use the optional subaccount and note fields to identify and catagorize messages. This is vital if you're reselling services or just want to group certain messages.

The information is stored with the SMS messages billing record. Neither field is passed to the network.

noteNote that will be stored in the transaction log and passed back with delivery reports. This can be up to 160 characters in length. The note field has no effect on the delivery of the message.
subaccountSubaccount to be stored in the transaction log. This can be up to 30 characters in length. The MX Telecom Partner Centre can provide reporting based on this field. Subaccounts do not need to be preconfigured.

Changing validity periods

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

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

vpLength of time, in seconds, that the network will attempt to send the SMS to the end user. If the network cannot initially reach the end user, then the standard retry strategy for the network is used until this validity period is reached.
You can specify any positive number; however, the SMS Gateway may need to adjust the value as some networks have minimum validity periods, or only allow specific values (such as in 30 second increments).
Default: There is no validity period set. The SMS Gateway and network will use their standard retry strategies.

Impact on retry strategies

Network to end user
If a network cannot initially deliver an SMS message to an end user, it will use a retry strategy to attempt to send the message. Most networks 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 network will use its standard retry strategy until it either reaches the end user, or the validity period expires.

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

SMS Gateway to network
If there is a problem reaching the network, and the validity time is very short, then the SMS Gateway will drop the message if the validity period expires.

Limitations to validity periods

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

Changing the HTTP response format for single-recipient requests

You can change the format of the HTTP response sent by the SMS Gateway to a message request. This applies only to requests for single recipients that use one of these endpoints:

To choose how the information in the response body is formatted, use the response parameter. The options are text or legacytext, for example:

FormatResponse for successful requestResponse for failed request
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
The response body contains just the SMS ID. For example:
The response body contains a text description of the problem. For example:
  Bad username/password

Enabling single-shot billing

If the SMS Gateway cannot deliver a Premium Rate SMS message due to billing reasons (for example, if the end user is out of credit), it will normally resubmit the message to the network at regular intervals over several days using a billing retry strategy. This increases revenue by improving delivery success rates.

However, you can request that the SMS Gateway only attempts billing once. This is called single-shot billing. To enable single-shot billing for a request, include the billingsingleshot parameter in a request, with any value specified, for example:

billingsingleshotEnable single-shot billing for the message. Any non-empty value will enable single-shot billing.
Default: messages are submitted as normal