HTTP Global SMS API

Making SMS Requests using HTTP

The Global SMS operations provide a programmatic way to engage with end users via SMS. Read this page to find out how to use the operations, and try out the operations using cURL. We'll be using JSON in the examples.

Using this SMS API you can also send branded messages using either JSON or XML.

Before we begin

Before beginning, you'll need an SMS account provisioned. Make sure to ask for access to our testing interface, called the Customer Integration Environment (CIE). We'll use this in the requests below. However, if you are ready to test these requests with real phone numbers, just remove "-cie" from the URLs in the example cURL calls.

You'll also need to let us know what regions you want to send messages (e.g. UK and Ireland) and a default message originator (e.g. your short code or other number) to use — if you're just starting out, and you're not messaging the US or Canada, you can use an alphanumeric string like "ACME" as your originator. Alternatively, we can offer a demo number in some regions like the UK or the US.

Sending your first SMS

(Operation: Send an SMS)

In this request we'll assume that you've only got one message originator set in your account. This means you don't need to send any "source address" details.

1. Create a text file for the POST body

Create a text file called send-sms.txt and copy in the example below.

If your account is provisioned for the US, you can leave the phone number as-is. Otherwise, change the number to any suitable number for your region — for447700900765 for the UK. Make sure that you include the country code; e.g. so that the number is in international format. Don't add a "+" character. Since we're messaging the CIE, you don't need to worry that this message will reach a phone.

{
   "mobileTerminate" : {
      "message" : {
         "content" : "Hello",
         "type" : "text"
      },
      "destination" : {
         "address" : "12515550145"
      }
   }
}

2. Use cURL to send the message

Make a request using the following sample cURL. You'll need to:

Ensure you're in the same folder/directory as the text file.
Replace the accountid:password with your OpenMarket account ID and password (note that this is sent using Basic authentication).

This request is sent to the CIE — if you are ready to send a message to a real phone number, just remove "-cie" from the URL.

curl -s -D - -X POST -H "Content-Type: application/json" --user accountid:password --data-binary @send-sms.txt https://smsc-cie-wdc.openmarket.com/sms/v4/mt

In the cURL, the "-s -D -" prints the HTTP response code, headers and response body to screen. For additional information useful when troubleshooting, replace "-s -D -" with "-v".

Response back from OpenMarket

For successful requests, OpenMarket returns an HTTP 202 response.

HTTP/1.1 202 Accepted
Content-Length: 0
Location: http://smsc-cie-wdc.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX
Content-Type: application/json;charset=UTF-8
X-Request-Id: BAC=DE1396F5-C67B-46CF-A488-DBECEB8164D0
Server: Jetty(8.1.14.v20131031)

The location includes a ticket ID (in the example: 03155-0331L-1439U-51SLFX). Make a note of this ID.

Querying the message status

(Operation: Get Message Status)

Once you've sent the Send SMS request, you can query its delivery status. Make a request using the following sample cURL. You'll need to:

Replace "03155-0331L-1439U-51SLFX" with the ticket ID you just received.
Replace the accountid:password with your OpenMarket account ID and password.

curl -s -D - -X GET -H "Accept: application/json" --user accountid:password https://smsc-cie-wdc.openmarket.com/sms/v4/mt/03155-0331L-1439U-51SLFX/status

Response from OpenMarket

For successful requests, OpenMarket sends an HTTP 200 response. The response body contains the message status information including the ticket ID.

HTTP/1.1 200 OK
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8

{
   "mtStatus": {
      "ticketId": "03155-0331L-1439U-51SLFX",
      "code": "4",
      "description": "Message successfully delivered",
      "deliveryDate": "2016-07-01T20:04:18.000Z",
      "mobileOperatorId": 383
   }
}

Receiving a delivery receipt

(Operation: Receive Delivery Receipts)

In our previous Send SMS request, we didn't request a delivery receipt, so one was never generated. So let's send a request that asks for a delivery receipt.

1. Create a text file for the POST body

Create a text file called send-sms.txt and copy in the example below. Make sure to change the url to your own endpoint.

{
   "mobileTerminate" : {
      "message" : {
         "content" : "Hello",
         "type" : "text"
      },
      "destination" : {
         "address" : "12515550145"
      },
       "delivery": {
         "receiptRequested": "final",
         "url": "https:my.example.com/receiver.php"
      }						
   }
}

2. Use cURL to send the message

Make a request using the following sample cURL. You'll need to:

Ensure you're in the same folder/directory as the text file.
Replace the accountid:password with your OpenMarket account ID and password.

curl -s -D - -X POST  -H "Content-Type: application/json" --user accountid:password --data-binary @send-sms.txt https://smsc-cie-wdc.openmarket.com/sms/v4/mt

As long as the request was successful (HTTP 200), you'll receive a delivery receipt shortly after that will show that the message was delivered successfully. The ticketId identifies the original message request.

POST / HTTP/1.1
User-Agent: OpenMarket
X-API-Version: 4 
Host: smsc.openmarket.com
Content-Type: application/json; charset=UTF-8
Content-Length: 424
Connection: close

{
   "deliveryReceipt" : {
      "mtStatus" : {
         "ticketId" : "03155-0331L-1439U-51SLFX",
         "deliveryDate" : "2016-07-01T20:04:18.000Z",
         "code" : "0",
         "description" : "Message successfully sent to mobile operator",
         "mobileOperatorId" : 383,
         "destination": {
             "address": "12515550145",
             "mobileOperatorId" : 383,
             "alpha2Code" : "US"
         },
         "source": {
            "ton" : 3,
            "address" : "222111"
         } 
      },
      "type" : "final"
   }
}

Finding out the Mobile Operator

(Operation: Mobile Operator Lookup )

If you're messaging in the US or Canada, you may also want to use our Operator Lookup request. This tells you more about the number and the related mobile operator. Make a request using the following sample cURL. You'll just need to replace the accountid:password with your OpenMarket account ID and password.

curl -s -D - -X GET  -H "Accept: application/json" --user accountid:password https://smsc-cie-wdc.openmarket.com/sms/v4/preview/12515550145

Response from OpenMarket

For successful requests, OpenMarket sends an HTTP 200 response. The header contains an X-Request-Id, while the response body contains the lookup data.

HTTP/1.1 200 OK
X-Request-Id: 001-3-72879E62-6586-4F77-9E7B-1E74386F0223
Content-Type: application/json;charset=UTF-8

{
   "preview": {
      "destination": {
         "countryCode": "1",
         "phoneNumber": "12515550145",
         "alpha2Code": "US",
         "wireless": true 
      },
      "operator": {
         "mobileOperatorId": 383,
         "mobileOperatorName": "AT&T",
         "textLength": 160,
         "binaryLength": 140,
         "unicodeLength": 70,
         "wapPush": true
      }
   }
}