Quick Start

Send your first SMS in under two minutes.

Prerequisites

1. Create a free test account at portal2.quicksms.com/signup
2. Create an API connection in Management > API Connections
3. Copy your API key (starts with sk_live_ or sk_test_)

Send a Test Message

Use your sk_test_ key to send in sandbox mode. No credits are deducted and no real SMS is delivered.

curl -X POST https://api.quicksms.com/v1/messages \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "MSISDN": "447700900001",
    "msg": "Hello from QuickSMS!",
    "sender": "QuickSMS"
  }'

Expected Response

{
    "sandbox": true,
    "total": 1,
    "accepted": 1,
    "rejected": 0,
    "messages": [{
        "quicksms_id": "msg_80fac5c752941b27",
        "MSISDN": "447700900001",
        "sender": "QuickSMS",
        "status": "ACCEPTED",
        "channel": "SMS",
        "encoding": "GSM-7",
        "message_parts": 1
    }],
    "created_at": "2026-03-26T12:00:00+00:00"
}

Switch to Production

Replace your sk_test_ key with your sk_live_ key. Ensure your sender ID is approved for the destination country. Credits will be deducted per message segment.

Authentication

All API requests require a valid API key in the Authorization header.

Bearer Token (Recommended)

Authorization: Bearer sk_live_EXAMPLE_KEY_REPLACE_ME

Basic Authentication

For backwards compatibility. Send your API key as the username with an empty password.

Authorization: Basic base64(sk_live_EXAMPLE_KEY_REPLACE_ME:)

API Key Types

Connection Status

Only active connections can send messages.

IP Allowlisting

Optionally restrict access to specific IPs. Unlisted IPs receive 403 with error code IP_NOT_ALLOWED. Configure at portal2.quicksms.com/account/security.

Brute-Force Protection

After 10 consecutive failed auth attempts from the same IP within 60 seconds, that IP is locked out for 5 minutes. The response includes a Retry-After header.

Best Practices

• Store API keys in environment variables or a secrets manager — never commit to source control.
• Use sk_test_ keys in development/staging; reserve sk_live_ keys for production.
• If a key may be compromised, rotate it immediately in portal2.quicksms.com.
• Enable IP allowlisting in production.

Send a Message

Send an SMS or RCS message to a single recipient. The API validates, prices, and queues the message in a single request.

Request Headers

Request Body

MSISDN Format

MSISDN (Mobile Station International Subscriber Directory Number) is the international phone number format used by telecom APIs. Digits only, country code prefix, no +.

Sender ID Formats

Example Request

curl -X POST https://api.quicksms.com/v1/messages \
  -H "Authorization: Bearer sk_live_EXAMPLE_KEY_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-sms" \
  -d '{
    "MSISDN": "447700900000",
    "msg": "Your order #12345 has been dispatched.",
    "sender": "MyStore",
    "customer_id": "cust_abc123",
    "metadata": { "order_id": "12345", "type": "dispatch_notification" },
    "callback_url": "https://example.com/webhooks/sms"
  }'

Try It

Understanding Responses

Every send request returns one of three outcomes.

Success — Message Queued

{
    "sandbox": false,
    "total": 1,
    "accepted": 1,
    "rejected": 0,
    "messages": [{
        "quicksms_id": "msg_80fac5c752941b27",
        "MSISDN": "447700900000",
        "sender": "MyStore",
        "status": "ACCEPTED",
        "channel": "SMS",
        "encoding": "GSM-7",
        "message_parts": 1,
        "customer_id": "cust_abc123"
    }],
    "created_at": "2026-03-26T12:00:00+00:00"
}

Success — Message Held

{
    "sandbox": false,
    "messages": [{
        "quicksms_id": "msg_80fac5c752941b27",
        "status": "HELD",
        "scheduled_send_at": "2026-03-27T08:00:00+00:00"
    }]
}

Rejection — Message Not Sent

{
    "messages": [{
        "MSISDN": "447700900000",
        "status": "REJECTED",
        "error": {
            "code": "CONTENT_BLOCKED",
            "message": "Message content was blocked by the content filter."
        }
    }]
}

Response Fields

Message Encoding

The API automatically selects the most efficient encoding for your message content.

GSM-7 (Standard)

UCS-2 (Unicode)

Delivery Webhooks (DLR)

When a message reaches a final delivery status, QuickSMS sends a POST request to your configured callback URL.

Callback URL Priority

If neither is configured, no webhook is delivered.

Webhook Headers

POST {your_callback_url}
Content-Type: application/json
X-QuickSMS-Timestamp: 1711468800
X-QuickSMS-Event: dlr
X-QuickSMS-Delivery-Attempt: 1
X-QuickSMS-Signature: sha256=5d7a8c3e...

Webhook Payload

{
    "quicksms_id": "msg_80fac5c752941b27",
    "customer_id": "cust_abc123",
    "channel": "SMS",
    "message_status": "DELIVERED",
    "status_code": 0,
    "message_parts": 1,
    "message_sent_time": "2026-03-26T12:00:01+00:00",
    "delivery_receipt_time": "2026-03-26T12:00:03+00:00",
    "read_receipt": null,
    "read_receipt_timestamp": null,
    "done_time": "2026-03-26T12:00:03+00:00",
    "metadata": { "order_id": "12345" }
}

Payload Fields

Retry Policy

Return any 2xx to acknowledge. Failures are retried with exponential backoff:

Best Practices

• Respond quickly. Return 200 immediately and process asynchronously.
• Handle duplicates. Use quicksms_id as a deduplication key.
• Verify signatures. Validate X-QuickSMS-Signature before processing.

Message Lifecycle

A message moves through distinct statuses from submission to final delivery.

Send Response Statuses

Delivery Statuses (via Webhook)

Status Flow

Send Response              Delivery Webhook
─────────────              ─────────────────

  ACCEPTED ──────────────▶ PENDING
                              │
                              ├──▶ DELIVERED
                              ├──▶ UNDELIVERED
                              ├──▶ EXPIRED
                              └──▶ REJECTED

  HELD ───(at scheduled)──▶ PENDING ──▶ (same as above)

  REJECTED                  (no webhook — message was never sent)

GSM Status Codes

Retry Strategy

Not all errors should be retried. Use the HTTP status code to decide.

Recommended Backoff

Rate Limits

Applied per API connection using a 60-second sliding window. Default: 1,000 requests per minute.

Idempotency

Include an Idempotency-Key header (max 128 chars) to prevent duplicate sends.

Keys are scoped to your API connection and cached for 24 hours.

Smart Routing (RCS)

When smart_routing is true and the sender is an approved RCS agent:

1. Message is routed via RCS
2. If the recipient doesn't support RCS, the system falls back to SMS automatically
3. Credits are adjusted — if SMS costs more, the difference is deducted; if less, refunded
4. DLR webhook channel field indicates which channel was actually used
5. RCS is billed per message (always 1 part), not per segment

SMS Failover Sender

When an RCS message falls back to SMS, the sender ID is resolved in this order:

Out-of-Hours Sending

Accounts can restrict dispatch to a defined business hours window. Configured per account in the portal.

Anti-Flood Protection

Prevents duplicate messages to the same recipient within a configurable window. A duplicate is the same account sending identical content to the same MSISDN within the window.

Country Restrictions

The recipient's country is determined by MSISDN prefix (e.g. 44 = UK, 353 = Ireland). Per-account overrides are checked first, then the platform-wide setting. Blocked destinations return COUNTRY_NOT_ALLOWED.

Sandbox Mode

Simulates the full send-and-deliver flow without carrier delivery. No credits deducted.

How to Activate

Differences from Production

Simulated Delivery Outcomes

Webhook Security

When a signing secret is configured, every webhook includes an X-QuickSMS-Signature header with an HMAC-SHA256 signature.

Verification Steps

1. Extract the X-QuickSMS-Timestamp header value
2. Get the raw request body (do not parse or re-serialize)
3. Concatenate: {timestamp}.{body}
4. Compute HMAC-SHA256 using your signing secret as the key
5. Compare with the header signature using constant-time comparison
6. Reject if timestamp is more than 5 minutes old (replay protection)

Verification Examples

const crypto = require('crypto');

function verifyWebhook(req, secret) {
    const timestamp = req.headers['x-quicksms-timestamp'];
    const signature = req.headers['x-quicksms-signature'];
    const body = req.rawBody;

    if (Math.abs(Date.now() / 1000 - parseInt(timestamp)) > 300) {
        throw new Error('Timestamp too old');
    }

    const payload = `${timestamp}.${body}`;
    const expected = 'sha256=' +
        crypto.createHmac('sha256', secret).update(payload).digest('hex');

    if (!crypto.timingSafeEqual(
        Buffer.from(expected), Buffer.from(signature)
    )) { throw new Error('Invalid signature'); }

    return JSON.parse(body);
}

import hmac, hashlib, time, json

def verify_webhook(request, secret):
    timestamp = request.headers.get('X-QuickSMS-Timestamp', '')
    signature = request.headers.get('X-QuickSMS-Signature', '')
    body = request.get_data(as_text=True)

    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError('Timestamp too old')

    payload = f'{timestamp}.{body}'
    expected = 'sha256=' + hmac.new(
        secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError('Invalid signature')

    return json.loads(body)

$secret    = 'your_webhook_signing_secret';
$timestamp = $_SERVER['HTTP_X_QUICKSMS_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_QUICKSMS_SIGNATURE'] ?? '';
$body      = file_get_contents('php://input');

if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401); die('Timestamp too old');
}

$payload  = "{$timestamp}.{$body}";
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401); die('Invalid signature');
}

$data = json_decode($body, true);
http_response_code(200);

Security Best Practices

Error Handling

All errors return consistent JSON with a unique request_id for support troubleshooting.

{
    "error": {
        "type": "validation_error",
        "code": "INVALID_PHONE_NUMBER",
        "message": "The MSISDN is not valid international format.",
        "param": "MSISDN",
        "request_id": "req_a1b2c3d4"
    }
}

HTTP Status Codes

Message Rejection Codes

Request-Level Error Codes

Health Endpoint

Check the API's operational status. No authentication required.

{ "status": "healthy" }

{ "status": "degraded" }

Use this endpoint for uptime monitoring. A 200 means all critical services are operational. A 503 indicates temporary degradation — retry with backoff.

Code Examples

curl -X POST https://api.quicksms.com/v1/messages \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "MSISDN": "447700900000", "msg": "Hello from QuickSMS!", "sender": "MyApp" }'

curl -X POST https://api.quicksms.com/v1/messages \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "MSISDN": "447700900000",
    "msg": "Your parcel is out for delivery!",
    "sender": "MyBrandAgent",
    "smart_routing": true,
    "sms_failover_sender": "MyBrand",
    "callback_url": "https://example.com/webhooks/dlr"
  }'

$ch = curl_init('https://api.quicksms.com/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer sk_live_your_key_here',
        'Content-Type: application/json',
        'Idempotency-Key: order-12345-sms',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'MSISDN' => '447700900000',
        'msg'    => 'Hello from QuickSMS!',
        'sender' => 'MyApp',
    ]),
]);
$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$data = json_decode($response, true);

if ($status === 202) {
    $msg = $data['messages'][0];
    echo "Sent: {$msg['quicksms_id']} — Status: {$msg['status']}";
} else {
    echo "Error: " . ($data['error']['message'] ?? $data['messages'][0]['error']['message']);
}

import requests

response = requests.post(
    'https://api.quicksms.com/v1/messages',
    headers={
        'Authorization': 'Bearer sk_live_your_key_here',
        'Idempotency-Key': 'order-12345-sms',
    },
    json={
        'MSISDN': '447700900000',
        'msg': 'Hello from QuickSMS!',
        'sender': 'MyApp',
    }
)

if response.status_code == 202:
    msg = response.json()['messages'][0]
    print(f"Sent: {msg['quicksms_id']} — Status: {msg['status']}")
elif response.status_code == 422:
    err = response.json()['messages'][0]['error']
    print(f"Rejected: {err['code']} — {err['message']}")
else:
    print(f"Error: {response.json()['error']['message']}")

print(f"Rate limit remaining: {response.headers.get('X-RateLimit-Remaining')}")

const response = await fetch('https://api.quicksms.com/v1/messages', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer sk_live_your_key_here',
        'Content-Type': 'application/json',
        'Idempotency-Key': 'order-12345-sms',
    },
    body: JSON.stringify({
        MSISDN: '447700900000',
        msg: 'Hello from QuickSMS!',
        sender: 'MyApp',
    }),
});
const data = await response.json();

if (response.status === 202) {
    const msg = data.messages[0];
    console.log(`Sent: ${msg.quicksms_id} — Status: ${msg.status}`);
} else {
    console.log(`Error: ${data.error?.message || data.messages?.[0]?.error?.message}`);
}

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer sk_live_your_key_here");
client.DefaultRequestHeaders.Add("Idempotency-Key", "order-12345-sms");

var payload = new {
    MSISDN = "447700900000",
    msg = "Hello from QuickSMS!",
    sender = "MyApp"
};
var response = await client.PostAsJsonAsync(
    "https://api.quicksms.com/v1/messages", payload);
var json = await response.Content.ReadAsStringAsync();

Console.WriteLine(response.StatusCode == System.Net.HttpStatusCode.Accepted
    ? $"Sent: {json}"
    : $"Error ({(int)response.StatusCode}): {json}");

Receiving Incoming Messages V1

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.

Register your numbers at portal2.quicksms.com/management/numbers.

Incoming Message Fields

Respond within ~1 second with RECEIVED.

Example Incoming Message

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"
}

Coming Soon

Planned capabilities and enhancements.

Changelog

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"
}

HTTP 200 OK
{ "reference": "42" }

HTTP 400 Bad Request
{ "Error": 206, "Description": "Invalid username or password" }