Textmast docs

Send your first message

About five minutes, and the first four of them cost nothing — test mode sends nothing and charges nothing.

1. Get a key

In the dashboard, Settings → API keys → Create key. Start intest mode and give it only messages:send. A key that can only do its job is a key that cannot do much damage when it leaks.

The secret is shown once. We store a hash of it, so we genuinely cannot show it to you again. If you lose it, revoke the key and mint another.

2. Send

curl https://api.textmast.com/v1/messages \
  -H "Authorization: Bearer tm_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f2b9c1e-8a77-4f3e-9e51-1d0a2b3c4d5e" \
  -d '{
    "to": "+447400123456",
    "body": "Your code is 123456",
    "class": "otp"
  }'

You get back 202 Accepted and the message:

{
  "id": "01j8xk2p7n4qc3m9v0wz5bt6ay",
  "object": "message",
  "status": "queued",
  "direction": "outbound",
  "to": "+447400123456",
  "to_country": "GB",
  "from": "TEXTMAST",
  "body": "Your code is 123456",
  "encoding": "gsm7",
  "segments": 1,
  "class": "otp",
  "price": { "amount": "0.0350", "currency": "GBP" },
  "failure": null,
  "created_at": "2026-09-17T09:14:22+00:00"
}

202, not 200. The message is accepted and queued; it has not reached a handset yet. segments and price come back on the send itself rather than only on the invoice, so you can see immediately what that emoji you just added costs.

3. Find out what happened

Either poll:

curl https://api.textmast.com/v1/messages/01j8xk2p7n4qc3m9v0wz5bt6ay \
  -H "Authorization: Bearer tm_test_…"

Or, better, register a webhook and let us tell you. Polling a message that is going to take four seconds is a waste of both our time; polling every message you have ever sent is how you end up rate limited.

4. Go live

Mint a tm_live_ key and change one string. Nothing else about the request changes. A live key cannot see test data and a test key cannot see live data, so there is no route by which your staging environment texts a real customer.

Three things that will save you an afternoon

Send an idempotency key

Generate it when you compose the message, not when you retry. A timeout that you retry without one is how somebody gets the same text twice. See idempotency.

Log the request_id

It is on every response, success or failure. When you email us about something odd, that one string is the difference between a single log query and a guess.

New accounts can only reach the UK

The UK, Guernsey, Jersey and the Isle of Man, until you ask for more. A send to anywhere else is refused with UNROUTABLE_COUNTRY. It looks unhelpful right up until you read what SMS pumping costs the people who did not have it — almost all of that fraud targets destinations a normal business never sends to, and the bill lands on you.