One platform, every channel

QuickSMS is one developer platform with two current outbound messaging APIs: use the Messaging API (POST /v1/messages) for SMS and RCS text, and the Rich RCS API (POST /v2/messages) for cards, carousels, media and interactions. Each has its own request shape, status vocabulary and delivery receipt, documented side by side; credentials, sending controls and webhook signing are shared. Messaging and the Contact Book use separate credentials today, explained once in Authentication.

Choose a channel

SMS and RCS text are sent through the Messaging API; Rich RCS is its own opt-in API with a structured content model and its own delivery receipts. Pick a channel once and the messaging pages show that channel's complete journey, see choose a messaging channel.

How the platform fits together

1. Contacts are your audience layer, who you can message, how they're organised, and what they've consented to.
2. Messaging sends to a recipient over the channel you choose, with content the channel supports.
3. Events tell you what happened next, delivered, read, failed, or fell back to SMS, with the payload for each endpoint clearly documented.
4. Errors use consistent envelope principles, with API-specific rejection and delivery models documented separately.

Messaging & Contact Book credentials Updated 21 July 2026 · View changelog →

Authentication

Every QuickSMS API request is authenticated with a Bearer credential in the Authorization header. This page is the single source of truth for credentials, the rest of the documentation links here rather than repeating it.

The Authorization header

All APIs use the same header format, over HTTPS only:

Authorization: Bearer sk_test_your_key_here

Which credential do I need?

Today, QuickSMS capabilities are covered by two credential types, both created in this portal. Messaging (SMS, RCS text and Rich RCS) shares one API key; the Contact Book has its own token with fine-grained scopes.

The two credential types are architecturally separate: a Contact Book token cannot send messages, and a messaging key cannot read your contact book. This limits the blast radius of a leaked credential and lets you grant integrators exactly what they need. If your integration does both, create both.

Test and live environments

Both credential types come in a test and a live variant. The base URL never changes, the credential prefix selects the environment. Use the Test / Live switch in the sidebar to update every example on these pages. How the two environments differ for messaging:

Manage the test allowlist on the API connection in API Connections. A live key can opt into the same behaviour per request with "sandbox": true, see sandbox mode. The Contact Book test token (cbk_test_) works differently: it is a real API against an isolated data namespace.

Simulated outcomes in test mode

Simulated delivery receipts arrive a few seconds after the send. You can force specific outcomes with the recipient's mobile number ending; read receipts are simulated only for RCS-delivered messages, SMS never produces read:

Use these endings to exercise your webhook handler against every delivery outcome.

The Contact Book sandbox is a separate data namespace: create, import and delete freely, then wipe it with POST /v1/sandbox/reset. Sandbox responses carry an X-Sandbox-Mode: true header so your client can display a test-mode indicator. Don't store real personal data in the sandbox.

Scopes (Contact Book)

Contact Book tokens carry scopes chosen at creation. Give each integration the narrowest scopes that work, a read-only dashboard needs contacts:read and nothing else.

Wildcards are supported: contacts:* grants all contact endpoints, * grants everything. A request without the required scope returns 403 with the missing scope and your token's actual scopes echoed back, see Errors.

Credential lifecycle

The two credential families have different lifecycles today. They are shown separately here because the states, and what an IP restriction failure returns, differ between them.

Messaging API connections

A request from an IP outside a messaging connection's allowlist returns 403 with the code IP_NOT_ALLOWED.

Contact Book tokens

A request from an IP outside a Contact Book token's allowlist returns 401 Unauthorized. For both families, leave the allowlist empty to accept requests from anywhere.

Basic authentication (compatibility)

The messaging API also accepts HTTP Basic authentication for compatibility with older integrations; Bearer is recommended for anything new. Your API key is the username and the password is blank, so the value is the Base64 encoding of the key followed by a trailing colon:

Authorization: Basic base64(sk_test_your_key_here:)

The trailing colon is required; the password field after it is ignored.

Brute-force protection

After 10 consecutive failed authentication attempts from the same IP within 60 seconds, that IP is locked out for 5 minutes. Locked-out requests return 429 with the code AUTH_RATE_LIMITED and a Retry-After header. Wait the indicated interval and verify the key is correct rather than retrying in a tight loop.

Best practices

• One credential per integration, easier to audit and revoke individually.
• Scope down, grant the minimum capability each integration needs.
• Rotate periodically, create the new credential, switch over, then revoke the old one.
• Separate test from live, CI and staging should only ever hold test credentials.

Verify your credential

Before integrating against real resources, confirm your credential works:

/v1/ping requires no scopes and echoes back your token's name, scopes and access level. For the messaging API, the health endpoint (GET /v1/health, also at /v2/health and /health) reports service status without authentication, and a test-key send to an allowlisted test number exercises the full authenticated flow.

Messaging API Updated 21 July 2026 · View changelog →

Send your first message

From API key to delivery receipt in seven steps. Everything here runs safely against a test key, nothing is sent to a real handset and no credits are used. Your progress is saved in this browser.

The steps are the same for every channel; the request, response and prerequisites below follow your selection. Shared steps stay complete when you switch channel; the send and response steps track completion per channel.

https://api.quicksms.com

{
  "sandbox": true,
  "total": 1,
  "accepted": 1,
  "rejected": 0,
  "messages": [{
    "quicksms_id": "msg_42a731415e521124",
    "mobile_number": "447700900123",
    "MSISDN": "447700900123",
    "sender": "YOUR_SENDER_ID",
    "status": "ACCEPTED",
    "channel": "SMS",
    "encoding": "GSM-7",
    "message_parts": 1
  }],
  "created_at": "2026-07-15T10:10:59+00:00"
}

{
  "sandbox": true,
  "total": 1,
  "accepted": 1,
  "rejected": 0,
  "messages": [{
    "quicksms_id": "msg_42a731415e521124",
    "mobile_number": "447700900123",
    "MSISDN": "447700900123",
    "sender": "YOUR_RCS_AGENT",
    "status": "ACCEPTED",
    "channel": "RCS",
    "encoding": null,
    "message_parts": 1
  }],
  "created_at": "2026-07-15T10:10:59+00:00"
}

{
  "total": 1,
  "accepted": 1,
  "rejected": 0,
  "messages": [{
    "message_id": "msg_42a731415e521124",
    "to": "447700900123",
    "sender": "YOUR_RCS_AGENT",
    "status": "queued",
    "channel": "RCS",
    "content_type": "rich_card",
    "cost": 0.10
  }],
  "created_at": "2026-07-15T10:10:59+00:00"
}

Messaging API Current · Live · Fully supported· Updated 21 July 2026 · View changelog →

Messaging

The QuickSMS Messaging API sends SMS and RCS text through one endpoint, POST /v1/messages, with one request shape and one status vocabulary. Rich content (cards, carousels, media) is an opt-in capability on an additional endpoint, POST /v2/messages, covered in Rich RCS; nothing about your existing integration changes when it is adopted.

The message model

Every message you send has the same anatomy:

{
  "mobile_number": "447700900123",                  // who, the recipient's mobile number
  "sender": "QuickSMS",                      // from, sender ID or RCS agent
  "msg": "Your order has been dispatched.",  // what, the message text
  "smart_routing": false,                    // RCS with automatic SMS fallback
  "expiry": 172800,                          // how long delivery may be attempted (seconds)
  "customer_id": "ORDER-12345",              // your reference, echoed in webhooks
  "metadata": { "journey": "dispatch" },     // your key-value data, echoed in webhooks
  "callback_url": "https://example.com/hooks"// where delivery receipts are sent
}

The full request/response reference, including the uppercase status vocabulary and the delivery receipt payload, is on the Messaging API reference.

Requests also accept an Idempotency-Key header (cached 24 hours) so a retried send never delivers twice, see Idempotency.

Sender formats and validation

Sender availability is also country-specific: the sender must be approved for the destination you are sending to. In test mode the default QuickSMS test sender applies unless you have an approved sender, see test and live environments.

Content length limits

Send a message

Pick a channel once; the selection follows you across the messaging pages (and into shared links) so you see one complete, channel-specific journey.

{
  "total": 1, "accepted": 1, "rejected": 0,
  "messages": [{
    "quicksms_id": "msg_9f2b60c1d8a4e7b3",
    "mobile_number": "447700900123",
    "MSISDN": "447700900123",
    "sender": "YOUR_SENDER_ID",
    "status": "ACCEPTED",
    "channel": "SMS",
    "encoding": "GSM-7",
    "message_parts": 1
  }],
  "created_at": "2026-07-15T09:30:00+00:00"
}

{
  "total": 1, "accepted": 1, "rejected": 0,
  "messages": [{
    "quicksms_id": "msg_5c11a09eb7f2d846",
    "mobile_number": "447700900123",
    "MSISDN": "447700900123",
    "sender": "YOUR_RCS_AGENT",
    "status": "ACCEPTED",
    "channel": "RCS",
    "encoding": null,
    "message_parts": 1
  }],
  "created_at": "2026-07-15T09:30:00+00:00"
}

{
  "total": 1, "accepted": 1, "rejected": 0,
  "messages": [{
    "message_id": "msg_42a731415e521124",
    "to": "447700900123",
    "sender": "MyBrandAgent",
    "status": "queued",
    "channel": "RCS",
    "content_type": "rich_card",
    "fallback": { "enabled": true, "sender_id": "MyBrand" },
    "cost": 0.10
  }],
  "created_at": "2026-07-14T09:30:00+00:00"
}

Build a request

Construct a working request without writing JSON by hand. Fill in the fields and copy the generated request in any of the eight languages; nothing is sent from this page, and the example key follows the Test / Live switch in the sidebar. Validation problems are flagged before you copy.

How smart routing works

Smart routing is a QuickSMS orchestration capability, not a Google feature: QuickSMS decides between RCS and SMS for a text message and applies your configured SMS fallback when the recipient or route is unavailable. It is implemented through our gateway's failover configuration. The whole flow, from request to billing:

Text request with "smart_routing": true
        |
        v
Is the sender an approved RCS agent?
        |-- no --> rejected synchronously (SENDER_NOT_RCS_AGENT), nothing sent
        |-- yes
        v
Is the recipient's handset RCS-capable and reachable?
        |-- yes --> delivered as RCS, read receipts possible
        |-- no  --> delivered as SMS via your fallback sender

• No silent downgrade to guesswork: if the sender isn't an approved RCS agent, the request is rejected synchronously; it never quietly sends as something else.
• The delivered channel is reported, not assumed: the send response reports the accepted channel, but the actual channel is confirmed by the delivery receipt's channel field (Rich RCS payloads additionally carry fell_back_to_sms: true, and support GET /v2/messages/{id}). An RCS-accepted message can still deliver, and bill, as SMS.
• Billing follows the delivered channel: RCS text is billed by length, up to 160 characters as RCS Basic, 161 or more as RCS Single; SMS is billed per message part. When a message falls back to SMS, the SMS rendition is calculated and billed independently on its own encoding and parts.
• Read receipts are RCS-only: read_receipt / read_at are populated only for RCS-delivered messages and are null for SMS.

How the SMS fallback sender is chosen

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

How the delivered channel is billed

Billing follows the channel the message was actually delivered on. An RCS text message is billed by length (RCS Basic or RCS Single); a message that falls back to SMS is billed on the SMS rendition's encoding and parts, calculated independently. The delivery receipt and, for Rich RCS, GET /v2/messages/{id} report the final channel and, on SMS delivery, the message_parts. Amounts are in your account currency; the exact reservation and re-rating behaviour on your wallet is described in your commercial terms.

// A 170-character RCS text send, accepted as RCS.
// RCS delivery would bill as RCS Single (161+ characters).

// Recipient is not RCS-capable; the same text is delivered as SMS instead.
// Delivery receipt: final channel is SMS, billed on its own parts.
{ "quicksms_id": "msg_42a731415e521124",
  "message_status": "DELIVERED",
  "channel": "SMS", "status_code": 0,
  "message_parts": 2 }
// Delivered as SMS: billed as two GSM-7 SMS parts, calculated
// independently from the RCS classification.

Scheduling and expiry

expiry caps how long delivery may be attempted (60 seconds to 72 hours, in seconds: min 60, max 259,200, default 172,800). If the recipient's handset stays unreachable past the validity period, the message ends as expired and you receive a failure receipt. Future-dated scheduling (send_at) is Coming soon, today, schedule sends from your own system or through portal campaigns.

Delivery is only attempted for five minutes; after that the code is useless anyway, so the message expires instead of arriving late.

Encoding, message parts and billing

SMS text is encoded as GSM-7 where possible: 160 characters in a single message, 153 per segment when concatenated (a few GSM-7 extension characters, such as €, [ and ~, count as two). Any character outside the GSM-7 set (many emoji, some accented characters, smart quotes pasted from a document) switches the whole message to UCS-2: 70 characters single, 67 per segment concatenated. SMS billing is per message part, and the maximum accepted length is 1,530 characters. This SMS segment counting applies to plain SMS and to any RCS message that falls back to SMS.

RCS billing classification

RCS text-message billing is determined by message length; rich formats have their own classification. The boundary between RCS Basic and RCS Single is a plain character count, so Unicode characters and emoji do not move it (they affect only an SMS fallback's encoding and parts).

If the message cannot be delivered through RCS and falls back to SMS, the SMS rendition is calculated and billed independently according to its encoding and number of SMS message parts. The two calculations are separate: the request builder shows both at once.

Above one segment the formula is ⌈length ÷ 153⌉ for GSM-7 and ⌈length ÷ 67⌉ for UCS-2. The response tells you what you were billed:

{
  "quicksms_id": "msg_42a731415e521124",
  "status": "ACCEPTED",
  "channel": "SMS",
  "encoding": "GSM-7",
  "message_parts": 2
}
// This SMS contains two message parts and is billed as two SMS messages.

The same message, with and without one emoji. This text is exactly 150 GSM-7 characters:

Hi Alex, your table at The Rose & Crown is booked for 7pm tonight. Reply C to confirm, or call us on 020 7946 0000 if you need to change your booking.

Paste the text into the request builder above and watch the encoding flip as you add the emoji.

One emoji turned one billable message into three. Check your message before sending: use the QuickSMS SMS & RCS character counter to see the encoding, number of message parts and likely charge as you type.

Personalisation and references

Render personalised text in your application before sending, you know your data best; QuickSMS does not substitute metadata into the message text. Use customer_id for your primary reference and metadata for structured hidden context (an order ID, a journey step). Both are echoed back on retrieval and on every delivery receipt, so your handler can correlate without a database lookup. To personalise from stored QuickSMS contact data, see Contacts & Audiences.

• customer_id: one string, max 128 characters.
• metadata: flat key-value pairs, max 10 keys, each value max 256 characters; no nested objects.
• Metadata is stored and echoed back to you, so don't put sensitive personal data in it unless you would be comfortable seeing it in your own webhook logs.

Sending in bulk

The send response is shaped for multiple recipients (total/accepted/rejected with a messages array). Batch sending of up to 1,000 recipients per request is Coming soon; today, send per recipient (respecting rate limits) or run large campaigns from the portal against your contact lists.

Rich RCS API Current · Live · Fully supported· Updated 21 July 2026 · View changelog →

Rich RCS

Branded cards, carousels, images and interactive buttons, delivered in the recipient's native inbox through the same POST /v2/messages endpoint as everything else. This page shows what each content type looks like on the handset, beside the JSON that creates it.

Overview

RCS billing classification

Text and suggestions

Plain text (up to 3,072 characters) with tappable chips beneath it. Text without suggestions prices and behaves like a standard RCS text send.

"content": {
  "type": "text",
  "text": "Your delivery arrives tomorrow between 9am and 11am.",
  "suggestions": [
    { "action_type": "open_url", "text": "Track parcel", "url": "https://example.com/track" },
    { "action_type": "dial", "text": "Call us", "phone_number": "+442037408909" }
  ]
}

Rich cards

At least one of title, description or media is required. The numbered markers show which field paints which part of the card:

"content": {
  "type": "rich_card",
  "rich_card": {
    "title": "Order dispatched",
    "description": "Your order #12345 is on its way.",
    "orientation": "vertical",
    "media_height": "tall",
    "media": { "url": "https://example.com/hero.png" },
    "buttons": [
      { "action_type": "open_url", "text": "Track parcel", "url": "https://example.com/track" },
      { "action_type": "dial", "text": "Call us", "phone_number": "+442037408909" }
    ]
  }
}

Carousels

2 to 10 swipeable cards, each with its own media and buttons. card_width is small or medium (default medium).

"content": {
  "type": "carousel",
  "carousel": {
    "card_width": "medium",
    "cards": [
      {
        "title": "Standard delivery",
        "description": "Arrives Thursday",
        "media": { "url": "https://example.com/a.png" },
        "buttons": [{ "action_type": "open_url", "text": "Choose", "url": "https://example.com/std" }]
      },
      {
        "title": "Express delivery",
        "description": "Arrives tomorrow",
        "media": { "url": "https://example.com/b.png" },
        "buttons": [{ "action_type": "open_url", "text": "Choose", "url": "https://example.com/exp" }]
      }
    ]
  }
}

Media

A standalone image or file, optionally with a thumbnail:

"content": {
  "type": "media",
  "media": {
    "url": "https://example.com/image.png",
    "thumbnail_url": "https://example.com/thumb.png"
  }
}

Requirements, for every media URL on cards and carousels too:

• QuickSMS requires media URLs to be HTTPS, publicly reachable (no authentication), and served with an image content type.
• QuickSMS retrieves and processes the asset, and may cache it: reuse the same URL for an identical asset so it is not re-fetched. A broken or redirecting URL can cause a rejection.
• Use stable CDN URLs, and author media to a recommended vertical-card ratio (2:1, 16:9 or 7:3); carousel media is commonly 4:3. Exact rendering is device-dependent.

Image sizes by media height

media_height sets the rendered height of the card's media area; supply an image whose aspect ratio suits that height, and the handset scales it to the card's width. These ratios are guidance, not a hard requirement: standalone vertical cards present best at 2:1, 16:9 or 7:3, while carousel media is commonly authored at 4:3. Anything else is centre-cropped to fit.

• tall is not supported on carousel cards; carousels use short or medium.
• tall is also not available on horizontal-orientation cards, where the media sits beside the text.
• Carousel card_width (small or medium, default medium) sets how much of the screen each card occupies; size images for the medium width and they scale down cleanly to small.
• Preview any combination without sending: build the card in RCS Studio (the RCS content wizard in the portal), which enforces these limits as you design and exports the matching content JSON.

Actions and replies

Buttons appear on cards (buttons, max 4 per card); suggestion chips appear beneath plain text (suggestions, max 11). Both use the same structure, and labels (text) are limited to 25 characters. Chip styling is fixed by the recipient's messaging app; your agent's brand colour tints the accents.

Webview support varies by the recipient's messaging app: Google Messages shows an in-conversation sheet; other clients may open the browser. As an anti-phishing measure, supported clients can display the destination URL on the chip; this is being rolled out (recent Google Messages) and is not yet universal, so do not rely on it appearing on every device. Design your label so it is clear on its own.

SMS fallback

Rich content can't reach handsets without RCS. The fallback object controls exactly what happens then: you write the SMS rendition, so nothing is improvised on your behalf. Here is the same message on an RCS handset and a non-RCS handset:

"fallback": {
  "enabled": true,
  "sms_body": "Your order #12345 has been dispatched. Track: https://example.com/track",
  "sender_id": "MyBrand"
}

The delivery and fallback journey:

• Webhooks and GET /v2/messages/{id} report fell_back_to_sms: true, with terminal status fallback_delivered or fallback_failed.
• Credits are re-rated at the SMS segment price and the difference adjusted automatically.
• With enabled: false (or omitted), a non-RCS recipient results in a failed message with a failure.reason; nothing is delivered.

Limitations

• Rich content requires an approved RCS agent as the sender; anything else is rejected synchronously with SENDER_NOT_RCS_AGENT. Rich content never quietly converts to SMS at send time.
• Rich content always routes via RCS; smart_routing applies to text content only.
• Chip icons and styling are fixed by the recipient's messaging app and cannot be customised.
• reply and share_location interactions are delivered through RCS inbound; configure inbound handling on the agent to receive them.
• Rich cards, carousels and standalone media are billed as RCS Single. Text with suggested replies keeps its length-based class (RCS Basic to 160 characters, RCS Single at 161+); text with any suggested action is RCS Single. Any SMS fallback is billed separately.

Messaging & Rich RCS APIs Updated 21 July 2026 · View changelog →

Choose a messaging channel

Three channels, one decision. Pick here, then every messaging page shows you a complete, channel-specific journey: request, response, delivery receipts, errors and billing.

Unsure? Start with SMS: it reaches everyone, and RCS text is one field away once your RCS agent is approved. Rich RCS is fully additive; adopting it changes nothing about your existing sends.

How RCS is billed

Messaging API Updated 21 July 2026 · View changelog →

Sending controls

The platform applies several safeguards between your API call and the handset: scheduling holds, out-of-hours rules, anti-flood protection and country restrictions. They apply to every send, whichever endpoint accepts it. This page explains each control, when it triggers, and what you see when it does.

Held messages and scheduling

A message that is accepted but not yet released for dispatch is held. Held messages carry a scheduled send time (scheduled_send_at) telling you when the platform will release them, and credits are reserved immediately so the send cannot later fail on balance. No action is needed on your side; the message dispatches automatically when the hold clears.

Out-of-hours protection

Accounts can restrict dispatch to a defined business-hours window, preventing a late-night batch job from messaging your customers at 3am. The account chooses what happens to a message submitted outside the window:

{
  "messages": [{
    "quicksms_id": "msg_80fac5c752941b27",
    "status": "HELD",
    "scheduled_send_at": "2026-07-15T08:00:00+00:00"
  }]
}

{
  "messages": [{
    "status": "REJECTED",
    "error": {
      "code": "OUT_OF_HOURS",
      "message": "Outside the allowed sending window (08:00 to 20:00). Sending resumes at 2026-07-15T08:00:00+00:00."
    }
  }]
}

Note the distinction: scheduled_send_at is a response field reporting when a held message will be released; it is not a request field for future scheduling (that is the planned send_at, coming soon). Configure the window and mode in your account settings; if none is configured, sends are released immediately at any time of day. Out-of-hours restrictions are bypassed in sandbox mode.

Anti-flood protection

Anti-flood protection prevents duplicate messages reaching the same recipient within a configurable window, which typically indicates a stuck retry loop or an integration bug rather than intent. A duplicate is the same account sending identical content to the same mobile number within the window. The account's anti-flood mode decides what happens:

{
  "messages": [{
    "status": "REJECTED",
    "error": {
      "code": "DUPLICATE_MESSAGE",
      "message": "Identical content was sent to this recipient within the anti-flood window. Original message: msg_80fac5c752941b27."
    }
  }]
}

The window length and mode are configured per account in your security settings. Anti-flood is bypassed in sandbox mode. Use an Idempotency-Key so that retries replay the original response instead of ever looking like a flood.

Country restrictions

Every destination country has a permission status on your account. The recipient's country is determined from the mobile number's dialling prefix (44 is the UK, 353 is Ireland, and so on); per-account overrides are checked first, then the platform-wide default. A send to a blocked destination is rejected synchronously with code COUNTRY_NOT_ALLOWED, before any carrier contact, and nothing is billed. Restrictions exist for fraud protection and compliance; international destinations beyond your agreed set are blocked by default. Review your destinations in your account security settings, and contact your account manager or support to enable additional countries; changes take effect immediately once approved.

Sandbox mode

Sandbox mode simulates the full send-and-deliver flow, including webhooks, without carrier delivery or credit use. Three things activate it:

Test keys can only send to mobile numbers in your approved test allowlist, managed on the API connection in the portal; other numbers are rejected with TEST_NUMBER_NOT_APPROVED. The text "This is a QuickSMS test message" is appended to sandbox sends, and test mode uses the default QuickSMS test sender unless you have an approved sender of your own. You can force specific simulated outcomes with the recipient number's ending, see simulated outcomes in test mode.

Callback URL priority

Delivery receipts are sent to the most specific webhook URL configured:

1. callback_url supplied on the individual message, if any.
2. Otherwise, the webhook URL configured on the API connection that sent it.

If neither is configured, no webhook is sent and you can still reconcile with GET /v2/messages/{message_id}.

Inbound API V2 Current · Live · SMS and RCS inbound available· Updated 21 July 2026 · View changelog →

Inbound messaging

Receive customer replies through QuickSMS and route each inbound message to the systems and teams that need it. SMS replies arrive through Inbound V2; replies to your RCS agent arrive through RCS inbound, configured per agent.

Inbound overview

Inbound messaging has three parts: an inbound number that receives the message, the routing options you enable on that number, and the delivery destinations each message is sent to. One inbound SMS can reach several destinations at once: your webhook for integrations, the QuickSMS Inbox for your team, and an email inbox for anyone else, while opt-out keywords are processed automatically.

Use inbound messaging for:

• Two-way conversations: let customers reply to your messages and route those replies into your CRM, support tool or inbox.
• Opt-out handling: capture STOP, UNSUBSCRIBE and similar keywords automatically.
• Lead capture: advertise a number on print, outdoor or broadcast media and route responses into your systems.
• Operational notifications: receive alerts that automated systems can act on.

How inbound numbers work

An inbound number is a dedicated UK mobile number assigned to your QuickSMS account. Customers can reply to messages sent from that number, or send messages to it directly. QuickSMS receives the inbound SMS and routes it to each destination you have enabled.

In the portal and some existing integrations, inbound numbers may also be referred to as Virtual Mobile Numbers or VMNs. Sends from an alphanumeric sender ID cannot receive replies; use an inbound number as the sender whenever you expect a response.

Inbound numbers are managed in Management › Numbers: click a number's row to open its configuration drawer, or select several numbers and use Bulk Configure to apply the same settings to all of them in one save.

Receive SMS replies

The end-to-end journey, from number to processed reply:

1. Obtain or select an inbound number in Management › Numbers.
2. Enable the routing options you need on that number.
3. Configure an inbound webhook where your systems need the message, and store the signing secret.
4. Send from the inbound number and receive an SMS reply.
5. Verify the webhook signature on the request you receive.
6. Process the inbound message in your system.
7. Opt-out keywords are handled automatically where you have enabled opt-out processing.
8. Review the message in the portal Inbox or the forwarded email, whichever destinations you enabled.

Routing inbound messages

Each inbound number has four routing options. Three are delivery destinations that receive a copy of the message; the fourth, automatic opt-out processing, is a processing action that updates your suppression lists rather than delivering the message anywhere. The portal groups all four together in the number's configuration drawer.

What each option needs

QuickSMS Inbox

Messages from the same sender thread into one conversation, even across days or weeks, with unread counts, full-text search across participants and content, and reply-from-portal (the reply is sent from the inbound number). Multiple portal users can work from the same Inbox, subject to permissions; sub-account users only see conversations on numbers they have access to. Toggling the Inbox off skips it without affecting the other routing options.

Email forwarding

Choose how messages arrive based on volume and urgency:

• Forward to one address or a whole team: separate addresses with semicolons (up to 1,000 characters of addresses). Each address is validated independently, and each recipient gets their own copy with no cross-recipient visibility.
• Delivery mode defaults to Immediate, and switching between Immediate, hourly digest and daily digest keeps the same recipient list; only the cadence changes.
• Subject lines are privacy-conscious ("New SMS received"); message content never appears in the subject. The email body contains the original sender's mobile number, the receiving inbound number, the message content and the time received.
• Forwarding is one-way: replies to the email are not delivered back to the original SMS sender.

Automatic opt-out processing

When an inbound message contains a recognised opt-out keyword, the sender is added to the configured opt-out list with a timestamp and source, the event is recorded in the audit log, and the sender is excluded from future campaigns. The message still reaches your other enabled destinations, so you keep a record of the opt-out. Recognised keywords, case-insensitive and tolerant of surrounding punctuation:

STOP        STOPALL      UNSUBSCRIBE
CANCEL      END          QUIT
OPT OUT     OPTOUT       REMOVE

A repeated opt-out from an already opted-out number is detected and recorded without error, so repeated STOP messages are never a failure. Point each number at its own opt-out list or share one across numbers. The master opt-out list is account-wide: numbers on it are excluded from every campaign regardless of which list captured them, and cannot be marketed to again without explicit re-consent. Automatic STOP handling is required by PECR for marketing SMS, so attach an opt-out list to every campaign-receiving number. See opt-outs and consent for the API side.

Inbound webhook V2

The webhook is the API surface of inbound messaging: every inbound message on a webhook-enabled number is POSTed to your endpoint in real time as JSON, signed so you can verify it came from QuickSMS. The forwarding URL must be HTTPS; plain HTTP URLs are not accepted. The signing secret is generated when you first save a URL and is displayed once, so copy it then. You can rotate the secret on demand (the old secret stops working immediately); secrets do not expire on their own, and disabling the webhook keeps both the URL and the secret so re-enabling resumes with the same configuration.

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-QuickSMS-Signature: sha256=<hex digest>
X-QuickSMS-Timestamp: 1718625684

{
  "from": "+447891658398",
  "to": "447908679883",
  "content": "Hi, just checking when my order will arrive?",
  "channel": "sms",
  "message_id": "sNb2FSG8wb6IsArvRdbS",
  "timestamp": "2026-06-17T11:41:24Z"
}

Signature verification

Compute an HMAC-SHA256 over timestamp + "." + body using your signing secret and compare it to the hex digest in X-QuickSMS-Signature (note the sha256= prefix). Verify against the raw request bytes, before any JSON parsing, and use a constant-time comparison:

const crypto = require('crypto');

function verifyInbound(rawBody, timestampHeader, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret)
    .update(timestampHeader + '.' + rawBody)
    .digest('hex');
  const received = signatureHeader.replace(/^sha256=/, '');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  );
}

function verifyInbound(string $rawBody, string $timestampHeader, string $signatureHeader, string $secret): bool
{
    $expected = hash_hmac('sha256', $timestampHeader . '.' . $rawBody, $secret);
    $received = preg_replace('/^sha256=/', '', $signatureHeader);
    return hash_equals($expected, $received);
}

import hmac, hashlib

def verify_inbound(body_bytes, timestamp_header, signature_header, secret):
    expected = hmac.new(
        secret.encode(),
        (timestamp_header + "." + body_bytes.decode()).encode(),
        hashlib.sha256,
    ).hexdigest()
    received = signature_header.replace("sha256=", "", 1)
    return hmac.compare_digest(expected, received)

using System.Security.Cryptography;
using System.Text;

static bool VerifyInbound(string rawBody, string timestamp, string signatureHeader, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(
        hmac.ComputeHash(Encoding.UTF8.GetBytes($"{timestamp}.{rawBody}"))
    ).ToLowerInvariant();
    var received = signatureHeader.StartsWith("sha256=")
        ? signatureHeader["sha256=".Length..]
        : signatureHeader;
    return CryptographicOperations.FixedTimeEquals(
        Convert.FromHexString(expected), Convert.FromHexString(received));
}

static boolean verifyInbound(String rawBody, String timestamp,
                             String signatureHeader, String secret) throws Exception {
    var mac = javax.crypto.Mac.getInstance("HmacSHA256");
    mac.init(new javax.crypto.spec.SecretKeySpec(
        secret.getBytes(java.nio.charset.StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] expected = mac.doFinal(
        (timestamp + "." + rawBody).getBytes(java.nio.charset.StandardCharsets.UTF_8));

    String received = signatureHeader.startsWith("sha256=")
        ? signatureHeader.substring("sha256=".length())
        : signatureHeader;
    byte[] receivedBytes = java.util.HexFormat.of().parseHex(received);
    return java.security.MessageDigest.isEqual(expected, receivedBytes);
}

func verifyInbound(rawBody []byte, timestamp, signatureHeader, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(timestamp + "."))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))

    received := strings.TrimPrefix(signatureHeader, "sha256=")
    return hmac.Equal([]byte(expected), []byte(received))
}

require "openssl"

def verify_inbound(raw_body, timestamp, signature_header, secret)
  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
  received = signature_header.delete_prefix("sha256=")
  OpenSSL.secure_compare(expected, received)
end

Failure behaviour

• Your endpoint should respond with a 2xx within 10 seconds.
• A non-2xx response or timeout is logged as a failed delivery for the webhook destination and is not retried automatically. This is different from outbound delivery receipts, which retry on a schedule. Enable the QuickSMS Inbox or another routing option so the message remains accessible if your endpoint is unavailable.
• Failures are isolated: the Inbox, email forwarding and opt-out processing still run normally.
• De-duplicate on message_id if your endpoint may be called more than once.

Payload reference

Inbound webhook V2 delivers the following JSON payload for each inbound SMS. The Inbox and email forwarding present the same underlying message record in their own formats.

Inbound V1 (deprecated)

Inbound V1 is the original inbound delivery from the same platform generation as the Legacy API. It remains in service for the integrations built on it and nothing changes without warning, but it is deprecated: every V1 capability now has a current, HMAC-signed successor, and no new V1 integrations should be created. No removal date is set.

The full V1 payload reference now lives with the platform history: Inbound V1 reference (deprecated).

Migrating from Inbound V1

• SMS replies: move to the Inbound V2 webhook. You gain the HMAC-signed normalised payload (from, to, content, channel, message_id, timestamp) in place of the unsigned V1 shape; de-duplicate on message_id.
• RCS replies: enable RCS agent inbound on your Live agent. You gain typed replies, chip and button taps with postback_data, photo/file replies and shared locations, none of which V1 delivers in structured form.
• If you want to verify the new payloads before retiring the old endpoint, ask your account manager about running V1 and the new delivery in parallel during the migration.

RCS inbound · replies to your RCS agent

When someone replies to a message from your RCS agent, that reply is an inbound message. Inbound handling is configured per agent: in Management › RCS Agents V2, open the actions menu on a Live agent and choose Inbound configuration. The same four destinations as SMS inbound apply, in any combination, independently: the in-portal Inbox (on by default), opt-out handling against a list you choose, webhook delivery to your own HTTPS endpoint, and one-way email forwarding. If an agent is suspended, its inbound configuration pauses and resumes with the agent; nothing is lost.

The RCS inbound webhook

Each inbound message is delivered to your forwarding URL as an HTTPS POST with Content-Type: application/json and two headers: x-quicksms-signature (sha256=<hex>, an HMAC-SHA256 of the raw request body computed with your signing secret) and x-quicksms-timestamp (Unix seconds, for replay checks). Verify the signature against the raw bytes before parsing, and reject stale timestamps.

The body is an envelope: event (always inbound_message), source (rcs_agent for per-agent delivery; api_connection when an account-level API connection's inbound webhook also receives the message, each with its own signing secret), and data:

Treat any field not listed above as diagnostic: it is not part of the stable contract, may change or disappear without notice, and should never be branched on. Build against message_type.

What each interaction looks like

One payload shape covers every way a recipient can respond. Read data.message_type first; fields that do not apply to an interaction are null. In brief:

1 · A typed, free-text reply

{
  "event": "inbound_message",
  "source": "rcs_agent",
  "data": {
    "from": "+447700900123",
    "to": "MyBrandAgent",
    "content": "What time will my order arrive?",
    "channel": "rcs",
    "message_id": "ib_7f3a9c2e5d81",
    "timestamp": "2026-07-21T09:15:02+01:00",
    "message_type": "text",
    "interaction_type": "BASIC_MESSAGE",
    "postback_data": null
  }
}

2 · A suggested-reply chip tap

The value you set in the outbound reply action's payload field comes back as postback_data; content is the chip's visible label. Drive your logic from postback_data, not the label, which you may reword at any time.

{
  "event": "inbound_message",
  "source": "rcs_agent",
  "data": {
    "from": "+447700900123",
    "to": "MyBrandAgent",
    "content": "Yes, sign me up",
    "channel": "rcs",
    "message_id": "ib_2b9d4e7a1c53",
    "timestamp": "2026-07-21T09:16:40+01:00",
    "message_type": "suggested_reply",
    "interaction_type": "BASIC_MESSAGE",
    "postback_data": "OPTIN_YES"
  }
}

3 · A button tap: open URL, dial, or add to calendar

Taps on open_url, dial and create_calendar_event buttons arrive as message_type: "suggested_action" with the button's label in content. The handset performs the action itself (opens the browser, pre-fills the dialler, opens the calendar); the webhook simply tells you the tap happened. A button tapped on a rich card reports interaction_type: "RICH_CARD_RESPONSE".

{
  "event": "inbound_message",
  "source": "rcs_agent",
  "data": {
    "from": "+447700900123",
    "to": "MyBrandAgent",
    "content": "Track parcel",
    "channel": "rcs",
    "message_id": "ib_9c1e6b3f8d24",
    "timestamp": "2026-07-21T09:18:11+01:00",
    "message_type": "suggested_action",
    "interaction_type": "RICH_CARD_RESPONSE",
    "postback_data": null
  }
}

A dial tap looks the same with "content": "Call us"; a calendar tap with "content": "Add to calendar". Pending confirmation The exact postback_data value for action buttons (which have no payload field on the outbound contract) is being confirmed; treat the label in content as the reliable signal for now.

4 · A photo or file reply

QuickSMS forwards a link to the file on the RCS network's storage; it does not download or host the file. Fetch it from media_url promptly if you need to keep it. Pending confirmation The content marker for file replies and the link's lifetime are being confirmed.

{
  "event": "inbound_message",
  "source": "rcs_agent",
  "data": {
    "from": "+447700900123",
    "to": "MyBrandAgent",
    "content": "[RCS interaction: FILE]",
    "channel": "rcs",
    "message_id": "ib_4a8d2c7e9f16",
    "timestamp": "2026-07-21T09:20:33+01:00",
    "message_type": "file",
    "interaction_type": "BASIC_MESSAGE",
    "postback_data": null,
    "media_url": "https://rcs-media.example/files/dl/6f2e8a91c4b7",
    "media_name": "photo.jpg",
    "media_content_type": "jpeg",
    "media_size": 245678
  }
}

5 · A shared location

When the recipient taps your share_location suggestion (or shares a position directly), the coordinates arrive in latitude and longitude, and content carries the marker [RCS interaction: LOCATION].

{
  "event": "inbound_message",
  "source": "rcs_agent",
  "data": {
    "from": "+447700900123",
    "to": "MyBrandAgent",
    "content": "[RCS interaction: LOCATION]",
    "channel": "rcs",
    "message_id": "ib_1d6f9b4a3e82",
    "timestamp": "2026-07-21T09:22:05+01:00",
    "message_type": "location",
    "interaction_type": "BASIC_MESSAGE",
    "postback_data": null,
    "latitude": 51.5074,
    "longitude": -0.1278
  }
}

Verifying the RCS inbound signature

Compute an HMAC-SHA256 over the raw request body with your signing secret and compare it, constant-time, to the header value after the sha256= prefix. Reject mismatches, and reject requests whose x-quicksms-timestamp is older than your tolerance:

expected = "sha256=" + hmac_sha256(secret, raw_request_body)
if constant_time_equals(expected, request.header("x-quicksms-signature")):
    # trusted

Respond promptly with a success status. The retry behaviour when your endpoint is unreachable is being confirmed and will be documented here.

Contact Book API v1.1 Updated 21 July 2026 · View changelog →

Contacts & audiences

Contacts are the audience layer of the messaging platform: who you can message, how they're organised, and what they've consented to. The Contact Book API manages contacts, tags, lists, opt-outs and custom fields, 47 endpoints, all following the same conventions as the rest of the platform.

The audience workflow

Contacts connect directly to messaging. A typical end-to-end journey:

1. Create a contact

Only mobile_number is required. Everything else, name, email, your CRM reference, custom fields, is optional.

2. Organise with lists and tags

Lists are explicit audiences ("Newsletter subscribers"); tags are labels for filtering ("VIP"). Add up to 1,000 contacts per call, import up to 5,000 at a time, or apply changes to an entire filtered audience asynchronously with the by-filter operations.

3. Message the audience

Send to individual contacts through the messaging API, using the contact's stored data for personalisation and customer_id to correlate. For whole lists and segments, run campaigns from the portal, list-addressed API sends arrive with the batch messaging API Coming soon.

4. Receive delivery receipts

Delivery, read and failure receipts flow to your webhook endpoint as usual, see Delivery receipts & webhooks. Use them to keep engagement data on your side in sync.

5. Keep consent up to date

A contact's status is computed from opt-out records: active or opted_out. Check before you send, and record opt-outs the moment they happen.

Opt-outs and consent

Opt-out lists are suppression lists. Numbers on them are excluded from portal campaigns automatically, and the API gives you everything needed to enforce the same rule in your own sends:

• Check a number before sending: the opt-out status check endpoint tells you whether a mobile number appears on any of your opt-out lists.
• Record an opt-out: add the number to an opt-out list the moment a recipient asks to stop.
• Bulk operations: import opt-out records, move them between lists, or opt out up to 1,000 contacts per call.

Custom fields

Define your own contact attributes (a loyalty tier, a renewal date) once, then read and write them per contact through custom_data. Definitions are managed through the custom-fields endpoints and available across imports, filters and the portal UI.

Bulk and asynchronous operations

Three sizes of write, one pattern each:

Send an Idempotency-Key on bulk writes, an accidental retry of a 50,000-contact tagging operation should replay the original response, not run twice. See Idempotency.

Messaging API & Rich RCS Updated 21 July 2026 · View changelog →

Delivery receipts & webhooks

Delivery receipts (DLRs) are how the platform talks back: when a message is delivered, read, fails or falls back to SMS, QuickSMS delivers the receipt as a signed webhook POSTed to your endpoint. One transport, one signature scheme for every channel; only the payload shape differs by API version.

Which payload will you receive?

The payload shape is determined solely by which endpoint accepted the message, never by account settings or content. The transport, retry schedule and signature scheme are identical for both, so one verification implementation covers everything.

What each channel's receipts can tell you:

{
  "quicksms_id": "msg_80fac5c752941b27",
  "customer_id": "cust_abc123",
  "channel": "SMS",
  "message_status": "DELIVERED",
  "status_code": 0,
  "message_parts": 2,
  "done_time": "2026-07-15T12:00:03+00:00",
  "metadata": { "order_id": "12345" }
}
// message_parts: 2 means this message was billed as two SMS messages.

{ "quicksms_id": "msg_80fac5c752941b27", "channel": "SMS",
  "message_status": "UNDELIVERED", "status_code": 27, "message_parts": 1,
  "done_time": "2026-07-15T12:48:00+00:00" }

{ "quicksms_id": "msg_11ab2c3d4e5f6a7b", "channel": "SMS",
  "message_status": "EXPIRED", "status_code": 255, "message_parts": 1,
  "done_time": "2026-07-17T12:00:00+00:00" }

{
  "quicksms_id": "msg_5c11a09eb7f2d846",
  "channel": "RCS",
  "message_status": "DELIVERED",
  "status_code": 0,
  "message_parts": 1,
  "read_receipt": true,
  "read_receipt_timestamp": "2026-07-15T12:01:10+00:00",
  "done_time": "2026-07-15T12:00:04+00:00"
}

{
  "quicksms_id": "msg_5c11a09eb7f2d846",
  "channel": "SMS",
  "message_status": "DELIVERED",
  "status_code": 0,
  "message_parts": 2,
  "read_receipt": null,
  "done_time": "2026-07-15T12:00:06+00:00"
}
// Fallback delivered as SMS: billed as two SMS parts, calculated independently.

How receipts are delivered (all channels)

QuickSMS delivers each delivery receipt as a webhook POSTed to your callback_url (per message) or your connection's default webhook URL. Rich RCS sends receive a message.status payload for each status transition (message.status is the technical webhook event name); Messaging API sends receive their DLR when the message reaches a final status. Every webhook carries the same headers:

{
  "api_version": "v2",
  "event": "message.status",
  "message_id": "msg_42a731415e521124",
  "customer_id": "cust_abc123",
  "channel": "RCS",
  "content_type": "rich_card",
  "status": "delivered",
  "fell_back_to_sms": false,
  "sent_at": "2026-07-14T10:11:01+00:00",
  "delivered_at": "2026-07-14T10:11:04+00:00",
  "read_at": null,
  "done_at": "2026-07-14T10:11:04+00:00",
  "metadata": { "order_id": "12345" }
}

"failure": {
  "reason": "not_capable",
  "description": "Destination not RCS capable"
}

Signature verification

Every webhook is signed. The X-QuickSMS-Signature header carries sha256=<hex>, an HMAC-SHA256 of {timestamp}.{body} computed with your webhook signing secret (shown on your API connection); the timestamp is delivered in the X-QuickSMS-Timestamp header. Strip the sha256= prefix before comparing, and verify before trusting any receipt:

const crypto = require('crypto');

function verifyWebhook(rawBody, timestamp, signatureHeader, secret) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    throw new Error('Timestamp too old');
  }
  const expected = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + rawBody)
    .digest('hex');
  const received = signatureHeader.replace(/^sha256=/, '');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received, 'hex')
  );
}

function verifyWebhook(string $rawBody, string $timestamp, string $signatureHeader, string $secret): bool
{
    if (abs(time() - (int) $timestamp) > 300) {
        return false; // timestamp too old
    }
    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    $received = preg_replace('/^sha256=/', '', $signatureHeader);
    return hash_equals($expected, $received);
}

import hashlib
import hmac
import time

def verify_webhook(raw_body: bytes, timestamp: str, signature_header: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False  # timestamp too old
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

using System.Security.Cryptography;
using System.Text;

static bool VerifyWebhook(string rawBody, string timestamp, string signatureHeader, string secret)
{
    var age = DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(timestamp);
    if (Math.Abs(age) > 300) return false; // timestamp too old

    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(
        hmac.ComputeHash(Encoding.UTF8.GetBytes($"{timestamp}.{rawBody}"))
    ).ToLowerInvariant();
    var received = signatureHeader.StartsWith("sha256=")
        ? signatureHeader["sha256=".Length..]
        : signatureHeader;
    return CryptographicOperations.FixedTimeEquals(
        Convert.FromHexString(expected), Convert.FromHexString(received));
}

static boolean verifyWebhook(String rawBody, String timestamp,
                             String signatureHeader, String secret) throws Exception {
    long age = Math.abs(System.currentTimeMillis() / 1000L - Long.parseLong(timestamp));
    if (age > 300) return false; // timestamp too old

    var mac = javax.crypto.Mac.getInstance("HmacSHA256");
    mac.init(new javax.crypto.spec.SecretKeySpec(
        secret.getBytes(java.nio.charset.StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] expected = mac.doFinal(
        (timestamp + "." + rawBody).getBytes(java.nio.charset.StandardCharsets.UTF_8));

    String received = signatureHeader.startsWith("sha256=")
        ? signatureHeader.substring("sha256=".length())
        : signatureHeader;
    byte[] receivedBytes = java.util.HexFormat.of().parseHex(received);
    return java.security.MessageDigest.isEqual(expected, receivedBytes);
}

func verifyWebhook(rawBody []byte, timestamp, signatureHeader, secret string) bool {
    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
        return false // timestamp too old
    }

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(timestamp + "."))
    mac.Write(rawBody)
    expected := hex.EncodeToString(mac.Sum(nil))

    received := strings.TrimPrefix(signatureHeader, "sha256=")
    return hmac.Equal([]byte(expected), []byte(received))
}

require "openssl"

def verify_webhook(raw_body, timestamp, signature_header, secret)
  return false if (Time.now.to_i - timestamp.to_i).abs > 300 # timestamp too old

  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
  received = signature_header.delete_prefix("sha256=")
  OpenSSL.secure_compare(expected, received)
end

• Compute the HMAC over the raw request body, parse the JSON only after verifying. Do not re-serialise the JSON; sign the exact bytes on the wire.
• Strip the sha256= prefix from the header before the comparison, as in the examples.
• Reject stale timestamps (older than 5 minutes) to prevent replay.
• Use a constant-time comparison, as in the examples above.
• The inbound webhook uses the same scheme with a per-number signing secret.

Delivery receipt retry schedule

Return any 2xx to acknowledge a webhook. A non-2xx response or a timeout counts as a failed attempt and is retried with backoff, with the attempt number in X-QuickSMS-Delivery-Attempt:

After five failed attempts the webhook is dropped. The message's status is unaffected, only the notification is lost; reconcile with the portal (or, for Rich RCS sends, GET /v2/messages/{id}). This schedule applies to outbound delivery receipts from both endpoints. The inbound webhook is different: inbound failures are logged without automatic retries.

• Respond fast with a 2xx. Acknowledge first, process asynchronously.
• Expect duplicates. Retries mean the same receipt can arrive more than once. De-duplicate per contract: Messaging API receipts on (quicksms_id, message_status), Rich RCS receipts on (message_id, status).
• Don't assume ordering. Use the payload timestamps (sent_at, delivered_at, read_at, done_at), not arrival order.
• Webhooks beat polling, but GET /v2/messages/{id} is always available to reconcile.

Webhook and delivery receipt catalogue

Every send endpoint links to the events it generates, and this catalogue links back to the operations that cause them, see POST /v2/messages.

Messaging & Contact Book APIs Updated 21 July 2026 · View changelog →

Errors & rate limits

QuickSMS APIs use a consistent error-envelope structure where supported: every non-2xx response gives you an HTTP status, a machine-readable code to branch on, a human-readable message for your logs, and a request_id for support. API-specific rejection codes and asynchronous delivery models are documented separately below.

Four separate vocabularies

Keep these four namespaces apart in your integration; a value from one never appears in another:

The error envelope

Every error on the messaging and Rich RCS surface returns this envelope, including 404 (unknown path), 405 (wrong method), 400 for malformed JSON, and masked 500 responses:

{
  "error": {
    "type": "validation_error",
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "request_id": "0dd0a4d6-d5b2-4df0-bcfa-93e4d95cb64c",
    "errors": {
      "mobile_number": ["The mobile number format is invalid."]
    }
  }
}

Request-level and recipient-level errors

Messaging sends distinguish two failure shapes. A request-level failure (bad credentials, malformed JSON, a missing field) returns the top-level error envelope above and no message record is created. A recipient-level rejection means the request was valid but the message itself was refused; it returns 422 with the rejection inside the messages array:

{
  "total": 1,
  "accepted": 0,
  "rejected": 1,
  "messages": [{
    "mobile_number": "447700900123",
    "MSISDN": "447700900123",
    "status": "REJECTED",
    "error": {
      "code": "SENDER_NOT_REGISTERED",
      "message": "The sender ID is not approved on this account."
    }
  }]
}

• total, accepted and rejected count the recipients in the request; today a send carries one recipient, so the message is either accepted or rejected. The shape is ready for batch sending, where one request will be able to contain both outcomes.
• A rejected message gets no message ID and produces no delivery receipt; the synchronous response is the only record. The Rich RCS endpoint reports the same shape with mobile_number and lowercase rejected.
• Rejections that identify an earlier message, such as DUPLICATE_MESSAGE, include the original message's ID in the response so you can correlate.

HTTP status codes

Request-level error codes

Codes are stable, new ones may be added, so fall back to type for anything unrecognised. Codes marked Contact Book or Messaging are specific to that surface; the rest apply everywhere.

Messaging rejection codes

These codes appear at the recipient level, inside messages[].error on a 422 response, when a valid request was refused for a specific message. No message ID is issued and no delivery receipt follows.

Errors by channel

Which codes and delivery-failure vocabularies apply to the channel you are sending on:

Rate limits

Limits are per credential, per minute, on a rolling 60-second window.

The messaging API reports your live position on every response:

Monitor X-RateLimit-Remaining and throttle your own sending when it falls below roughly 10% of your limit, then ramp back up gradually after the reset. At the limit you receive 429 with Retry-After (header and body). Aggressive retry loops without backoff keep you at the limit indefinitely, always wait the indicated interval. Need more? Contact support with your account ID and workload; per-credential limits can be raised.

Retrying API requests

Not every error should be retried. Decide from the HTTP status:

Recommended backoff, with jitter so concurrent clients don't retry in lockstep:

Stop after five attempts and log the failure with its request_id. Always send the same Idempotency-Key on every retry of a send, so a request that actually landed is replayed rather than duplicated:

const RETRYABLE = new Set([429, 500, 503]);

async function sendWithRetries(payload, idempotencyKey, attempts = 5) {
  for (let attempt = 1; attempt <= attempts; attempt++) {
    const response = await fetch('https://api.quicksms.com/v1/messages', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.QUICKSMS_API_KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey, // same key on every attempt
      },
      body: JSON.stringify(payload),
      signal: AbortSignal.timeout(15000),
    });

    if (response.ok) return response.json();

    const body = await response.json().catch(() => ({}));
    if (!RETRYABLE.has(response.status)) {
      // 400-422: fix the request, don't retry
      throw new Error(`${body.error?.code}: ${body.error?.message} (request_id ${body.error?.request_id})`);
    }

    const retryAfter = Number(response.headers.get('Retry-After'));
    const backoff = retryAfter ? retryAfter * 1000
      : 1000 * 2 ** (attempt - 1) * (0.8 + Math.random() * 0.4);
    console.warn(`Attempt ${attempt} got ${response.status}, request_id ${body.error?.request_id}, waiting ${Math.round(backoff)}ms`);
    await new Promise(resolve => setTimeout(resolve, backoff));
  }
  throw new Error('Send failed after 5 attempts');
}

import os, random, time, requests

RETRYABLE = {429, 500, 503}

def send_with_retries(payload, idempotency_key, attempts=5):
    for attempt in range(1, attempts + 1):
        response = requests.post(
            'https://api.quicksms.com/v1/messages',
            headers={
                'Authorization': f"Bearer {os.environ['QUICKSMS_API_KEY']}",
                'Idempotency-Key': idempotency_key,  # same key on every attempt
            },
            json=payload,
            timeout=15,
        )
        if response.ok:
            return response.json()

        error = response.json().get('error', {})
        if response.status_code not in RETRYABLE:
            # 400-422: fix the request, don't retry
            raise RuntimeError(f"{error.get('code')}: {error.get('message')} (request_id {error.get('request_id')})")

        retry_after = response.headers.get('Retry-After')
        backoff = (float(retry_after) if retry_after
                   else 2 ** (attempt - 1) * random.uniform(0.8, 1.2))
        print(f"Attempt {attempt} got {response.status_code}, request_id {error.get('request_id')}, waiting {backoff:.1f}s")
        time.sleep(backoff)
    raise RuntimeError('Send failed after 5 attempts')

const RETRYABLE = [429, 500, 503];

function sendWithRetries(array $payload, string $idempotencyKey, int $attempts = 5): array
{
    for ($attempt = 1; $attempt <= $attempts; $attempt++) {
        $ch = curl_init('https://api.quicksms.com/v1/messages');
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 15,
            CURLOPT_HTTPHEADER     => [
                'Authorization: Bearer ' . getenv('QUICKSMS_API_KEY'),
                'Content-Type: application/json',
                'Idempotency-Key: ' . $idempotencyKey, // same key on every attempt
            ],
            CURLOPT_POSTFIELDS => json_encode($payload),
            CURLOPT_HEADERFUNCTION => function ($ch, $header) use (&$retryAfter) {
                if (stripos($header, 'Retry-After:') === 0) {
                    $retryAfter = (int) trim(substr($header, 12));
                }
                return strlen($header);
            },
        ]);
        $retryAfter = null;
        $body   = curl_exec($ch);
        $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        $data = json_decode($body, true) ?? [];

        if ($status >= 200 && $status < 300) {
            return $data;
        }
        if (!in_array($status, RETRYABLE, true)) {
            // 400-422: fix the request, don't retry
            throw new RuntimeException(sprintf('%s: %s (request_id %s)',
                $data['error']['code'] ?? $status,
                $data['error']['message'] ?? 'request failed',
                $data['error']['request_id'] ?? 'n/a'));
        }
        $backoff = $retryAfter ?? (2 ** ($attempt - 1)) * (mt_rand(80, 120) / 100);
        error_log(sprintf('Attempt %d got %d, request_id %s, waiting %.1fs',
            $attempt, $status, $data['error']['request_id'] ?? 'n/a', $backoff));
        usleep((int) ($backoff * 1_000_000));
    }
    throw new RuntimeException('Send failed after 5 attempts');
}

static readonly int[] Retryable = { 429, 500, 503 };

static async Task<string> SendWithRetries(object payload, string idempotencyKey, int attempts = 5)
{
    using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(15) };
    client.DefaultRequestHeaders.Add("Authorization",
        $"Bearer {Environment.GetEnvironmentVariable("QUICKSMS_API_KEY")}");
    client.DefaultRequestHeaders.Add("Idempotency-Key", idempotencyKey); // same key on every attempt

    for (var attempt = 1; attempt <= attempts; attempt++)
    {
        var response = await client.PostAsJsonAsync(
            "https://api.quicksms.com/v1/messages", payload);
        var body = await response.Content.ReadAsStringAsync();
        if (response.IsSuccessStatusCode) return body;

        var status = (int)response.StatusCode;
        if (Array.IndexOf(Retryable, status) < 0)
        {
            // 400-422: fix the request, don't retry
            throw new HttpRequestException($"{status}: {body}");
        }
        var retryAfter = response.Headers.RetryAfter?.Delta
            ?? TimeSpan.FromSeconds(Math.Pow(2, attempt - 1) * (0.8 + Random.Shared.NextDouble() * 0.4));
        Console.Error.WriteLine($"Attempt {attempt} got {status}, waiting {retryAfter.TotalSeconds:F1}s; body: {body}");
        await Task.Delay(retryAfter);
    }
    throw new HttpRequestException("Send failed after 5 attempts");
}

static final java.util.Set<Integer> RETRYABLE = java.util.Set.of(429, 500, 503);

static String sendWithRetries(String jsonPayload, String idempotencyKey, int attempts) throws Exception {
    var client = java.net.http.HttpClient.newBuilder()
        .connectTimeout(java.time.Duration.ofSeconds(15)).build();
    var request = java.net.http.HttpRequest.newBuilder()
        .uri(java.net.URI.create("https://api.quicksms.com/v1/messages"))
        .timeout(java.time.Duration.ofSeconds(15))
        .header("Authorization", "Bearer " + System.getenv("QUICKSMS_API_KEY"))
        .header("Content-Type", "application/json")
        .header("Idempotency-Key", idempotencyKey) // same key on every attempt
        .POST(java.net.http.HttpRequest.BodyPublishers.ofString(jsonPayload))
        .build();

    for (int attempt = 1; attempt <= attempts; attempt++) {
        var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() / 100 == 2) return response.body();
        if (!RETRYABLE.contains(response.statusCode())) {
            // 400-422: fix the request, don't retry
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        long backoffMs = response.headers().firstValue("Retry-After")
            .map(v -> Long.parseLong(v) * 1000L)
            .orElse((long) (Math.pow(2, attempt - 1) * (800 + java.util.concurrent.ThreadLocalRandom.current().nextInt(400))));
        System.err.printf("Attempt %d got %d, waiting %dms; body: %s%n",
            attempt, response.statusCode(), backoffMs, response.body());
        Thread.sleep(backoffMs);
    }
    throw new RuntimeException("Send failed after 5 attempts");
}

Idempotency

Network failures leave you unsure whether a write landed. Send an Idempotency-Key header on state-changing requests and retries become safe: a duplicate within 24 hours replays the original response byte-for-byte (flagged with an Idempotent-Replay: true header) instead of repeating the work.

• Key: up to 128 ASCII characters, unique per logical operation. Tie keys to your business event ("order-12345-dispatch") rather than random UUIDs, so retries naturally reuse the same key.
• Scope: per credential; different credentials can use the same key without collision. Test and live are separate credentials, so their key spaces never collide.
• TTL: 24 hours from first use.
• Same key, same body: the original response is replayed instead of repeating the work; the Contact Book flags replays with an Idempotent-Replay: true header, messaging returns the cached 202.
• Same key, different body: 409, protecting you from racing two different operations under one key. Messaging returns IDEMPOTENCY_CONFLICT; the Contact Book returns IDEMPOTENCY_KEY_REUSED.
• Reads: keys are ignored on GET requests. A key longer than 128 characters is rejected with a validation error.

All API surfaces Updated 21 July 2026 · View changelog →

Security best practices

Everything security-related in one checklist: credentials, webhooks, retries and logging. Each item links to the page that documents the mechanism in detail.

Credentials

Webhooks

Requests and retries

All API surfaces Updated 21 July 2026 · View changelog →

Troubleshooting & FAQ

Fix integration problems by the symptom you can see. Each section gives the most likely causes in order, the fix, and a link to the full explanation; the quick answers at the end cover the decisions developers ask about most. Nothing here replaces the reference pages, it routes you to them faster.

Start here: the two-stage check

Every send has two independently checkable stages, and most confusion comes from conflating them. A 202 Accepted means QuickSMS accepted the request; it is not proof of delivery. Delivery is reported asynchronously by the delivery receipt.

1. Check the synchronous response. A non-2xx status or a REJECTED entry in messages[] means the request itself failed; branch on the error.code using the rejection code catalogue. A rejected message gets no ID and no receipt.
2. Then check the delivery receipt. An accepted message reaches a final status (DELIVERED, UNDELIVERED, EXPIRED, REJECTED) with a GSM status code on the Messaging API, or a lowercase lifecycle status with failure.reason on the Rich RCS API. PENDING is not final.

Four separate code vocabularies exist and a value from one never appears in another; if a code looks unfamiliar, first identify which vocabulary you are looking at.

My API call is rejected

401 UNAUTHORIZED or AUTH_RATE_LIMITED

• Wrong credential family: messaging endpoints need an sk_ key, Contact Book endpoints need a cbk_ token. They are not interchangeable.
• Using Basic auth: the key is the username with a blank password, and the trailing colon before base64 encoding is required (base64(api_key:)).
• AUTH_RATE_LIMITED: 10 failed attempts from one IP within 60 seconds locks that IP for 5 minutes; wait for the Retry-After header rather than retrying immediately.

Full rules: Authentication.

403 IP_NOT_ALLOWED

Your connection has an IP allowlist and this request came from an address not on it. Note the asymmetry: messaging returns 403 IP_NOT_ALLOWED, while a Contact Book token outside its allowlist returns 401. Update the allowlist on the connection, or check which egress IP your servers actually use.

SENDER_NOT_REGISTERED or SENDER_NOT_RCS_AGENT

• Alphanumeric sender IDs: maximum 11 characters and must contain at least one letter. Numeric senders: maximum 15 digits. Anything else fails validation before registration is even checked.
• The sender must be registered, approved, and valid for the destination country.
• SENDER_NOT_RCS_AGENT: smart_routing and all rich content require your approved RCS agent name as the sender; an SMS sender ID there is rejected synchronously.

Formats and validation: sender formats.

VALIDATION_ERROR on the recipient number

• Messaging endpoints take digits only, with country code, no +, 7 to 15 digits (447700900123). The Contact Book API differs: E.164 with a leading +.
• On POST /v1/messages, send mobile_number (preferred) or MSISDN (alias), not both with different values. On POST /v2/messages, only mobile_number is accepted.

The full cross-API mapping: field names across the two send APIs.

TEST_NUMBER_NOT_APPROVED

Test keys can only send to numbers on the connection's approved test allowlist. Add the recipient in the portal, or switch to a live key if this is a production send. See test and live environments.

My message was accepted but never arrived

• You are in sandbox mode. A sk_test_ key (or "sandbox": true) never delivers to a handset; receipts are simulated after a few seconds. This is the single most common cause. Check the key prefix and the "sandbox" field in the response.
• Deliberate test outcomes: in sandbox, a recipient number ending 0000 simulates UNDELIVERED (GSM 27) and 9999 simulates EXPIRED (GSM 255).
• The message is HELD: a sending control such as an out-of-hours window is holding it, with scheduled_send_at in the response. Credits are reserved; it sends when the window opens. See sending controls.
• It expired: delivery is attempted for expiry seconds (default 48 hours), then the message ends EXPIRED with a failure receipt, commonly when the handset is off (GSM 27, absent subscriber).
• The receipt is the truth: look up the final status and GSM code rather than assuming; PENDING means not final yet.

My message cost more parts than expected

• GSM-7 texts fit 160 characters in one part (153 per part when concatenated). One character outside GSM-7, including curly quotes or an emoji pasted from a document, silently switches the whole message to UCS-2: 70 characters per part (67 concatenated).
• GSM-7 extension characters (such as €, [, ], ~) count as two characters each.
• The response tells you what happened: check encoding and message_parts; you are billed on message_parts.

Limits and the encoding table: content length limits. The request builder shows encoding and parts live as you type.

My RCS message arrived as SMS

• That is smart routing working, not failing: the recipient's handset or route was not RCS-reachable, so QuickSMS applied your configured SMS fallback. The receipt's channel field reports what was actually delivered.
• If the fallback sender was not what you expected, it was resolved through the four-step priority chain; set an account default sender or pass an explicit fallback sender to control it.
• Billing follows the delivered channel: an RCS-delivered text bills as RCS Basic or RCS Single by length; a fallback SMS bills independently on its own encoding and parts.
• On the Rich RCS API there is no silent downgrade: rich content to a non-RCS recipient uses your explicit fallback object, or fails with a failure.reason if fallback is not enabled.

My webhook signature verification fails

• Wrong base string. Delivery receipts and Inbound V2 SMS sign {timestamp}.{body}; the RCS agent inbound webhook signs the raw body only. Verifying one webhook with the other's base always fails.
• Parsed-then-reserialised body. Compute the HMAC over the raw request bytes before any JSON parsing; frameworks that re-encode the body change the bytes and break the digest.
• The prefix. Strip sha256= from the header value before comparing, and compare in constant time.
• Rotated secret. Rotating a signing secret invalidates the old one immediately; make sure the receiver was updated.

Worked verification code in four languages: signature verification.

I'm not receiving webhooks or inbound messages

• Webhook URLs must be HTTPS; plain HTTP is not accepted.
• Check which URL actually applies: a per-message callback_url overrides the connection default.
• For replies: an alphanumeric sender cannot receive them, send from an inbound number. For RCS replies: the agent must be Live and have inbound configuration enabled.
• Design for the transport's guarantees: expect occasional duplicates (de-duplicate on the message ID) and do not assume ordering.
• Enable a second destination (the portal Inbox or email forwarding) as a safety net while diagnosing, so messages are not lost if your endpoint is down.

My rich card or carousel is rejected

• Per-field limits: title 200, card description 2,000, button and chip labels 25, fallback sms_body 1,530 (CONTENT_TOO_LONG names the field).
• Media URLs must be HTTPS, publicly reachable without authentication, served with an image content type, and must not redirect; see media requirements.
• A rich card needs at least one of title, description or media; horizontal cards require media.
• The sender must be your approved RCS agent, not an SMS sender ID.

The request builder validates all of this before you copy a request.

Quick answers

Which API do I use, /v1 or /v2?

SMS and RCS text: the Messaging API, POST /v1/messages. Cards, carousels and media: the Rich RCS API, POST /v2/messages, which also accepts plain text if you want the structured content model for a new integration. Neither replaces the other; see choose a channel.

Which credential do I need?

Messaging (SMS, RCS text, Rich RCS): an API key, sk_live_ or sk_test_. Contact Book: a scoped token, cbk_. They are separate on purpose: a leaked messaging key cannot read your contacts, and vice versa. See Authentication.

Why does my live RCS send not reach my phone, when sandbox "works"?

Two different test concepts. The API sandbox (sk_test_) never delivers to any handset and simulates receipts. Google's RCS agent test phase is separate: a live (sk_live_) RCS send from an agent still in verification only reaches handsets registered as testers on that agent. See test and live environments.

How long does RCS agent verification take?

Registration includes verification with Google and typically takes 1 to 2 weeks. While the agent is in its test phase, receiving handsets must be added as testers. See Rich RCS.

What happens when the recipient's phone doesn't support RCS?

With smart_routing on the Messaging API, QuickSMS delivers the text as SMS automatically. On the Rich RCS API, your explicit fallback object supplies the SMS rendition; without it the message fails with a failure.reason.

If my RCS message falls back to SMS, what am I billed?

Billing follows the channel actually delivered: RCS text by length (RCS Basic up to 160 characters, RCS Single from 161), or the fallback SMS on its own encoding and parts. They are alternative outcomes, never two charges for one delivery. Wallet reservation detail is in your commercial terms.

How do I retry a failed request safely?

Send an Idempotency-Key header and reuse the same key on retries; it is cached for 24 hours, so a retried send never delivers twice. Respect Retry-After on 429. The full production pattern is in retrying API requests.

Should I use mobile_number or MSISDN?

Use mobile_number everywhere; it works on both send APIs and is echoed in responses. MSISDN remains fully supported on /v1/messages as an alias for existing integrations, with no deprecation. Never send both with different values.

Contacting support

So the first reply can be the fix, include:

• The request_id from the error envelope (every non-2xx response carries one), or the message ID (quicksms_id / message_id) for delivery questions.
• The endpoint, the environment (test or live), and the timestamp with timezone.
• For delivery issues: the recipient number and the receipt you received (or that none arrived).
• For webhook issues: the raw request body and headers exactly as received.

Never include a full API key or signing secret in a support message; the key prefix and the connection name identify it.

Messaging API & Rich RCS Updated 21 July 2026 · View changelog →

API reference

Field-by-field reference for every endpoint. Messaging and Rich RCS endpoints authenticate with a Messaging API key (sk_…); Contact Book endpoints with a scoped token (cbk_…), see which credential you need. URL paths contain version numbers for historical reasons; they do not indicate product generations.

Field names across the two send APIs

The Messaging API and the Rich RCS API describe the same concepts with different field names and status vocabularies. If you integrate both, this is the mapping. The recipient field has converged on mobile_number in both the request and the send response, but the other names still differ per surface.

Messaging API

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

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...

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

Rich RCS API

A first-class peer to the Messaging API, opt-in, for rich content. Rich RCS is opt-in on a separate endpoint; every existing integration continues to work with zero changes.

{
  "sandbox": false,
  "total": 1,
  "accepted": 1,
  "rejected": 0,
  "messages": [{
    "message_id": "msg_42a731415e521124",
    "to": "447700900123",
    "sender": "YOUR_SENDER_ID",
    "status": "queued",
    "channel": "SMS",
    "content_type": "text",
    "cost": 0.04
  }],
  "created_at": "2026-07-14T10:10:59+00:00"
}

{
  "message_id": "msg_42a731415e521124",
  "to": "447700900123",
  "sender": "MyBrandAgent",
  "channel": "RCS",
  "content_type": "rich_card",
  "created_at": "2026-07-14T10:10:59+01:00",
  "cost": 0.10,
  "status": "read",
  "read_at": "2026-07-14T10:11:12+01:00"
}

Contact Book endpoints

The Contact Book API has its own complete reference covering all 47 endpoints, every scope, parameter and response: Contact Book reference.

Contact Book API v1.1 Updated 21 July 2026 · View changelog →

Contact Book reference

Every Contact Book API v1 endpoint: 47 operations across contacts, tags, lists, opt-outs and custom fields, plus operations and diagnostics. Base URL https://api.quicksms.com/v1, Bearer cbk_… token, and the shared error, idempotency and pagination conventions throughout. Expand any endpoint for parameters, examples and responses.

Contacts

Manage individual contacts and run bulk operations.

curl 'https://api.quicksms.com/v1/contacts?per_page=25&status=active' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/contacts?per_page=25&status=active', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/contacts?per_page=25&status=active',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": [
        {
            "id": "9c8b1a2e-…",
            "mobile_number": "+447700900123",
            "first_name": "Alice",
            "last_name": "Smith",
            "email": "alice@example.com",
            "status": "active",
            "source": "manual",
            "created_at": "2026-05-30T14:22:11Z"
        }
    ],
    "total": 152,
    "per_page": 25,
    "current_page": 1,
    "last_page": 7
}

curl 'https://api.quicksms.com/v1/contacts/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/contacts/uuid', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/contacts/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "id": "9c8b1a2e-…",
        "mobile_number": "+447700900123",
        "first_name": "Alice",
        "last_name": "Smith",
        "email": "alice@example.com",
        "date_of_birth": "1990-04-15",
        "postcode": "SW1A 1AA",
        "city": "London",
        "country": "GB",
        "customer_id": "shopify_cus_1234567",
        "status": "active",
        "tags": [
            {
                "id": "uuid",
                "name": "VIP",
                "color": "#6f42c1"
            }
        ],
        "lists": [
            {
                "id": "uuid",
                "name": "Newsletter Subscribers"
            }
        ],
        "custom_data": {
            "loyalty_tier": "gold"
        },
        "created_at": "2026-05-30T14:22:11Z"
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"mobile_number":"+447700900123","first_name":"Alice","last_name":"Smith","email":"alice@example.com","customer_id":"shopify_cus_1234567","country":"GB","custom_data":{"loyalty_tier":"gold"}}'

const response = await fetch('https://api.quicksms.com/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "mobile_number": "+447700900123",
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice@example.com",
    "customer_id": "shopify_cus_1234567",
    "country": "GB",
    "custom_data": {
        "loyalty_tier": "gold"
    }
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "mobile_number": "+447700900123",
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice@example.com",
    "customer_id": "shopify_cus_1234567",
    "country": "GB",
    "custom_data": {
        "loyalty_tier": "gold"
    }
},
)
data = response.json()

{
    "data": {
        "id": "9c8b1a2e-…",
        "mobile_number": "+447700900123",
        "first_name": "Alice",
        "status": "active",
        "created_at": "2026-06-03T07:30:00Z"
    }
}

curl -X PUT 'https://api.quicksms.com/v1/contacts/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"first_name":"Alicia","email":"alicia@example.com"}'

const response = await fetch('https://api.quicksms.com/v1/contacts/uuid', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "first_name": "Alicia",
    "email": "alicia@example.com"
}),
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.quicksms.com/v1/contacts/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "first_name": "Alicia",
    "email": "alicia@example.com"
},
)
data = response.json()

{
    "data": {
        "id": "9c8b1a2e-…",
        "first_name": "Alicia",
        "email": "alicia@example.com"
    }
}

curl -X DELETE 'https://api.quicksms.com/v1/contacts/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/contacts/uuid', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.quicksms.com/v1/contacts/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "message": "Contact deleted"
    }
}

curl 'https://api.quicksms.com/v1/contacts/uuid/mobile' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/contacts/uuid/mobile', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/contacts/uuid/mobile',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "mobile_number": "+447700900123"
}

curl 'https://api.quicksms.com/v1/contacts/stats' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/contacts/stats', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/contacts/stats',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "total": 152,
    "active": 148,
    "opted_out": 4,
    "recent_7d": 12
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk-import' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contacts":[{"mobile_number":"+447700900001","first_name":"Alice"},{"mobile_number":"+447700900002","first_name":"Bob"}]}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk-import', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contacts": [
        {
            "mobile_number": "+447700900001",
            "first_name": "Alice"
        },
        {
            "mobile_number": "+447700900002",
            "first_name": "Bob"
        }
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk-import',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contacts": [
        {
            "mobile_number": "+447700900001",
            "first_name": "Alice"
        },
        {
            "mobile_number": "+447700900002",
            "first_name": "Bob"
        }
    ]
},
)
data = response.json()

{
    "data": {
        "inserted": 2,
        "skipped": 0,
        "total": 2
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/add-tags' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1","uuid-2"],"tags":["VIP","Newsletter"]}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/add-tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ],
    "tags": [
        "VIP",
        "Newsletter"
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/add-tags',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ],
    "tags": [
        "VIP",
        "Newsletter"
    ]
},
)
data = response.json()

{
    "data": {
        "message": "Added tag(s) \"VIP\" to 2 contact(s)",
        "affectedCount": 2
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/remove-tags' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1"],"tags":["VIP"]}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/remove-tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1"
    ],
    "tags": [
        "VIP"
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/remove-tags',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1"
    ],
    "tags": [
        "VIP"
    ]
},
)
data = response.json()

{
    "data": {
        "affectedCount": 1
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/add-to-list' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1"],"list_name":"Newsletter Subscribers"}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/add-to-list', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1"
    ],
    "list_name": "Newsletter Subscribers"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/add-to-list',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1"
    ],
    "list_name": "Newsletter Subscribers"
},
)
data = response.json()

{
    "data": {
        "affectedCount": 1
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/remove-from-list' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1"],"list_name":"Newsletter Subscribers"}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/remove-from-list', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1"
    ],
    "list_name": "Newsletter Subscribers"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/remove-from-list',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1"
    ],
    "list_name": "Newsletter Subscribers"
},
)
data = response.json()

{
    "data": {
        "affectedCount": 1
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/add-to-opt-out' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1"],"opt_out_list_id":"list-uuid"}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/add-to-opt-out', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1"
    ],
    "opt_out_list_id": "list-uuid"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/add-to-opt-out',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1"
    ],
    "opt_out_list_id": "list-uuid"
},
)
data = response.json()

{
    "data": {
        "affectedCount": 1
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/remove-from-opt-out' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1"],"opt_out_list_id":"list-uuid"}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/remove-from-opt-out', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1"
    ],
    "opt_out_list_id": "list-uuid"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/remove-from-opt-out',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1"
    ],
    "opt_out_list_id": "list-uuid"
},
)
data = response.json()

{
    "data": {
        "affectedCount": 1
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/delete' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1","uuid-2"]}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/delete', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/delete',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ]
},
)
data = response.json()

{
    "data": {
        "affectedCount": 2
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/add-tags-by-filter' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"filter":{"status":"active","country":"GB"},"expected_count":50000,"tags":["UK Active"]}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/add-tags-by-filter', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
        "status": "active",
        "country": "GB"
    },
    "expected_count": 50000,
    "tags": [
        "UK Active"
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/add-tags-by-filter',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "filter": {
        "status": "active",
        "country": "GB"
    },
    "expected_count": 50000,
    "tags": [
        "UK Active"
    ]
},
)
data = response.json()

{
    "data": {
        "operation_id": "op-uuid",
        "status": "queued",
        "total_items": 50000
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/remove-tags-by-filter' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"filter":{"tag_id":"old-tag-uuid"},"expected_count":12000,"tags":["Old Promo"]}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/remove-tags-by-filter', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
        "tag_id": "old-tag-uuid"
    },
    "expected_count": 12000,
    "tags": [
        "Old Promo"
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/remove-tags-by-filter',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "filter": {
        "tag_id": "old-tag-uuid"
    },
    "expected_count": 12000,
    "tags": [
        "Old Promo"
    ]
},
)
data = response.json()

{
    "data": {
        "operation_id": "op-uuid",
        "status": "queued",
        "total_items": 12000
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/add-to-list-by-filter' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"filter":{"country":"GB"},"expected_count":30000,"list_name":"UK Customers"}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/add-to-list-by-filter', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
        "country": "GB"
    },
    "expected_count": 30000,
    "list_name": "UK Customers"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/add-to-list-by-filter',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "filter": {
        "country": "GB"
    },
    "expected_count": 30000,
    "list_name": "UK Customers"
},
)
data = response.json()

{
    "data": {
        "operation_id": "op-uuid",
        "status": "queued",
        "total_items": 30000
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/remove-from-list-by-filter' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"filter":{"list_id":"list-uuid"},"expected_count":5000,"list_name":"Old List"}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/remove-from-list-by-filter', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
        "list_id": "list-uuid"
    },
    "expected_count": 5000,
    "list_name": "Old List"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/remove-from-list-by-filter',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "filter": {
        "list_id": "list-uuid"
    },
    "expected_count": 5000,
    "list_name": "Old List"
},
)
data = response.json()

{
    "data": {
        "operation_id": "op-uuid",
        "status": "queued",
        "total_items": 5000
    }
}

curl -X POST 'https://api.quicksms.com/v1/contacts/bulk/delete-by-filter' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"filter":{"status":"opted_out"},"expected_count":8000}'

const response = await fetch('https://api.quicksms.com/v1/contacts/bulk/delete-by-filter', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "filter": {
        "status": "opted_out"
    },
    "expected_count": 8000
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/contacts/bulk/delete-by-filter',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "filter": {
        "status": "opted_out"
    },
    "expected_count": 8000
},
)
data = response.json()

{
    "data": {
        "operation_id": "op-uuid",
        "status": "queued",
        "total_items": 8000
    }
}

Tags

Manage labels for grouping contacts. Tags are account-scoped and may have a colour.

curl 'https://api.quicksms.com/v1/tags' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/tags', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/tags',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": [
        {
            "id": "uuid",
            "name": "VIP",
            "color": "#6f42c1",
            "contact_count": 42
        },
        {
            "id": "uuid",
            "name": "Newsletter",
            "color": "#0d6efd",
            "contact_count": 1024
        }
    ]
}

curl -X POST 'https://api.quicksms.com/v1/tags' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"VIP","color":"#6f42c1"}'

const response = await fetch('https://api.quicksms.com/v1/tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "VIP",
    "color": "#6f42c1"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/tags',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "name": "VIP",
    "color": "#6f42c1"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "name": "VIP",
        "color": "#6f42c1",
        "contact_count": 0
    }
}

curl -X PUT 'https://api.quicksms.com/v1/tags/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"VVIP","color":"#dc2626"}'

const response = await fetch('https://api.quicksms.com/v1/tags/uuid', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "VVIP",
    "color": "#dc2626"
}),
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.quicksms.com/v1/tags/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "name": "VVIP",
    "color": "#dc2626"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "name": "VVIP",
        "color": "#dc2626"
    }
}

curl -X DELETE 'https://api.quicksms.com/v1/tags/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/tags/uuid', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.quicksms.com/v1/tags/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "message": "Tag deleted"
    }
}

Lists

Manage contact lists (static membership) and their members.

curl 'https://api.quicksms.com/v1/lists' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/lists', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/lists',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": [
        {
            "id": "uuid",
            "name": "Newsletter Subscribers",
            "description": "Opted-in subscribers",
            "type": "static",
            "contact_count": 1024,
            "created_at": "2026-05-01T10:00:00Z"
        }
    ]
}

curl -X POST 'https://api.quicksms.com/v1/lists' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"VIP Customers","description":"High-value customer list","contact_ids":["uuid-1","uuid-2"]}'

const response = await fetch('https://api.quicksms.com/v1/lists', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "VIP Customers",
    "description": "High-value customer list",
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/lists',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "name": "VIP Customers",
    "description": "High-value customer list",
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ]
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "name": "VIP Customers",
        "contact_count": 2,
        "type": "static"
    }
}

curl -X PUT 'https://api.quicksms.com/v1/lists/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"VIP Customers (2026)","description":"Updated description"}'

const response = await fetch('https://api.quicksms.com/v1/lists/uuid', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "VIP Customers (2026)",
    "description": "Updated description"
}),
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.quicksms.com/v1/lists/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "name": "VIP Customers (2026)",
    "description": "Updated description"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "name": "VIP Customers (2026)"
    }
}

curl -X DELETE 'https://api.quicksms.com/v1/lists/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/lists/uuid', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.quicksms.com/v1/lists/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "message": "List deleted"
    }
}

curl -X POST 'https://api.quicksms.com/v1/lists/uuid/members' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1","uuid-2"]}'

const response = await fetch('https://api.quicksms.com/v1/lists/uuid/members', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/lists/uuid/members',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1",
        "uuid-2"
    ]
},
)
data = response.json()

{
    "data": {
        "added": 2
    }
}

curl -X DELETE 'https://api.quicksms.com/v1/lists/uuid/members' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contact_ids":["uuid-1"]}'

const response = await fetch('https://api.quicksms.com/v1/lists/uuid/members', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_ids": [
        "uuid-1"
    ]
}),
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.quicksms.com/v1/lists/uuid/members',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contact_ids": [
        "uuid-1"
    ]
},
)
data = response.json()

{
    "data": {
        "removed": 1
    }
}

curl -X POST 'https://api.quicksms.com/v1/lists/uuid/members/bulk-import' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"contacts":[{"mobile_number":"+447700900001","first_name":"Alice"},{"mobile_number":"+447700900002"}]}'

const response = await fetch('https://api.quicksms.com/v1/lists/uuid/members/bulk-import', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contacts": [
        {
            "mobile_number": "+447700900001",
            "first_name": "Alice"
        },
        {
            "mobile_number": "+447700900002"
        }
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/lists/uuid/members/bulk-import',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "contacts": [
        {
            "mobile_number": "+447700900001",
            "first_name": "Alice"
        },
        {
            "mobile_number": "+447700900002"
        }
    ]
},
)
data = response.json()

{
    "data": {
        "new_contacts": 1,
        "existing_contacts": 1,
        "added_to_list": 2
    }
}

Opt-outs

Manage opt-out lists and individual records. Use the check endpoint before sending to verify consent.

curl 'https://api.quicksms.com/v1/opt-out-lists' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/opt-out-lists', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/opt-out-lists',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": [
        {
            "id": "uuid",
            "name": "Master Opt-Out",
            "is_master": true,
            "count": 4
        },
        {
            "id": "uuid",
            "name": "Campaign X Opt-Outs",
            "is_master": false,
            "count": 12
        }
    ]
}

curl -X POST 'https://api.quicksms.com/v1/opt-out-lists' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Campaign X Opt-Outs","description":"Opt-outs from the Campaign X promo"}'

const response = await fetch('https://api.quicksms.com/v1/opt-out-lists', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Campaign X Opt-Outs",
    "description": "Opt-outs from the Campaign X promo"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/opt-out-lists',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "name": "Campaign X Opt-Outs",
    "description": "Opt-outs from the Campaign X promo"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "name": "Campaign X Opt-Outs",
        "is_master": false,
        "count": 0
    }
}

curl -X PUT 'https://api.quicksms.com/v1/opt-out-lists/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Campaign X Opt-Outs (closed)"}'

const response = await fetch('https://api.quicksms.com/v1/opt-out-lists/uuid', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Campaign X Opt-Outs (closed)"
}),
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.quicksms.com/v1/opt-out-lists/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "name": "Campaign X Opt-Outs (closed)"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "name": "Campaign X Opt-Outs (closed)"
    }
}

curl -X DELETE 'https://api.quicksms.com/v1/opt-out-lists/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/opt-out-lists/uuid', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.quicksms.com/v1/opt-out-lists/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "message": "Opt-out list deleted"
    }
}

curl 'https://api.quicksms.com/v1/opt-out-lists/list-uuid/records' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/opt-out-lists/list-uuid/records', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/opt-out-lists/list-uuid/records',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": [
        {
            "id": "uuid",
            "mobile_number": "+447700900099",
            "source": "sms_reply",
            "created_at": "2026-05-30T12:00:00Z"
        }
    ],
    "total": 1,
    "per_page": 25,
    "current_page": 1,
    "last_page": 1
}

curl 'https://api.quicksms.com/v1/opt-out-records?opt_out_list_id=list-uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/opt-out-records?opt_out_list_id=list-uuid', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/opt-out-records?opt_out_list_id=list-uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": [
        {
            "id": "uuid",
            "mobile_number": "+447700900099",
            "source": "sms_reply",
            "opt_out_list_id": "uuid",
            "created_at": "2026-05-30T12:00:00Z"
        }
    ],
    "total": 42,
    "per_page": 25,
    "current_page": 1,
    "last_page": 2
}

curl -X POST 'https://api.quicksms.com/v1/opt-out-lists/list-uuid/records' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"mobile_number":"+447700900099","source":"manual","campaign_ref":"promo-2026"}'

const response = await fetch('https://api.quicksms.com/v1/opt-out-lists/list-uuid/records', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "mobile_number": "+447700900099",
    "source": "manual",
    "campaign_ref": "promo-2026"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/opt-out-lists/list-uuid/records',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "mobile_number": "+447700900099",
    "source": "manual",
    "campaign_ref": "promo-2026"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "mobile_number": "+447700900099",
        "source": "manual"
    }
}

curl -X POST 'https://api.quicksms.com/v1/opt-out-lists/list-uuid/records/bulk-import' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"records":[{"mobile_number":"+447700900099"},{"mobile_number":"+447700900100","source":"upload"}]}'

const response = await fetch('https://api.quicksms.com/v1/opt-out-lists/list-uuid/records/bulk-import', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "records": [
        {
            "mobile_number": "+447700900099"
        },
        {
            "mobile_number": "+447700900100",
            "source": "upload"
        }
    ]
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/opt-out-lists/list-uuid/records/bulk-import',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "records": [
        {
            "mobile_number": "+447700900099"
        },
        {
            "mobile_number": "+447700900100",
            "source": "upload"
        }
    ]
},
)
data = response.json()

{
    "data": {
        "inserted": 2,
        "skipped": 0,
        "total": 2
    }
}

curl -X DELETE 'https://api.quicksms.com/v1/opt-out-records/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/opt-out-records/uuid', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.quicksms.com/v1/opt-out-records/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "message": "Opt-out record deleted"
    }
}

curl 'https://api.quicksms.com/v1/opt-out-records/uuid/mobile' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/opt-out-records/uuid/mobile', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/opt-out-records/uuid/mobile',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "mobile_number": "+447700900099"
}

curl -X POST 'https://api.quicksms.com/v1/opt-out-records/move' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"record_ids":["uuid-1","uuid-2"],"target_opt_out_list_id":"list-uuid"}'

const response = await fetch('https://api.quicksms.com/v1/opt-out-records/move', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "record_ids": [
        "uuid-1",
        "uuid-2"
    ],
    "target_opt_out_list_id": "list-uuid"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/opt-out-records/move',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "record_ids": [
        "uuid-1",
        "uuid-2"
    ],
    "target_opt_out_list_id": "list-uuid"
},
)
data = response.json()

{
    "data": {
        "moved": 2
    }
}

curl 'https://api.quicksms.com/v1/opt-outs/check?mobile_number=%2B447700900099' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/opt-outs/check?mobile_number=%2B447700900099', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/opt-outs/check?mobile_number=%2B447700900099',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "mobile_number": "+447700900099",
    "is_opted_out": true,
    "lists": [
        {
            "id": "uuid",
            "name": "Master Opt-Out",
            "is_master": true,
            "source": "sms_reply"
        }
    ]
}

Custom fields

Manage custom field definitions for contacts. Values are stored in each contact's custom_data object.

curl 'https://api.quicksms.com/v1/custom-fields' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/custom-fields', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/custom-fields',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": [
        {
            "id": "uuid",
            "key": "loyalty_tier",
            "label": "Loyalty Tier",
            "type": "string"
        },
        {
            "id": "uuid",
            "key": "join_date",
            "label": "Join Date",
            "type": "date"
        }
    ]
}

curl -X POST 'https://api.quicksms.com/v1/custom-fields' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"key":"loyalty_tier","label":"Loyalty Tier","type":"string"}'

const response = await fetch('https://api.quicksms.com/v1/custom-fields', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "key": "loyalty_tier",
    "label": "Loyalty Tier",
    "type": "string"
}),
});
const data = await response.json();

import requests

response = requests.post(
    'https://api.quicksms.com/v1/custom-fields',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "key": "loyalty_tier",
    "label": "Loyalty Tier",
    "type": "string"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "key": "loyalty_tier",
        "label": "Loyalty Tier",
        "type": "string"
    }
}

curl -X PUT 'https://api.quicksms.com/v1/custom-fields/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token' \
  -H 'Content-Type: application/json' \
  -d '{"label":"Loyalty Tier (Updated)"}'

const response = await fetch('https://api.quicksms.com/v1/custom-fields/uuid', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "label": "Loyalty Tier (Updated)"
}),
});
const data = await response.json();

import requests

response = requests.put(
    'https://api.quicksms.com/v1/custom-fields/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
    json={
    "label": "Loyalty Tier (Updated)"
},
)
data = response.json()

{
    "data": {
        "id": "uuid",
        "label": "Loyalty Tier (Updated)"
    }
}

curl -X DELETE 'https://api.quicksms.com/v1/custom-fields/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/custom-fields/uuid', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.delete(
    'https://api.quicksms.com/v1/custom-fields/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "message": "Custom field deleted"
    }
}

Operations & diagnostics

Track asynchronous bulk operations, verify tokens, and manage the sandbox.

curl 'https://api.quicksms.com/v1/operations/uuid' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/operations/uuid', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://api.quicksms.com/v1/operations/uuid',
    headers={'Authorization': 'Bearer cbk_test_your_token'},
)
data = response.json()

{
    "data": {
        "operation_id": "op_8a7f6b4e-…",
        "type": "contacts.bulk_add_tags_by_filter",
        "status": "completed",
        "created_at": "2026-06-08T10:23:45Z",
        "started_at": "2026-06-08T10:23:46Z",
        "completed_at": "2026-06-08T10:24:12Z",
        "progress": {
            "total": 50000,
            "completed": 50000,
            "failed": 0
        },
        "result": {
            "affectedCount": 50000,
            "tags_applied": [
                "UK Active"
            ]
        }
    }
}

curl 'https://api.quicksms.com/v1/ping' \
  -H 'Authorization: Bearer cbk_test_your_token'

const response = await fetch('https://api.quicksms.com/v1/ping', {
  headers: {
    Authorization: 'Bearer cbk_test_your_token',
  },
});
const data = await response.json();