HTTP Global SMS API

Things to Know

Before you start using the Global SMS API, familiarize yourself with these features:

How we set up your accounts

When you sign on with OpenMarket, your account manager will work with you to make several decisions:

  • Which OpenMarket product(s) you intend to use
  • Whether you're sending messages within or outside your country or territory
  • Whether you're sending one-way or two-way messages
  • Whether you're using HTTP or SMPP (or both)
  • What type(s) of originators you're using (short codes, VMNs, etc.)

When we set up your OpenMarket account, we'll provide you with the user and application accounts that you need with access to the products you're licensed to use. We set permissions on each account to ensure it accesses only the resources it needs. Accounts for applications are normally numbers, while accounts for people are normally a business email address. The following tables gives examples.

Account ID / Name

Description

123-456-789-12345

An ID specifically enabled for SMS messaging.

Used in any Global SMS API request (POST or GET), such as to send an MT message to any end user.

matthew@example.com

Enables Matthew to access Customer Center tools and reporting. OpenMarket Support will recognize Matthew when he emails using this address.

As Matthew is in Finance, he is able to see all reports including financial reports.

Jinghua@example.com

Enables Jinghua to access Customer Center tools and reporting. OpenMarket Support will recognize Jinghua when she emails using this address.

As Jinghua is in development, she is restricted from seeing financial reports.

Your credentials for using OpenMarket operations and applications are provisioned by OpenMarket's Identity Service and configured with individual permissions. When one of our operations or applications receives a request, it checks to make sure that the authentication credentials are valid and that the corresponding user has the required permissions to make that API call.

Note: If you're using MEP you will be able to create and administer your own user accountsAuthenticating with OpenMarket

Accepting asynchronous message and notifications from OpenMarket

When you provision a messaging account with us, make sure you provide us with a default URL for receiving message requests and other types of requests from OpenMarket.

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)

What if I can't seem to receive a request?

If you do not receive requests from us to an HTTPS URL, but you can receive them over standard HTTP, a possible cause is that we do not recognize and trust your server's security certificate. You must obtain an additional certificate from one of the trusted certification authorities.

Authenticating with OpenMarket

Basic authentication

At the request level, most of our operations require Basic authentication.

When you submit an API request, usually we authenticate you using Basic authentication. To use Basic authentication, you'll need to base64-encode your OpenMarket account ID and password. You must encode it in the format accountid:password. For example:

abcAccountId:123Password

Looks like this when encoded:

YWJjQWNjb3VudElkOjEyM1Bhc3N3b3Jk

In the header, specify "Authorization: Basic" and then your encoded details. For example:

Authorization: Basic YWJjQWNjb3VudElkOjEyM1Bhc3N3b3Jk

If your account ID was "123-123-123-12345", and your password was "Secure123", then you would encode "123-123-123-12345:Secure123". In the header this would look like:

Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=

Your account ID and password are both case-sensitive.

Data security

OpenMarket takes the security of your data seriously. Yearly third-party security audits across all our products are conducted by a qualified independent security assessor.

When connecting to the mobile operators, we utilize industry-standard encryption technologies appropriate to the sensitivity of the information being transmitted. This means we use either VPN tunnels or SSL (TLS v1.2 or v.1.1) to encrypt data being sent over public networks or private networks if required.

Whitelisting

For extra security you can provide a whitelist of IP addresses from which OpenMarket will accept API requests for your account. With this added safeguard, a request will fail if it is submitted from an IP address that is not on your whitelist.

In order to provision an IP whitelist, contact OpenMarket Support.

IP filtering

OpenMarket sends MO messages, delivery receipts, and other notifications from the IP Address ranges listed below. We may route traffic through any of these IP addresses, without notice, to ensure that services remain highly available

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)

Message requests

Including your own identifiers

When you submit a request to send a message, you may want to include your own message identifiers, such as your own ticket or transaction IDs, or campaign and program names. The Global SMS API provides two fields that allow you to do this: note1 and note2.

These fields are included in the SMS Detailed Data Source report and are returned in delivery receipts.

Formatting phone numbers

In your message requests you must include the country calling code (or dial-in code) with the end user's phone number. For example:

  • US numbers must include "1" at the start: 12125550123
  • UK numbers must include "44" at the start: 447700900750
  • Uzbekistan numbers must include "998" at the start: 998901234567

These codes are defined in the ITU-T standards E.123 and E.164, and are also available on Wikipedia.

Your text-enabled virtual mobile number (VMN), toll-free number, or landline number must also use this format in the source address. Do not include a "+" character with a number.

Responses and requests from OpenMarket will also use this format for phone numbers.

Responses from OpenMarket

We'll always provide a synchronous response to your API requests, indicating whether the request was accepted or rejected.

We use standard HTTP status codes to indicate whether a request was successful. As well as the HTTP status codes, OpenMarket returns are own response codes, which you can find documented on each operation's page.

HTTP code

Description

200-299

Indicates that the request was accepted.

However, even if a request is accepted, there might be in issue with processing the request further.

400-499

Indicates that there was an issue with the request.

500-599

Indicates that there was a systems issue.

Troubleshooting messages

We provide a tool called SMS Activity Search that lets you obtain status and other information about the messages you send. To use the tool, you need to log in to OpenMarket's Customer Center and select the Tools menu. For more information see SMS Activity Search.

Identifiers returned by OpenMarket

Whenever you send a request, we'll respond with unique identifier so that you can match future reports and notifications. The primary ones are:

  • X Request ID — This identifies a request in OpenMarket's systems. Our SMS, MMS, and related operations all include this in the request header. This ID is useful when you need to contact OpenMarket Support regarding a specific transaction.
  • Ticket ID (SMS)  — This identifies an accepted SMS message request. If your message is split into multiple parts, they will share the same ticket ID in your delivery receipts. Ticket IDs are also used to identify MO messages.

Other operations return additional unique IDs as required.

Character encoding

Choosing the right character encoding for a message and mobile operator can often be confusing or frustrating to deal with. So to make life simpler, OpenMarket ensures that the best possible character encoding is used for each message. All you need to do is send us the message; we'll do the rest.

Your message requests to us should use UTF-8 character encoding. If you're generating your message text using another encoding, you can still send us the text using as is — just use charset in the request body to specify the encoding.

Regardless of whether you've sent the message using UTF-8 or another encoding, we will convert the text content to use the encoding that's optimal for the mobile operator. For many mobile operators and messages, we use GSM. However this is not the case if:

  • The mobile operator requires a different encoding
  • Your message uses characters outside the GSM set

Note: The encoding you use may impact whether your message is sending single and multipart messages (see Tracking multipart messages below). That's because character encoding (or set) determines the data size of the message.

Before forwarding a message, OpenMarket determines what encoding the mobile operator accepts, and then what encoding best matches the message contents. The two encodings that are most widely accepted by the mobile operators are:

  • GSM — each character requires 1 byte of data
  • UCS-2 — each character requires 2 bytes of data

Options for charset

If you choose to send a hexadecimal-encoded text message, you'll need to identify what character encoding you've used. The options are:

Character set

Description

GSM

We support GSM 7-bit default alphabet and extension table of 3GPP TS 23.038 / GSM 03.38.

GSM requires 1 byte per character, but only supports limited range of languages and characters.

Latin-1 (ISO-8859-1)

Requires 1 byte per character, and supports most Western European languages.

UTF-8

This requires between 1 to 4 bytes of data for each character. See the Wikipedia article: https://en.wikipedia.org/wiki/UTF-8.

UTF-16 using big-endian encoding

The UTF-16 basic and supplementary multilingual planes are supported. See the Wikipedia article: http://en.wikipedia.org/wiki/UTF-16.

GSM character set

See also the Wikipedia article for more information: http://en.wikipedia.org/wiki/GSM_03.38.

Modified Latin-9 character set

This character set is based on ISO-8859-15 (Latin-9). However, in order to fully cover the GSM character set and also has different characters at 0xA8, 0xA4, 0xA6, 0xB4, 0xB8, 0xBC, 0xBD, 0xBE. The characters not present in the GSM character set are shown on a grey background in the table below.

The acronyms in the table are:

  • LF — line feed
  • FF — form feed
  • CR — carriage return
  • SP — space
  • NBSP — non-breaking space
  • SHY — soft hyphen

See this Wikipedia article for more information about the Modified Latin-9 character set: https://en.wikipedia.org/wiki/ISO/IEC_8859-15.

Using message originators

When you sign up with OpenMarket, your account manager will work with you to specify where you're sending messages and the originators you want to use.

  • For one-way messaging, you need to provide a list of the countries you want to message, and which originator(s) to use. You can use the same originator globally, or use different originators for different regions. In most regions, you will not need to provision these numbers and alphanumeric strings with the mobile operators.
  • For two-way messaging, you need to provide us with the numbers provisioned in that region. OpenMarket can work with you to provision short codes, VMNs, and other types of numbers with mobile operators.

Note: In the US and Canada, all messaging is two-way.

For example, say you want to send messages to end users in the US, UK, New Zealand, and Australia. You would tell us whether you're sending one-way or two-way messages, and the number or alphanumeric string for each originator, such as 222111 for a US short code, or KIWI321 for a New Zealand string.

When choosing a message originator, we follow these rules:

  • We choose a national (local) originator whenever possible over one from another country.
  • We reject a message request if the interaction type (one-way or two-way) isn't available for your account in the specific region.
  • We reject a message request if there's a conflict between the interaction type and the source address the number or string that identifies you as the sender). For example, we would reject a message with the source address, "ACME" (an alphanumeric string), and interaction type, two-way.

If you send a message without a source address, and the SMS service cannot find an applicable source address associated with your account using Automated Originator Selector, a mobile-terminated message can then fail with one of two delivery receipt error codes:

  • 593: Cannot determine which message originator to use
  • 597: Account has no provisioned address that can reach destination

The following examples illustrate what values to include in a message request. As you can see, you include source address or interaction type only if you need to differentiate between two similar originators that are provisioned in the same region.

Provisioned message originators:

  • 98765, short code, UK
  • 3312303120, VMN,France
  • 66655, short code, US

In this example, if any message request is sent to a UK, French or US end user, then OpenMarket will send the message using the message originator for that region. You would not need to include source address or interaction in the request.

Provisioned message originators:

  • 654321, short code, Puerto Rico
  • 442089878855, VMN, Global (note, this is a UK number)
  • 18772772801, toll-free, US and Puerto Rico

In this example, it is possible for all the message originators to reach Puerto Rico end users.

However, OpenMarket would choose the Puerto Rico short code by default, as a local short code takes precedence over a UK number (even if it is global) and a North American toll-free number.

You would not need to include source address or interaction in the request, unless you wanted the message to use a different originator.

Provisioned message originators:

  • MYBRAND, alphanumeric string, India
  • 34911062005, VMN, Spain
  • 420736370463, VMN, Czech Republic

In this example, if any message is sent to Spain, India, and the Czech Republic, then OpenMarket will use the provisioned message originator. You would not need to include source address or interaction in the request.

However, if you send the MT with a value of two-way for interaction:

  • Messages sent to Spain end users are accepted.
  • Messages sent to Czech Republic end users are accepted.
  • Messages sent to India end users are rejected. The message originator for India is not two-way, and there is no other number provisioned for India.

Provisioned message originators:

  • 12345, short code, France
  • 45678, short code, France

In this example, if a message is sent to a French end user, then the message request must include a source address. This is because there is no way for OpenMarket to determine which of the short codes you would prefer us to use.

If the request doesn't include source address, then OpenMarket responds with status code 593, “Cannot determine which message originator to use”.

When and how messages are retried

OpenMarket and most of the mobile operators have robust retry methods to ensure that the best effort is made to contact a handset. The length of the retry period depends on whether you've also set a validity period for the message.

Retries by the mobile operators

As long as a request is to an active mobile phone account, most mobile operators will attempt to deliver a message for up to three days. If they fail to reach the handset, then they will generally return a delivery receipt of code 811: Message expired. If you requested delivery receipts then we pass this code to you in the receipt.

Retries by OpenMarket to the operators

If a mobile operator fails a message request, OpenMarket will check whether it is retryable. If it is retryable, we will troubleshoot the request and then resubmit it.

For example, if your request specifies the wrong mobile operator, the operator will return an "Invalid destination" error. OpenMarket will perform an operator lookup to check whether this is the issue and, if it is, we will re-submit the message with the correct operator.

We will retry messages for up to 24 hours — approximately 20 retry attempts. If this fails, then you will receive a final delivery receipt (if requested) with the failure code.

When OpenMarket is retrying a message, the message state is “Retrying” in the SMS Activity Search results on Customer Center.

Note: It is very rare for a mobile operator to be unreachable for long and without notice; however, OpenMarket does have robust systems in place to ensure that messages are queued and correctly retried in these instances.

Using the validity period option

Your MT message requests can include a validity period for the message. This enables you to specify an expiry time, after which you do not want the end user to receive the message. This is useful when your message is time-sensitive, such as a deal or feedback request, and you do not want extended retrying of a request.

Note that not all mobile operators support setting an expiry time and will attempt to deliver the message until they reach their own limit. Ask your OpenMarket account manager if you need to know about the behavior of specific mobile operators or regions.

Retries by OpenMarket to your systems

If we cannot initially reach your systems to deliver an MO message or delivery receipt, then we will retry the request for up to 24 hours — approximately 20 retry attempts.

Retrying your requests to OpenMarket

When considering your retry strategies, it's important to note that if you receive an HTTP transaction timeout, it is still possible that we received the request. Therefore, you should decide whether you'd prefer the end user to potentially receive the message twice, or to not receive the message at all.

For retrying requests when we have responded with a temporary system error, we suggest resubmitting the request after a minimum of 10 seconds. Make sure your retry strategy uses a back-off algorithm for further retries and contact OpenMarket Support if you still continue to receive an error.

Testing your integration with OpenMarket

Our Customer Integration Environment (CIE) lets you test your integration with the Global SMS API. You use the same account ID and password you use when submitting messages to the production environment. You can use the same short codes, long codes, and alphanumeric source addresses in the CIE that you intend to use in production. Messages submitted to the CIE are not sent to mobile operators or end users.

Testing in the CIE will validate MT syntax and values. If no errors are found, the CIE responds with a ticket ID. If an error is found, the CIE responds with an OpenMarket response code.

What you can test

You can test these requests:

  • Sending an MT message
    • Global SMS
    • US and Canada standard rate SMS
  • Getting the status of an SMS
  • Getting the operator for a number
  • Receiving delivery receipts

You cannot test receiving MO messages.

Constraints to be aware of when using the CIE

  • MT messages are not forwarded to mobile operators or end users, so you will not receive messages on a handset
  • Reporting is not supported
  • The CIE is not intended for performance or load testing

Prerequisites

No special provisioning is required in order to use the CIE unless you want to use it for demo purposes or to do any kind of performance testing. For these cases, contact your account manager to make sure your OpenMarket account is properly provisioned.

Connecting to the CIE

Use the same request as you would for the production environment, but change the domain to:

https://smsc-cie.openmarket.com

You can find the full path name on each operation page. Unencrypted HTTP is not allowed.

If no errors are found, the CIE responds with a ticket ID. If an error is found, the CIE responds with an OpenMarket response code.

Getting message status

The Get Message Status operation lets you request delivery receipt details for all parts of a multipart message. The response also provides a summary code and description for the entire message. You can request the status of a message for up to five days.

Example (JSON)

When your message is initially accepted, our synchronous response will include one ticket ID. In this example, the ticket ID is 03155-0331L-1439U-51SLFX.


HTTP/1.1 202 Accepted..Server: Apache-Coyote/1.1
Location: http://smsc-cie.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tue, 31 Mar 2016 18:39:51 GMT
Connection: close

When you get the message status, our response includes all the information, as known, for each part. The top level code and description provide the current status of the entire message.

  • Code 830, "Partial message delivery failure", means that at least one of the message parts has not been successfully delivered.
  • Code 831, "Awaiting complete message delivery status", means that the mobile operator has not returned a delivery receipt for one or more of the message parts. For example, you will get this code if one message part was successfully delivered but we do not have a receipt for the second part. However, if any message part fails delivery, then code 830 is returned.

Any other code means that the result for all parts of the message is the same. For example, if it is a "success" code of 0 or 4 then all parts were successfully delivered; if it is the same code to indicate a problem then all parts experienced the same problem.

In this example, the first two parts have been successfully delivered; however, we are still awaiting a delivery status update for the third part.

{
   "mtStatus": {
      "ticketId": "03155-0331L-1439U-51SLFX",
      "code": "831",
      "description": "Awaiting complete message delivery status",
      "totalSegments" : 3,
      "destination": {
         "address": "12515550123",
         "alpha2Code" : "US"
      },
      "source": {
         "ton" : 3,
         "address" : "222111"
      },
      {
      "segments":[
            {
            "segmentNumber":1,
            "deliveryDate":"2016-03-31T20:04:18.000Z",
            "code":"4",
            "description":"Message delivered"
            },
            {
            "segmentNumber":2,
            "deliveryDate":"2016-03-31T20:04:18.000Z",
            "code":"4",
            "description":"Message delivered"
            }
            {
            "segmentNumber":3,
            "code":"3",
            "description":"Message accepted by mobile operator. Awaiting receipt"
            }
         ]
      }
   }
}				
				

Single and multipart messages

When sending a multipart message, you will be charged for each message segment, not the message as a whole. Therefore, if your message is split into four segments you will be charged for each of those four segments.

The mlc option identifies what you would like to happen if your message is longer than the maximum single part message that the mobile operator supports. The options are:

  • Reject the message — OpenMarket does not send the message on to the end user.
  • Truncate the message —This means the end user will get a single part message that finishes at the maximum length that the mobile operator supports.
  • Segment the message —This means that OpenMarket sends a multipart message. Note that if your message is larger than the maximum multipart message allowed by the mobile operator, we will reject the message.

Note: When you submit an SMS message request, our synchronous reply informs you whether the request was accepted. However, it does not identify whether the message needs multiple parts. This is because we need to check the message's character use against the mobile operator's constraints before we can process the message.

Example

Imagine sending a Shakespearean sonnet to a UK operator that is 622 GSM characters in length. The table below shows what the end user would receive based on the mlc value.

mlc option

Outcome

reject

Your submit request would be rejected.

truncate

OpenMarket truncates the message to a single part of 160 characters:

Shall I compare thee to a summer's day? Thou art more lovely and more temperate: Rough winds do shake the darling buds of May, And summer's lease hath all too s

segment

OpenMarket segments the message into 5 parts, with 4 of approximately 153 characters and another of 10 characters. Most handsets will then display it as one long message.

Segment one:

Shall I compare thee to a summer's day? Thou art more lovely and more temperate: Rough winds do shake the darling buds of May, And summer's lease hath al

Segment two:

l too short a date: Sometime too hot the eye of heaven shines, And often is his gold complexion dimm'd; And every fair from fair sometime declines, By c

Segment three:

hance, or nature's changing course, untrimm'd; But thy eternal summer shall not fade Nor lose possession of that fair thou ow'st; Nor shall Death brag th

Segment four:

ou wander'st in his shade, When in eternal lines to time thou grow'st; So long as men can breathe or eyes can see, So long lives this, and this gives lif

Segment five:

e to thee.

You will receive delivery receipts for each part of the message. Each part is identified by the attribute segmentNumber. All the parts share the same ticketId.

Behavior when the operator does not support multipart messages

There are a few mobile operators that do not support multipart messaging at all. OpenMarket applies the same logic above for the mlc reject and truncate options. However, if you set mlc to segment, then OpenMarket will send the message as a series of single part messages. We do not add any UDH. Instead, we add a page numbering sequence to the start of each message to help the end user. This gives both the part number (p) and the total number of parts (t) in the format: "p/t:"; E.g.:

  • 1/5: Shall I compare thee...
  • 2/5: l too short a date...
  • 3/5: hance, or nature's...

For information about tracking multipart messages, see Tracking multipart messages below.

Tracking multipart messages

Messages split into multiple parts are easily tracked in status requests and delivery receipts.

Delivery receipts

Each part of a multipart message is labelled with the same ticket ID, and each delivery receipt includes segmentNumber and totalSegments identifying the part.

Example (JSON)

When your message is initially accepted, our synchronous response will include one ticket ID. In this example, the ticket ID is 03155-0331L-1439U-51SLFX.

HTTP/1.1 202 Accepted
Server: Apache-Coyote/1.1
Location: http://smsc-cie.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8
Content-Length: 0
Date: Tue, 31 Mar 2016 18:39:51 GMT
Connection: close

Once we've processed the message further, we split it into the necessary SMS parts, and in the right encoding for the mobile operator. As each part is successfully delivered (or fails), we return a delivery receipt. In this example, the message was split into three parts. The operator has successfully delivered the first two parts, but failed to deliver the third. You can see the segmentNumber increment, while totalSegments indicates there were three message parts. The ticket ID remains the same.