HTTP Global SMS API

Benefits of Migrating to the Global SMS API

This page describes the benefits of migrating from an existing legacy HTTP SMS API to our HTTP Global SMS API.

If you're currently using OpenMarket's v3 HTTP or UK HTTP SMS (also known as the MX API) APIs, then this information is for you. If you're new to OpenMarket, see the Overview to find out how to connect to us.

Note: 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. Future feature development will be focused on the Global SMS API.

OpenMarket's Global SMS API enables you to send both one-way and two-way messages globally. It supports enterprise-level features such as automatically selecting the originator, character set, and message length to use; and providing detailed message delivery tracking. Benefits include:

Our highest level SLA

We offer a contractual SLA of 99.99% for the HTTP Global SMS API.
Increased messaging capacity

This API supports higher traffic volumes than the UK HTTP SMS API.
RESTful operations offering JSON and XML

Our Global SMS API is RESTful, and you can choose to use either XML or JSON when integrating.

For customers transitioning from the UK HTTP SMS API we recommend using the JSON interface as it is simpler to read and is the standard format for OpenMarket APIs.
Security through Basic authentication

Requests are authenticated through Basic authentication in the request header.

The Content-Type header field is required in requests (and returned in responses) to identify the content as either XML or JSON format.
```
POST /sms/v4/mt HTTP/1.1
Host: smsc.openmarket.com
Content-Type: application/xml; charset=UTF-8
Authorization: Basic VXNlcm5hbWU6cGFzc3dvcmQ=
```
Automated originator selection

Sending SMS messages worldwide means using the right message originator (short code or other type of number) for each country. With the Global SMS API, we have the ability to select the correct originator for each message you send, relieving your system of this work. See also Automated Originator Selection and Message originators.
Simplified text encoding and additional supported character encodings

In v4, your application submits all text message requests using UTF-8 encoding. Our system examines the message text and determines which character set to use given the mobile operator that’s delivering the message to the handset. The objective is to use the character set that best preserves the characters in the message.

However, you may have cases where the message text you want to send is stored or created using a different encoding. To support this, you can send the message content using these encodings/sets: GSM, Latin-1, UTF-8 and UTF-16. We will re-encode this as required to best match what the mobile operator supports. See Character sets and encodings.
Better multipart message tracking

Messages split into multiple parts are easily tracked in Get Message Status responses and in delivery receipts. Each part of a multipart message is labelled with the same ticket ID (smsid), and each delivery receipt includes segmentNumber and totalSegments identifying the part.

In a Get Message Status response, we provide delivery receipt details for all parts of a multipart message. The request will also provide a summary code and description for the entire message. You can request the status of a message for up to five days.

In the SMS Activity Search available in our Customer Center, a search returns all parts of a multipart message in the search results.
New per-request identifier in headers from OpenMarket

Successful and unsuccessful requests include an X-Request-Id field in the header, for improved troubleshooting with OpenMarket's Customer Success Managers and Technical Support. This identifies the specific request transaction. It will look similar to:
```
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
```
Support for two free-form reporting fields

In v4 requests, you can include two optional fields, note1 and note2, in the request body.

New to UK HTTP SMS API users only

Simpler accounts

The Global SMS API does not require you to use separate accounts to send messages in specific regions or to specific mobile operators. For more information, see API Account Differences.
Ability to query the message status

The Global SMS API provides a Get Message Status operation, enabling you to query the current message delivery status for a chosen message. You can use this request up to five days after the message was submitted. If your message was split into multiple parts, then you will receive data about each part, including an individual receipt code and description.

For more information, see Get Message Status operation.
Testing via our Customer Integration Environment (CIE)

The OpenMarket CIE lets you test your integration with the Global SMS API without sending messages to the mobile operators. Operations you can test are: Send an SMS, Get Message Status, and Mobile Operator Lookup. Testing using the CIE confirms that you are using validate syntax and values in your requests, and that your platform can successfully receive a synchronous response from OpenMarket.

When submitting a test request, you use the same details you intend to use with the production environment. The CIE checks whether their are errors in the request and responds accordingly.

See Testing Your SMS Integration for full details about how to use the CIE.