SMS API for sending and receiving UK texts

Everything lives under /api/v1. Put your API key in the Authorization header as a Bearer token and send JSON bodies of up to 1 MB. Successful responses all come back in the same envelope: data holds the result and meta holds anything about it, such as the cursor for the next page. Errors have one shape too, an error object with a code, a message and details, so you can handle them in one place.

Lists use cursor pagination and come back newest first. The whole API is described in an OpenAPI 3.1 document at /api/v1/openapi.json, which you can load into your usual tools or generate a client from.

Our own dashboard runs on the same API, so whatever you can do with messages and contacts in the browser, you can do from code.

The API covers messages, contacts and everything around them:

Connections drop, and a send you retry after a timeout shouldn't go out twice. Add an Idempotency-Key header to POST /messages (any unique string per send works; a UUID is typical) and a repeat of the same request returns the original result without sending again.

Every API key, live or test, is limited to 20 requests a second, with bursts up to 40. Test keys send nothing and cost nothing, and they're also capped at 50 numbers a request and 300 numbers an hour.

The API texts UK mobiles only, including Guernsey, Jersey and the Isle of Man. Numbers it can't text come back in the rejected list with a reason code (not_mobile for a landline, unsupported_destination for another country), and they're never charged. Live sending starts once we've checked your account.

There are five events: message.sent, message.delivered, message.failed, message.received and opt_out.created. Each is a JSON POST signed with HMAC SHA-256. The signature header carries t=<unix time>,v1=<hex>, worked out over the timestamp, a full stop and the raw body using your webhook's signing secret.

Answer with any 2xx within 8 seconds. If you don't, we retry after 1, 5, 30, 120, 360 and 720 minutes, and the delivery ID header stays the same on every attempt so you can drop duplicates. A webhook that fails 100 times in a row is switched off until you turn it back on.

Test keys work from the moment you sign up, before we've approved your account. A test send goes nowhere: each text is marked sent, then delivered a few seconds later, and the message.sent and message.delivered webhooks fire. Nobody can reply to a test text, so message.received and opt_out.created only ever come from a live key. You can run the sending side end to end without spending anything or texting anyone, then swap in a live key when you're ready.