Send SMS from your code, under your own brand.

1. Buy SMS credits and get a sender ID approved. Apply on Sender IDs in your dashboard.
2. Create an API key on API keys. It is shown once, so store it in your server's environment (never in a browser or mobile app).
3. Send your first message:

curl https://www.ceytrexlabs.com/api/v1/sms/send \
  -H "Authorization: Bearer $CEYTREX_SMS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10293" \
  -d '{
    "sender_id": "ACME",
    "to": ["0771234567", "+94712345678"],
    "body": "ACME: Your order #10293 has shipped.",
    "type": "transactional"
  }'

Prefer clicking first? Send a test SMS from the dashboard. It goes through the same pipeline as the API.

Every request carries your key in the Authorization header. Keys look like ceysk_live_ followed by 40 letters and digits.

Authorization: Bearer ceysk_live_3kQ9...

• We store only a one-way HMAC-SHA256 hash, so a lost key can't be recovered. Revoke it and create another.
• Use one key per system. Up to 10 active keys per account; each shows when it was last used.
• A missing, wrong or revoked key answers 401 unauthenticated.

Sri Lankan networks block SMS from unregistered sender names, so every send names one of your approved sender IDs in sender_id, exactly as approved (case matters). Anything else answers 403 sender_id_not_approved.

Sender IDs are 3 to 11 characters, contain at least one letter, and must match your business or brand. Apply with your business registration and an authorisation letter on /dashboard/sms/sender-ids. Use separate sender IDs for transactional and promotional traffic where you can.

POST/api/v1/sms/send

Sends the same body to 1 to 1,000 numbers. Credits for every recipient are taken before anything goes out, and refunded automatically for any message the network refuses or fails to deliver.

Response (200):

{
  "id": "6f1c2a0e-9b1d-4c55-8a8e-2b7d1f0c9a11",
  "object": "sms.batch",
  "sender_id": "ACME",
  "type": "transactional",
  "encoding": "GSM-7",
  "segments_per_message": 1,
  "recipients": { "accepted": 2, "invalid": [], "duplicates_removed": 0 },
  "credits_charged": 2,
  "credits_refunded": 0,
  "balance_after": 4818,
  "levy": { "applies": false },
  "messages": [
    { "id": "0b8e...e1", "to": "+94771234567", "status": "sent", "error": null },
    { "id": "4c1a...7f", "to": "+94712345678", "status": "sent", "error": null }
  ],
  "created_at": "2026-10-19T09:32:11.000Z"
}

credits_charged is what the send cost after refunds, and balance_after is your wallet afterwards. Scheduled sends are not available yet; a scheduled_at field is refused rather than ignored.

One credit pays for one SMS part to one number. Long messages are split into parts, and each part carries a small header, so the per-part limit drops once a message is split.

• One Sinhala or Tamil letter switches the whole message to Unicode. A 100-character English message with one Sinhala word becomes 2 parts.
• In GSM-7, the characters ^ { } [ ] ~ | € \ count as two.
• Emoji outside the basic plane (most of them) count as two Unicode characters.
• Every response tells you the encoding and segments_per_message, and the dashboard test form counts parts as you type.

Sri Lanka treats marketing SMS differently from service messages (TRCSL guideline, Gazette 2104/16). Mark offers, discounts and campaigns as "type": "promotional". The API then enforces:

• Hours: 08:00 to 20:00 Sri Lanka time only. Outside that window the send answers 422 quiet_hours with next_window_at and a Retry-After header.
• Opt-out: every promotional message must say how to stop, for example "Opt out: reply STOP" or an unsubscribe link. Without one it answers 400 opt_out_missing.
• Levy: the government levy of LKR 0.25 per promotional SMS is included in our per-SMS price, so promotional parts cost the same one credit. The response's levy object shows this.
• Send only to people who agreed to hear from you, and keep a record of that consent.

Transactional messages (OTPs, delivery updates, bills) are not limited by these rules.

GET/api/v1/sms/balance

{
  "object": "sms.balance",
  "credits": 4818,
  "currency": "LKR",
  "rate_per_credit": "0.85",
  "value": "4095.30"
}

Top up from Enterprise SMS pricing. Credits are added as soon as the payment clears.

GET/api/v1/sms/messages/{id}

GET/api/v1/sms/messages?since=&status=&before=&limit=

Look up one message, or list your messages newest first. since and before take ISO 8601 times, status filters, and limit is 1 to 100 (default 50). When has_more is true, pass next_before as before to get the next page.

The mobile networks report delivery back to us through a signed delivery-report webhook, and we update each message's status. Reports can arrive out of order, so a final status (delivered, failed, rejected) is never overwritten by a later "sent". A message that fails delivery is refunded once, however many reports arrive.

To follow delivery from your side, poll GET /api/v1/sms/messages?since= with the time of your last poll, or look up the ids you got back from the send. Push webhooks to your own URL are planned; ask us if you need them early.

Networks drop connections. To retry safely, send an Idempotency-Key header (or a client_reference field) of up to 100 visible characters, such as your order id.

• Same key, same body: you get the original result back (with idempotent_replay: true), and nothing is sent or charged twice.
• Same key, different body: 409 idempotency_conflict.
• If the whole send failed upstream (502 upstream_unavailable), the key is released, so retrying with it sends for real.

Each key may send up to 1,000 messages (recipients) in any rolling minute. Over the limit, the send answers 429 rate_limited with Retry-After. Successful sends return RateLimit-Limit and RateLimit-Remaining headers. Need more? Talk to us about a higher limit.

Errors always use the same JSON envelope and a stable code you can branch on. Quote the request_id when you contact support.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough SMS credits for this send. Top up and try again.",
    "credits_required": 120,
    "balance": 40,
    "request_id": "req_k2V9xQ1bT0aZ",
    "doc_url": "https://www.ceytrexlabs.com/developers/sms#error-insufficient_credits"
  }
}