Before You Begin
Getting Started with Global SMS
If you're new to OpenMarket's messaging services, look through this section to familiarize yourself with the basic features of the platform and how to make use of them.
Choose how to integrate with OpenMarket
Using either the HTTP API or SMPP, you can send and receive SMS messages. Usually our customers choose one technology or the other based on their in-house expertise, but a few of our customers use both HTTP and SMPP. We recommend using SMPP only if you have experience using it, since integrating with SMPP is more complex than HTTP.
Our Global SMS service lets you send both one-way and two-way messages almost anywhere in the world. The HTTP API is fully RESTful and supports both JSON and XML operations. Both the HTTP API and SMPP support automated selection of message originators, simple character encoding, efficient tracking of multipart (concatenated) messages, and a 99.99% SLA. The SMPP service supports version 3.4 of the SMPP protocol.
If you are an existing OpenMarket customer and are using one of our legacy SMS APIs, you may continue to use them. However we urge you to consider migrating, as the new capabilities in v4 will not be back-ported. See the HTTP Global SMS API Release Notes for more information, and contact your OpenMarket account manager when you're ready to make the switch.
Decide whether to send traditional SMS messages or branded messages
A traditional SMS message contains only text, and it can include a link to external content. Using our SMS service you can send a message that's longer than the standard 160 characters. (See Things to know for more information on multipart messages.)
In contrast, a branded message contains your company's logo and colors along with the message text. There are several benefits to branded messages:
- They are more recognizable to end users
- They are more visible inside the message inbox
- Data can be captured about how end users interact with them
- More difficult for fraudsters to spoof
Our Branded Messaging service utilizes both our SMS and RCS messaging platforms. When you request to send a branded message, you'll include a special parameter called campaignId that tells our SMS platform to hand the message to the RCS platform. It then determines which destination phone numbers are capable of displaying the branded message and which aren't. The RCS platform delivers the branded message to the RCS-capable phones and sends the other messages back to the SMS platform for delivery as traditional SMS messages.
Branded Messaging requires additional configuration on your OpenMarket account. Contact your OpenMarket account manager to learn how to get started.
Authenticate with OpenMarket
Only secured connections using Transport Layer Security (TLS) versions 1.2 and 1.1 are allowed for both the HTTP and SMPP APIs. For HTTP this means using HTTPS connections over secure port 443.
If you're using SMPP, authentication is performed when a Bind operation is initiated. The Bind operation passes your account ID and password in the request, and upon authentication, a connection is created between you and us.
For more information about authenticating, see:
Use Automated Originator Selection
With AOS all you need to provide in the 'send message' request is the destination mobile phone number. Based on that we determine the country and then use the matching originator. If you use multiple originators for the same region, we may need more information in order to choose the correct originator for a particular end user.
If you send a message without a source address and A0S cannot find an appropriate originator, the message will fail with one of these 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:
|
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:
|
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:
|
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:
|
|
Provisioned message originators:
|
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
Message requests can fail at two points: the mobile operator and the handset. OpenMarket and most mobile operators have robust retry methods to ensure that the best effort is made to contact a handset.
For messages that fail at the mobile operator, we check whether the message is retryable and, if it is, we retry it. For messages that fail to reach the handset, most mobile operators will attempt to deliver a message for up to three days. If they cannot reach the handset, they will usually return a delivery receipt to us indicating that the message expired. If you are receiving delivery receipts, then we pass this information to you. The length of the retry period depends on whether you've also set a validity period for the message.
For information about how to specify retry parameters, see HTTP Global SMS API and SMPP Global SMS.
Data security
OpenMarket takes the security of your data seriously. Yearly, third-party security audits of our SMS platform are conducted annually 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.
IP 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. A whitelist is only used with SMPP. HTTP does not use whitelists.
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)
Get technical support
All of our technical support engineers and technicians are OpenMarket employees and are available by phone, email, and our web-based ticketing system. To contact technical support, send an email to support@openmarket.com or call one of our regional numbers:
- US: +18772772801
- UK: +442089878855
- Australia: +61293322141