Sending a plain text SMS using 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 describes how to send a plain text message through the SMS Gateway. For information about integrating with the SMS Gateway, see either Sending a Single SMS or Broadcasting an SMS.

Contents

Character set options

The SMS Gateway has three character set options for sending plain text SMS messages:

  • Modified Latin-9
  • GSM 03.38
  • UCS-2 Unicode

Messages you submit in modified Latin-9 or GSM 03.38 character sets are sent in a character set appropriate to the destination carrier. These character sets normally have fewer characters than modified Latin-9, so some characters in the modified Latin-9 set do not have a direct counterpart. In these instances, our system performs a best-guess mapping, for example turning the character into i.

You may also submit messages in UCS-2 Unicode which supports a much wider variety of characters. MX Telecom sends these messages in UCS-2 Unicode encoding. However, as UCS-2 Unicode is a 16-bit encoding, using it to send SMS messages restricts the maximum number of characters per message to 70.

See our Knowledge Base for more information about the Modified Latin-9 character set and the GSM 03.38 character set.

Adding User Data Header (UDH) information

You can send UDH information in a plain text message.

UDH information is useful for multiple tasks, including setting a specific port for the message to be delivered to or manually creating a multipart message. Messages split using UDH concatenation are limited to 153 characters per part. This is due to the overhead from the header.

You can also use UDH information in binary data messages. You cannot specify UDH information for other message types. However, the SMS Gateway may still add UDH information in the message sent to the end user; for example, in a WAP Push message.

Sending a message using Modified Latin-9

Single-recipient end points:

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

Broadcast end points: (HTTP POST only)

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

Example single-recipient request:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsmsg=Hello%20World

This sends the message Hello World from the account MyMXOneAccount, with password P4ssw0rD, to the recipient 12515550100. Note that the message content, Hello World is URL encoded (e.g. the space is represented by %20).

Mandatory parameters:

ParameterDescription
user The SMS Gateway account you are sending the message through.
pass The password for the SMS Gateway account.
smsto The MSISDN of the message recipient in international format (e.g. 12515550100). No leading "+" is required.
If you are sending a broadcast SMS request, separate each MSISDN with a line break (e.g. smsto=12515550100%0A12515550123%0A12515550145).
smsmsgThe message text, encoded in the Modified Latin-9 character set.

Optional parameters specific to this request type:

ParameterDescription
bitsThe bits parameter is used to identify the type of data you are sending in the message body of the request. You only need to specify this parameter when you are sending User Data Header (UDH) information in the SMS message (with the smsudh parameter). For this type of request, bits must equal 7.
flashDetermines whether the message is sent as a flash message. Flash messages are shown immediately on an end user's mobile phone without the user taking any action, and are often not saved to the phone. It is not recommended to send an SMS that is both multipart and flash.
Default: 0
0 Message is not sent as a flash message.
1 Message sent as a flash message.
smsudhEnables you to add User Data Header (UDH) information. The format of UDH information is octet pairs in decimal notation, e.g. 06050430393039.
For this type of message request, you must also specify bits=7 if you are including UDH information in the message.
If you specify the smsudh parameter, then the SMS Gateway will ignore the split parameter, if specified. To send a multipart message, you will need to manually split the message into separate requests and use the UDH information to concatenate the message.
splitDetermines whether the SMS Gateway treats the message as single or multiple part. The smsudh and split parameters are mutually exclusive.
Default: 0
0The message is not split. The SMS Gateway will reject the message if it is greater than 160 characters.
1 The message is split into normal messages of approximately 160 characters with each message part (bar the end message) ending with ellipsis "...". The end user's cell phone treats each message part as a separate message rather than combining them into one message.
2The message is split using SMS Concatenation. This uses User Data Header (UDH) information to tell the cell phone how many parts there are. The end user's cell phone will combine the message parts into one message.
3The message is split into normal messages of approximately 160 characters. The end user's cell phone treats each message part as a separate message rather than combining them into one message.

Carrier-specific parameters and requirements:

Where possible, OpenMarket removes the complexity of sending messages to multiple carriers. However, there are several carriers where you services may need to provide additional parameters or use a different messaging workflow. For information on these, please see US Carrier-Specific Requirements. The specific parameters are:

Optional parameters you can use for any request type:

  • smsfrom: sets the originator for the message—this parameter is mandatory for standard rate messages in all regions bar the US
  • submitid: used to send broadcast SMS messages
  • report: sets the delivery reports you want for the message
  • response: (for single-recipient requests only) changes the format of the HTTP response from the SMS Gateway
  • note, subaccount: optional reporting notes that you can add to the request
  • vp, billingsingleshot: alters the validity period and billing for the SMS message

Examples:

This request sends the message Welcome to ACME as a flash message. Setting report=7 enables the SMS Gateway to send delivery reports for the generated SMS message:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsmsg=Welcome%20to%20ACME&flash=1&report=7

This request sends the message Very long message as a concatenated multipart message:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsmsg=Very%20long%20message&split=2

Sending a message using GSM 03.38

Single-recipient end points:

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

Broadcast end points: (HTTP POST only)

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

Example single-recipient request:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsia5=Hello%20World

This sends the message Hello World from the account MyMXOneAccount, with password P4ssw0rD, to the recipient 12515550100. Note that the message content, Hello World is URL encoded (e.g. the space is represented by %20).

Mandatory parameters:

ParameterDescription
user The SMS Gateway account you are sending the message through.
pass The password for the SMS Gateway account.
smsto The MSISDN of the message recipient in international format (e.g. 12515550100). No leading "+" is required.
If you are sending a broadcast SMS request, separate each MSISDN with a line break (e.g. smsto=12515550100%0A12515550123%0A12515550145).
smsia5 The message text, encoded in the GSM 03.38 character set.

Optional parameters specific to this request type:

ParameterDescription
flashDetermines whether the message is sent as a flash message. Flash messages are shown immediately on an end user's mobile phone without the user taking any action, and are often not saved to the phone. It is not recommended to send an SMS that is both multipart and flash.
Default: 0
0 Message is not sent as a flash message.
1 Message sent as a flash message.
smsudhEnables you to add User Data Header (UDH) information. The format of UDH information is octet pairs in decimal notation, e.g. 06050430393039.
If you specify the smsudh parameter, then the SMS Gateway will ignore the split parameter, if specified. To send a multipart message, you will need to manually split the message into separate requests and use the UDH information to concatenate the message.
splitDetermines whether the SMS Gateway treats the message as single or multiple part. The smsudh and split parameters are mutually exclusive.
Default: 0
0The message is not split. The SMS Gateway will reject the message if it is greater than 160 characters.
1 The message is split into normal messages of approximately 160 characters with each message part (bar the end message) ending with ellipsis "...". The end user's cell phone treats each message part as a separate message rather than combining them into one message.
2The message is split using SMS Concatenation. This uses UDH information to tell the cell phone how many parts there are. The end user's cell phone will combine the message parts into one message.
3The message is split into normal messages of approximately 160 characters. The end user's cell phone treats each message part as a separate message rather than combining them into one message.

Carrier-specific parameters and requirements:

Where possible, OpenMarket removes the complexity of sending messages to multiple carriers. However, there are several carriers where you services may need to provide additional parameters or use a different messaging workflow. For information on these, please see US Carrier-Specific Requirements. The specific parameters are:

Optional parameters you can use for any request type:

  • smsfrom: sets the originator for the message—this parameter is mandatory for standard rate messages in all regions bar the US
  • submitid: used to send broadcast SMS messages
  • report: sets the delivery reports you want for the message
  • response: (for single-recipient requests only) changes the format of the HTTP response from the SMS Gateway
  • note, subaccount: optional reporting notes that you can add to the request
  • vp, billingsingleshot: alters the validity period and billing for the SMS message

Examples:

This request sends the message Welcome to ACME as a flash message. Setting report=7 enables the SMS Gateway to send delivery reports for the generated SMS message:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsia5=Hello%20World&flash=1&report=7

This request sends the message First part of long message. It uses the smsudh parameter to send it as a concatenated multipart message:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsia5=First%20part%20of%20long%20message&smsudh=06050430393039

Sending a message using UCS-2 Unicode

Single-recipient end points:

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

Broadcast end points: (HTTP POST only)

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

Example single-recipient request:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsucs2=03b303b503b903b10021

This sends the message “γεια!” from the account MyMXOneAccount, with password P4ssw0rD, to the recipient 12515550100. The message is sent using a series of UCS-2 16-bit words. For example, the character 三 (the Japanese symbol for the number three) is hexadecimal encoded as 4E09. As UCS-2 Unicode is a 16-bit encoding, using it to send SMS messages restricts the maximum number of characters per message to 70.

Mandatory parameters:

ParameterDescription
user The SMS Gateway account you are sending the message through.
pass The password for the SMS Gateway account.
smsto The MSISDN of the message recipient in international format (e.g. 12515550100). No leading "+" is required.
If you are sending a broadcast SMS request, separate each MSISDN with a line break (e.g. smsto=12515550100%0A12515550123%0A12515550145).
smsucs2 The message text as hexadecimal encoded UCS-2.

Optional parameters specific to this request type:

ParameterDescription
smsudhEnables you to add User Data Header (UDH) information. The format of UDH information is octet pairs in decimal notation, e.g. 06050430393039.
If you specify the smsudh parameter, then the SMS Gateway will ignore the split parameter, if specified. To send a multipart message, you will need to manually split the message into separate requests and use the UDH information to concatenate the message.
splitDetermines whether the SMS Gateway treats the message as single or multiple part. The smsudh and split parameters are mutually exclusive.
Default: 0
0The message is not split. The SMS Gateway will reject the message if it is greater than 70 Unicode characters.
2The message is split using SMS Concatenation. This uses UDH information to tell the cell phone how many parts there are. The end user's cell phone will combine the message parts into one message.

Carrier-specific parameters and requirements:

Where possible, OpenMarket removes the complexity of sending messages to multiple carriers. However, there are several carriers where you services may need to provide additional parameters or use a different messaging workflow. For information on these, please see US Carrier-Specific Requirements. The specific parameters are:

Optional parameters you can use for any request type:

  • smsfrom: sets the originator for the message—this parameter is mandatory for standard rate messages in all regions bar the US
  • submitid: used to send broadcast SMS messages
  • report: sets the delivery reports you want for the message
  • response: (for single-recipient requests only) changes the format of the HTTP response from the SMS Gateway
  • note, subaccount: optional reporting notes that you can add to the request
  • vp, billingsingleshot: alters the validity period and billing for the SMS message

Examples:

This request sends the message “γεια!” with report=7 set to enable the SMS Gateway to send delivery reports for the generated SMS message:

http://sms.openmarket.com/sms/v1/send?user=MyMXOneAccount&pass=P4ssw0rD&smsto=12515550100&smsucs2=03b303b503b903b10021&report=7