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
| Information | POST Field | Example |
|---|---|---|
| Request Type | reqType | BULK |
| Number to send to | MSISDN | 447123456789 |
| Message | msg | Hello World |
| Sender | sender | TestSender |
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
| Information | POST Field | Example |
|---|---|---|
| Multipart allowed (> 160 characters) | multi | true |
| Custom ID (returned with receipt) | cid | 123456 |
| Receipt Delivery URL | Delurl | www.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.
• 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 Code | Explanation |
|---|---|
| 200 | The request was not received through HTTPS. Requests must be sent to https://api.quicksms.com/rcs/api |
| 201 | The request was not made through HTTP POST |
| 202 | Username and/or Password not set or Username not in correct format |
| 203 | Request type not set |
| 204 | Invalid request type sent |
| 205 | Missing required field |
| 206 | Username or password incorrect |
| 207 | Invalid MSISDN |
| 208 | Master account does not have enough credits available |
| 209 | Message too long |
| 210 | Sender too long |
| 220 | API temporarily disabled due to too many failed logins |
| 221 | API 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
| Information | POST Field | Example |
|---|---|---|
| Unique Reference | reference | 42 |
| Custom Reference | cid | 1234-232-134 |
| Number message sent to | MSISDN | 447123456789 |
| Delivery Date and Time | delivery | 2012-06-27 12:33:00 |
| Status | status | 3 |
| Substatus | substatus | 5 |
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
| Code | Explanation |
|---|---|
| 3 | Successful Delivery |
| 2 | Undeliverable |
| 4 | Message delivery has expired |
| 5 | Message has been rejected by the network |
Sub Status Codes
| Code | Explanation |
|---|---|
| 2 | Delivered to Operator |
| 5 | Delivered to handset |
| 4 | Rejected by operator and deemed undeliverable |
| 9 | Not delivered (invalid/unreachable destination) |
| 15 | Pending until validity expired or operator returns EXPIRED |
| 29 | Expired; delivery status unknown (no DR received) |
| 6 | Network experiencing problems |
| 10 | Rejected due to DND (Do Not Disturb) |
| 14 | Destination 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
| Information | POST Field | Example |
|---|---|---|
| Unique Reference | reference | 42 |
| Custom Reference | CID | 1234-232-134 |
| Number message sent to | MSISDN | 447123456789 |
| Seen Date and Time | seentime | 2012-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
| Information | Post Field | Example |
|---|---|---|
| Unique Reference | ID | 42 |
| Number/Sender message sent from | MSISDN | 447123456789 |
| Message | Message | Hello |
| Number message sent to | Number | 44789011829 |
| Received Date and Time | DateRecieved | 2012-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"
}