Textmast API

One HTTPS endpoint, JSON in and JSON out, bearer authentication. If you have used a modern payments API you already know the shape of this one.

curl https://api.textmast.com/v1/messages \
  -H "Authorization: Bearer tm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+447400123456",
    "body": "Your code is 123456",
    "class": "otp"
  }'

What is worth knowing before you start

Sending is asynchronous, and we say so

A successful send returns 202 Accepted, not 200 OK. The message has been accepted and queued; it has not yet reached a handset. The eventual outcome arrives on awebhook, or you can poll the message.

Plenty of platforms return 200 and let you assume delivery. We would rather the status code told you the truth, because the difference matters on the day something is wrong.

Status only ever moves forwards

Carriers deliver receipts out of order more often than you would expect. A message that isdelivered will never go back to sent, and a terminal status is final. See delivery reports.

You are billed in segments, not messages

A single emoji turns a 160-character message into a 70-character one, and a long message into three. The segment counter we bill with is published, and the same function runs in our dashboard, in the mobile app and on the server.

Opt-outs are enforced, not advisory

A reply of STOP suppresses that number for your account immediately, for every class of message including transactional. We will refuse to send to them afterwards. Seeopt-outs.

Base URL

Test mode is a property of the key, not of the URL. A tm_test_ key behaves identically, costs nothing and sends nothing. It cannot see live data and a live key cannot see test data, so there is no path by which a staging environment sends a real customer a real text.