Optional parameters common to all messages types
Overview
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
- Adding delivery reports
- Adding subaccount and note details to a request
- Changing validity periods
- Changing the HTTP response format for single-recipient requests
- Enabling single-shot billing
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:
http://sms.openmarket.com/sms/v1/send?This request sends a plain text message with the originator set to ACMEDentist:
http://sms.openmarket.com/sms/v1/send?| Parameter | Description |
| 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:
|
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:
http://sms.openmarket.com/sms/v1/send?We recommend setting report to 7, so that you receive all possible reports.
| Parameter | Description | |
| report | Determines whether the SMS Gateway will send delivery reports
to your platform for an individual SMS message.
Default: 0 | |
| 0 | The SMS Gateway does not send any delivery reports to your platform. | |
| 1 | Enables BUFFERED (intermediate) reports. | |
| 2 | Enables DELIVERED (successful) reports. | |
| 3 | Enables BUFFERED and DELIVERED reports. | |
| 4 | Enables FAILED (failure) and REJECTED reports. | |
| 5 | Enables BUFFERED, FAILED and REJECTED delivery reports. | |
| 6 | Enables DELIVERED, FAILED and REJECTED delivery reports. | |
| 7 | Enables 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 carrier, 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 carrier.
| Parameter | Description |
| note | Note 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. |
| subaccount | Subaccount to be stored in the transaction log. This can be up to 30 characters in length. The MX Telecom Partner Center 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 carrier 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 carrier (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):
http://sms.openmarket.com/sms/v1/send?| Parameter | Description |
| vp | Length of time, in seconds, that the carrier will attempt to
send the SMS to the end user. If the carrier cannot initially reach the end user, then the standard
retry strategy for the carrier 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 carriers 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 carrier will use their standard retry strategies. |
Impact on retry strategies
Carrier to end user
If a carrier cannot initially deliver an SMS message to an end user, it will use a retry strategy
to attempt to send the message. Most carriers 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 carrier will use its standard retry strategy until it either reaches the
end user, or the validity period expires.
Validity periods set longer than the carrier's own maximum will not extend the retry strategy for the message.
SMS Gateway to carrier
If there is a problem reaching the carrier, 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 carriers 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:
http://sms.openmarket.com/sms/v1/send https://sms.openmarket.com/sms/v1/sendTo choose how the information in the response body is formatted, use the response parameter. The options are text or legacytext, for example:
http://sms.openmarket.com/sms/v1/send?
| Format | Response for successful request | Response for failed request |
| text (recommended) |
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 |
| legacytext (default) |
The response body contains just the SMS ID. For example:
1846552894 |
The response body contains a text description of the problem. For example: Forbidden 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 carrier 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:
http://sms.openmarket.com/sms/v1/send?| Parameter | Description |
| billingsingleshot | Enable single-shot billing for the message.
Any non-empty value will enable single-shot billing.
Default: messages are submitted as normal |
