API Documentation

Messaging Services that ensure your messages reach instantly and effectively, no matter where they are located.

1. Sending an RCS/SMS Message

An RCS/SMS request must contain all information required to route a message through the system to the handset.

Required Fields

InformationPOST FieldExample
Request TypereqTypeBULK
Number to send toMSISDN447123456789
MessagemsgHello World
SendersenderTestSender

Endpoint: POST https://api.quicksms.com/rcs/v2/api

  • All required information must be present in the JSON POST body.
  • Username/Password credentials should be sent via a standard HTTP Basic Authorization header.

Example Request

POST https://api.quicksms.com/rcs/v2/api
Content-Type: application/json
Authorization: Basic <base64 encoded username:password>

{
  "reqType":"BULK",
  "MSISDN":"447891658396",
  "msg":"test message",
  "sender":"TestSender"
}

Optional Parameters

InformationPOST FieldExample
Multipart allowed (> 160 characters)multitrue
Custom ID (returned with receipt)cid123456
Receipt Delivery URLDelurlwww.receipts.co.uk

Request Response

Successful Request
On submission of a complete request the server responds with a single string in the format Success 100, 42, where 42 is the unique QuickSMS reference.

Notes
• A message will only be sent by RCS if the Sender ID has been pre-registered; otherwise it will be sent as a standard SMS.
• An RCS message will be attempted for 10 seconds before failing over to a standard SMS if it cannot be achieved.

Example Successful Response

HTTP 200 OK
Content-Type: application/json

{
  "reference": "42"
}

Failed Request

Upon receiving an incorrect request the server responds with a single string in the format Error 204 where the number maps to an error code (see below).

Example Failed Response

HTTP 400 Bad Request
Content-Type: application/json

{
  "Error": 206,
  "Description": "Invalid username or password"
}

Error Codes

Error CodeExplanation
200The request was not received through HTTPS. Requests must be sent to https://api.quicksms.com/rcs/api
201The request was not made through HTTP POST
202Username and/or Password not set or Username not in correct format
203Request type not set
204Invalid request type sent
205Missing required field
206Username or password incorrect
207Invalid MSISDN
208Master account does not have enough credits available
209Message too long
210Sender too long
220API temporarily disabled due to too many failed logins
221API permanently disabled due to too many failed logins

Code Examples

curl --location 'https://api.quicksms.com/rcs/v2/api' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic BASE64_ENCODED_USER:PASS' \
--data '{
  "reqType": "BULK",
  "MSISDN": "447000000000",
  "msg": "Test message",
  "sender": "QuickSMS"
}'
import requests
from requests.auth import HTTPBasicAuth

url = "https://api.quicksms.com/rcs/v2/api"
payload = {
  "reqType": "BULK",
  "MSISDN": "447000000000",
  "msg": "Test message",
  "sender": "QuickSMS"
}
response = requests.post(url, json=payload, auth=HTTPBasicAuth('your_user', 'your_pass'))
print(response.status_code, response.text)
const axios = require('axios');
const auth = Buffer.from('your_user:your_pass').toString('base64');

axios.post('https://api.quicksms.com/rcs/v2/api', {
  reqType: 'BULK',
  MSISDN: '447000000000',
  msg: 'Test message',
  sender: 'QuickSMS'
}, {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Basic ${auth}`
  }
}).then(response => {
  console.log(response.data);
}).catch(err => {
  console.error(err.response?.status, err.response?.data || err.message);
});
$curl = curl_init();
curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.quicksms.com/rcs/v2/api",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Basic " . base64_encode("your_user:your_pass")
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "reqType" => "BULK",
    "MSISDN" => "447000000000",
    "msg" => "Test message",
    "sender" => "QuickSMS"
  ])
]);
$response = curl_exec($curl);
curl_close($curl);
echo $response;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;
import java.io.OutputStream;

public class SendSMS {
  public static void main(String[] args) throws Exception {
    String userpass = "your_user:your_pass";
    String basicAuth = "Basic " + Base64.getEncoder().encodeToString(userpass.getBytes());

    URL url = new URL("https://api.quicksms.com/rcs/v2/api");
    HttpURLConnection conn = (HttpURLConnection) url.openConnection();
    conn.setRequestMethod("POST");
    conn.setRequestProperty("Authorization", basicAuth);
    conn.setRequestProperty("Content-Type", "application/json");
    conn.setDoOutput(true);

    String json = "{\\"reqType\\":\\"BULK\\",\\"MSISDN\\":\\"447000000000\\",\\"msg\\":\\"Test message\\",\\"sender\\":\\"QuickSMS\\"}";

    try (OutputStream os = conn.getOutputStream()) {
      os.write(json.getBytes("utf-8"));
    }
    System.out.println("HTTP " + conn.getResponseCode());
  }
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

class Program {
  static async Task Main() {
    var client = new HttpClient();
    var token = Convert.ToBase64String(Encoding.ASCII.GetBytes("your_user:your_pass"));
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", token);

    var body = "{\\"reqType\\":\\"BULK\\",\\"MSISDN\\":\\"447000000000\\",\\"msg\\":\\"Test message\\",\\"sender\\":\\"QuickSMS\\"}";
    var res = await client.PostAsync("https://api.quicksms.com/rcs/v2/api",
      new StringContent(body, Encoding.UTF8, "application/json"));

    Console.WriteLine((int)res.StatusCode + " " + await res.Content.ReadAsStringAsync());
  }
}

2. RCS/SMS Delivery Receipt

Once the RCS/SMS message has been delivered, a POST request is made to the location defined in your API account.

Delivery Receipt Fields

InformationPOST FieldExample
Unique Referencereference42
Custom Referencecid1234-232-134
Number message sent toMSISDN447123456789
Delivery Date and Timedelivery2012-06-27 12:33:00
Statusstatus3
Substatussubstatus5

Respond quickly (under 1 second) with a single line string: RECEIVED.

Example Delivery Receipt

POST https://www.website.co.uk/receipts
Content-Type: application/json

{
  "reference":"564634E434D0586B0C957D97E556CAD",
  "MSISDN":"447891658396",
  "status":"3",
  "substatus":"5",
  "deliverytime":"2024-01-01 16:36:48",
  "cid":"customid"
}

Status Codes

CodeExplanation
3Successful Delivery
2Undeliverable
4Message delivery has expired
5Message has been rejected by the network

Sub Status Codes

CodeExplanation
2Delivered to Operator
5Delivered to handset
4Rejected by operator and deemed undeliverable
9Not delivered (invalid/unreachable destination)
15Pending until validity expired or operator returns EXPIRED
29Expired; delivery status unknown (no DR received)
6Network experiencing problems
10Rejected due to DND (Do Not Disturb)
14Destination blocklisted (e.g., operator request)

3. RCS Seen Receipt

Once an RCS message has been seen, a POST request is made to the location defined in your API account.

Note: Only RCS messages send a Seen Receipt.

Seen Receipt Fields

InformationPOST FieldExample
Unique Referencereference42
Custom ReferenceCID1234-232-134
Number message sent toMSISDN447123456789
Seen Date and Timeseentime2012-06-27 12:33:00

Respond within ~1 second with RECEIVED.

Example Seen Receipt

POST https://www.website.co.uk/seen-receipts
Content-Type: application/json

{
  "reference":"564634E434D0586B0C957D97E556CAD",
  "CID":"1234-232-134",
  "MSISDN":"447891658396",
  "seentime":"2024-01-01 16:36:48"
}

4. Receiving Incoming Messages

When an incoming message is received by the QuickSMS system, it is checked against a list of registered numbers and RCS senders. If a match is found, a POST request is made to your configured endpoint.

Incoming Message Fields

InformationPost FieldExample
Unique ReferenceID42
Number/Sender message sent fromMSISDN447123456789
MessageMessageHello
Number message sent toNumber44789011829
Received Date and TimeDateRecieved2012-06-27 12:33:00 or Failed

Respond within ~1 second with RECEIVED.

Example Incoming Message Request

POST https://www.website.co.uk/incoming.php
Content-Type: application/json

{
  "MSISDN":"NotifyTest",
  "Message":"Testing",
  "Number":"44789100000",
  "DateRecieved":"2024-01-28 11:54:32",
  "ID":"MxJFwONIywR7yZysg7iAtDXQ"
}