Bhutan SMSC API

Quickstart

Create an account and you are issued a sandbox key immediately. Sandbox sends are free, simulated end to end, and never reach a handset — so this works before you have paid anything.

# 1. price it — free, and no account needed at all
curl -X POST https://smsc.bt/api/quote \
  -d 'to=17123456' -d 'body=Your code is 481920'

# 2. send it
curl -X POST https://smsc.bt/api/v1/messages \
  -H "Authorization: Bearer bsk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"to":"17123456","body":"Your code is 481920"}'

# 202 Accepted
{
  "accepted": 1,
  "rejected": 0,
  "cost_uusd": 100000,
  "hold_seconds": 15,
  "undo_url": "/api/v1/batches/xk29fj…",
  "results": [{ "to": "97517123456", "accepted": true,
                "carrier": "btl", "segments": 1 }]
}

Try it live

This fires real HTTP requests from your browser at this deployment, and writes the matching client code as you type. It is the same request either way — the code below is what the button above it sends, not a rendering of what it might send.

Pick an endpoint and press Send request.

Pick an endpoint above.

Authentication

Send your key as a bearer token. X-Api-Key is accepted identically if that suits your client better.

Authorization: Bearer bsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-Api-Key: bsk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys carry scopes, and the endpoint decides which one it needs — you never request a scope per call.

A reporting script does not need send, and a key issued without it cannot spend your credit even if it leaks. Keys can also be pinned to an IP allowlist. A revoked key stops working on its very next call — there is no cache to wait out.

Sandbox vs live

The mode is a property of the key, not of the request. A bsk_test_ key always simulates: nothing reaches a carrier, nothing is charged, and the full API — receipts, status transitions, error codes — behaves exactly as it does live. A bsk_live_ key sends to real handsets and spends real credit.

This is deliberate: there is no request flag that can be forgotten and accidentally bill you.

Numbers and routing

We accept a Bhutanese number in any form you have it and normalise before routing, so all of these are the same recipient:

17123456        # bare national
+975 17 12 34 56
0097517123456
97517123456     # canonical, and what we store

The prefix decides the network: 16 and 17 are B-Mobile, 77 is TashiCell. Anything else is refused at the boundary with unroutable_number and is not charged. A foreign number returns unroutable_number rather than invalid_number — it is a real phone number, just not one we carry.

Filtering with ?to= normalises the same way, so the string you sent finds the message you sent with it.

Segments and encoding

You are billed per segment, not per message. This is the one thing worth understanding before you go live.

A single character outside the GSM alphabet moves the whole message to UCS-2. A word processor's curly apostrophe is the usual culprit, and it can turn a one-segment message into two.

POST /api/v1/validate returns the exact count and cost before you commit, from the same code that does the charging. Use it — it is free and it does not create a message.

The undo window

Every send is held for a few seconds before it is handed to a carrier, and can be withdrawn in full during that window. The response tells you how long you have:

{ "hold_seconds": 15, "undo_url": "/api/v1/batches/xk29fj…" }

# withdraw the whole send
curl -X DELETE https://smsc.bt/api/v1/batches/xk29fj… \
  -H "Authorization: Bearer bsk_live_…"

{ "cancelled": 3, "already_sent": 0, "complete": true,
  "refunded_uusd": 300000 }

Once the window closes there is no recall — the message is on a carrier's dispatcher and neither we nor SMPP can take it back. A cancel attempt after that returns not_cancellable rather than pretending. Set hold_seconds: 0 to skip the window.

Status and receipts

Submission and delivery are two different facts and we never merge them. submitted means a carrier accepted the message. Only delivered — which requires a carrier receipt — means a handset got it.

Webhooks

You can register a receipt endpoint at Settings on a plan that includes them, and the registration is stored with its own signing secret.

Poll instead, for now. GET /api/v1/messages/{id} carries status and a receipts array, and GET /api/v1/batches/{id} gives status_counts for a whole send in one call — which is the cheaper thing to poll after sending in bulk. Check GET /api/v1/health first: while carrier_delivery is false, messages stay queued and no amount of polling will move them.

When receipts do ship, the signature scheme will be documented here before the first call goes out — not discovered from a payload.

Errors

Every failure returns the same shape. Branch on error; it is a stable string and will not be renamed under you.

{ "error": "insufficient_credit",
  "message": "…",
  "docs_url": "/docs/errors#insufficient_credit" }

The docs_url in a failure is a real link — follow it and you land on that code, with what to do about it. All 25 codes →

Codes marked "no" will never succeed by repeating the identical request — retrying one is how a clear refusal becomes a rate-limit ban.

Rate limits

Throughput is per account, not per key, so issuing more keys does not buy more capacity. Exceeding it returns rate_limited with HTTP 429 — back off and retry.

There are no rate-limit response headers. No Retry-After, no X-RateLimit-*. Do not write a client that waits for one. The window is one second, so a short pause clears it, and your ceiling is readable at any time from GET /api/v1/pricing as max_tps — which is also where to read it if your account holds an agreed rate above its plan.

A key may be throttled tighter than your account, never looser. See pricing for the rate on each tier.

OpenAPI and generated clients

The whole API is described at /docs/openapi.json — OpenAPI 3.0.3, generated from the same tables the routes are built from, so it cannot describe an endpoint this build does not serve. Point a generator at it and get a typed client instead of hand-writing one:

# a typed client, in whatever you write in
npx @openapitools/openapi-generator-cli generate \
  -i https://smsc.bt/docs/openapi.json \
  -g typescript-fetch -o ./smsc-client

# or python, php, go, dart, java, csharp, …
  -g python -o ./smsc_client

The document names its own server, so a spec fetched from a staging box generates a client pointed at that box rather than at production.