SMS API

APIs for use with SMS Gateways

Our REST SMS API and SMPP SMS API are included below. For further information on our SMS gateway for use with the UK, France, Germany, Spain, Italy and other locations, please see the Tyr SMS Gateway. If your application supports a different API, then you can use the One SMS API service to bridge between the API supported by your application and the APIs we provide.

REST API

REST calls can be made via HTTPS to send SMS to mobiles, and also to cancel, query and replace previously submitted SMS messages. Additional operations also allow for management of distribution lists, phonebooks, and mobile numbers for two-way SMS messaging and receiving SMS.

Webhooks allow for delivery receipts and inbound SMS received from mobiles to be sent to your application without the need to poll for the status of messages or newly received messages.

The REST API uses TLS v1.1, v1.2 and v1.3 (where supported) to ensure that transactions are secure between your application and the SMS gateway.

curl https://api.melroselabs.com/sms/message/ \
	--header 'x-api-key: [API_KEY]' --header 'Content-Type: application/json' \
	--data-raw '{ "source": "MelroseLabs","destination": "447712345678","message": "Hello World €£$" }'

{"transactionID": "1ccead78-6550-4aac-a6b4-a4942b908659"}

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.melroselabs.com/sms/message/',
  'headers': {
    'x-api-key': '[API_KEY]',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ "source": "MelroseLabs","destination": "447712345678","message": "Hello World €£$" })
};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body); // response is of type application/json
});

{"transactionID": "1ccead78-6550-4aac-a6b4-a4942b908659"}

import requests
import json

url = "https://api.melroselabs.com/sms/message/"
payload = {
	{ "source": "MelroseLabs","destination": "447712345678","message": "Hello World €£$" }
}
headers = {
  'x-api-key': '[API_KEY]',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = json.dumps(payload))

# response is of type application/json
print(response.text.encode('utf8'))

{"transactionID": "1ccead78-6550-4aac-a6b4-a4942b908659"}

<?php 
$data = { "source": "MelroseLabs","destination": "447712345678","message": "Hello World €£$" }

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.melroselabs.com/sms/message/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => $data,
  CURLOPT_HTTPHEADER => array(
    "x-api-key: [API_KEY]",
    "Content-Type: application/json"
  )
));

$response = curl_exec($curl);

curl_close($curl);

echo $response; // response is of type application/json
?>

{"transactionID": "1ccead78-6550-4aac-a6b4-a4942b908659"}

SMPP API

Short Message Peer-to-Peer (SMPP) v3.3, v3.4 and v5 are supported and the SMPP PICS (Protocol Implementation Conformance Statement) showing the level of support is provided. SMPP can be used to establish sessions over which SMS can be submitted (submit_sm PDU), queried (query_sm PDU), replaced and cancelled.

Delivery receipts are sent in SMPP sessions when messages reach a completion state and receipts were requested in the submit_sm. Inbound SMS from mobiles (MO SMS) are also sent via SMPP. The deliver_sm PDU is used for both receipts and inbound SMS.

The SMPP API can be used with TLS v1.1, v1.2 and v1.3 (where supported) to ensure that transactions are secure between your application and the SMS gateway.

To achieve maximum message throughput, there are a number of factors that can improve submission performance. Submission window size of up to 20 SMS should be used, coupled with multiple transceiver (TRX) or transmitter (TX) binds. Further, it is important for your application to use the SMS gateway access endpoint with the lowest Internet route round-trip time (RTT).

SMPP Simulator

Use the Melrose Labs SMSC Simulator with your application and SMPP to test outbound and inbound SMS without cost and without need for SMS gateway or SMSC account.

Smart Uses of SMS APIs

It can often be beneficial to minimise the amount of code, effort or applications involved in getting SMS from their source to their destination. The following are examples that help to achieve this when using an SMPP API when your application doesn't support SMPP:

• SMS to database (PostgreSQL, MySQL, etc) : Write to database an SMS that has been received from a mobile, and use code that periodically queries the database to process the received SMS. [SMPP to database, PostgreSQL or MySQL]
• SMPP to HTTP : Use a protocol bridge to pass SMS received from a mobile via SMPP to a webhook (using HTTP). [SMPP to REST]
• SMPP to SMTP : Use a protocol bridge to pass SMS received from a mobile via SMPP to an email address (using SMTP).
• HTTP to SMPP :
  • See REST-SMPP Bridge for batch submission of SMS
  • REST SMS API for sending individual and batches of SMS
• SMTP to SMPP : Use a protocol bridge to pass messages in emails (SMTP) to SMPP and onto mobiles.

Privacy and Confidentiality

APIs provide a means for one application to interact with another application. With the use of TLS by both SMPP and REST APIs, the information exchanged between the application and SMS gateway endpoint can be done securely. Specifically, TLS ensures the confidentiality of information passed from the application to the gateway, and vice versa. SMS APIs such as SMPP and REST do not themselves ensure the end-to-end confidentiality of information passed between the application and mobile.