API v1

Quathos SMS developer docs

Quathos SMS sends transactional email, one-time codes and campaigns behind one account and one token. The public API is REST over JSON, versioned in the path. Requests and responses are JSON, timestamps are UTC in ISO 8601, identifiers are UUIDs you can store as opaque strings. Everything below works in both the test and live environments: the token prefix decides which.

Get started Send email

Copy, paste, run

Send your first email in the language you already use.

curl -X POST https://api.mailer.quathos.com/api/v1/sms/messages \
  -H "Authorization: Bearer $QSENDYX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": "QSENDYX",
    "to":   "+5511999998888",
    "body": "Your code is 481902"
  }'

Response: 202 Accepted · { "id": "…", "status": "queued" }

Jump straight to what you need.

Getting started Every call carries a bearer token. Its prefix tells you the environment; its scopes tell you what it may do. OTP and verification The Verify endpoints handle one-time codes end to end: generation, expiry, attempt limits and validation. You never store the code. Webhooks Register an HTTPS endpoint and receive delivery events. Verify the signature, apply idempotency, and let status come to you.

When something fails

Every error returns the same shape: an HTTP status and a stable code you can branch on.

code	Status	When
`invalid_token`	401	Missing, malformed or revoked token.
`insufficient_scope`	403	Token lacks the scope for this call.
`insufficient_balance`	402	The wallet cannot cover the send or the reservation. Top up and retry.
`not_found`	404	Resource does not exist in your tenant.
`duplicate_request`	409	Same key reused with a different payload.
`suppressed_recipient`	403	Recipient is on the suppression list; nothing was sent.
`destination_not_allowed`	403	SMS destination not enabled for your account. US needs 10DLC, Canada a dedicated number.
`destination_not_verified`	403	Evaluation mode: until your first top-up, SMS only goes to numbers verified in the dashboard (SMS → Verified numbers).
`invalid_sender`	403	Sender not usable: number you do not own, or a protected brand name without the verified domain.
`rate_limit_exceeded`	429	Too many requests, or an SMS anti-fraud ceiling: back off and retry.

See the full error reference →

Frequently asked questions

Test freely

Use a test token while you integrate: it runs the full pipeline on isolated data, never emails a real recipient and never spends balance. Switch to a live token when you go to production.

Next Authentication