Things to Know

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

• Types of message requests you can send
• How we set up your accounts
• Basic authentication
• Data security
• Character encoding
• Using message originators
• Testing your integration with OpenMarket
• Getting message status
• When and how messages are retried
• Single and multipart messages
• Tracking multipart messages

Types of message requests you can send

Using the v4 SMS API you can send regular SMS messages and branded messages. Because branded messages contain your company brand/logo, they are processed by both our SMS and RCS platforms.

For more information on our Branded Messaging service, see Branded Messaging.

How SMS messages are delivered

Regular SMS messages are delivered via one of these sources (originators):

• Short code
• Long code (text-enabled toll-free number or landline, and 10DLC)
• Alphanumeric code

We provide delivery receipts when possible so you know which messages weredelivered and when. The receipt data is also available in the SMS Detailed report.

Note: SMS messages sent from a 10DLC source (originator) are subject to analysis for spam. Any messages identified by OpenMarket's spam filter will result in a 607 response. Such messages are not retryable. If you receive a 607 and feel that your message was falsely identified as spam, submit a ticket to OpenMarket Support.

How branded messages are delivered

Because branded messages contain your logo and brand, our SMS platform hands them to our RCS platform for delivery. It processes a branded message request similar to an RCS message request. It evaluates whether the destination number (the end user's device) is RCS-capable and if it is, delivers the branded message to the device. For destination numbers that are not RCS-capable, the platform routes the message back to the SMS platform and the message is delivered as a regular text message.

Because Branded Messaging uses both SMS and RCS, you need a transport mechanism for each channel: a short code for SMS and the bot for RCS. To represent the bot in a 'send SMS' request, you'll use a Campaign ID that we provide to you once registration is complete.

We provide delivery receipts for all messages delivered as text messages. The receipt data is also available in the SMS Summary and SMS Detailed reports. For the branded messages that are delivered via RCS, you'll use the RCS Detailed report to see this information:

• Delivered date — The time and date (in UTC) when the end user received the message.
• Read date — Date on which the message was read by the end user.
• Updated date — The time and date (in UTC) when the most recent event happened related to this message.

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 sending branded 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.

Your credentials for using OpenMarket services are configured for you. When you send a request, our system checks to make sure that the authentication credentials are valid and that the corresponding user has the required permissions to access the specific API.

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) 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)

Including custom fields in message requests

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 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 always provide a synchronous response to message requests so you know whether a request was accepted or rejected.

We use standard HTTP codes to indicate status. In addition we return are own response codes, which you can find documented on each operation's page.

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:

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 choose the appropriate originators based on where you intend to send messages.

• 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 considered two-way, so you'll need to use short codes until 10DLC numbers become available.

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.

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.

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.

Part one

{
   "deliveryReceipt" : {
      "mtStatus" : {
         "ticketId" : "03155-0331L-1439U-51SLFX",
         "deliveryDate" : "2016-03-31T20:04:18.000Z",
         "code" : "4",
         "description" : "Message delivered",
         "mobileOperatorId" : 383,
         "segmentNumber" : 1,
         "totalSegments" : 3,
         "destination": {
            "address": "12515550123",
            "mobileOperatorId" : 383,
            "alpha2Code" : "US"
         },
         "source": {
            "ton" : 3,
            "address" : "222111"
         } 
      },
      "type" : "final"
   }
}

Part two

{
   "deliveryReceipt" : {
      "mtStatus" : {
         "ticketId" : "03155-0331L-1439U-51SLFX",
         "deliveryDate" : "2016-03-31T20:04:23.000Z",
         "code" : "4",
         "description" : "Message delivered",
         "mobileOperatorId" : 383,
         "segmentNumber" : 2,
         "totalSegments" : 3,
         "destination": {
            "address": "12515550123",
            "mobileOperatorId" : 383,
            "alpha2Code" : "US"
         },
         "source": {
            "ton" : 3,
            "address" : "222111"
         } 
      },
      "type" : "final"
   }
}

Part three

{
   "deliveryReceipt" : {
      "mtStatus" : {
         "ticketId" : "03155-0331L-1439U-51SLFX",
         "deliveryDate" : "2016-04-03T11:21:20.000Z",
         "code" : "810",
         "description" : "Failed message delivery",
         "mobileOperatorId" : 383,
         "segmentNumber" : 3,
         "totalSegments" : 3,
         "destination": {
            "address": "12515550123",
            "mobileOperatorId" : 383,
            "alpha2Code" : "US"
         },
         "source": {
            "ton" : 3,
            "address" : "222111"
         } 
      },
      "type" : "final"
   }
}