API docs

Quick start

1. Create an account and verify your email and phone number.
2. Top up at least $10.
3. Create an API key and keep it in an environment variable called TEXTRAIL_API_KEY.
4. Send your first message.

curl https://textrail.devflovv.com/api/v1/sms \
  -H "Authorization: Bearer $TEXTRAIL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14165550123",
    "message": "Your table for two is ready. Come on in."
  }'

The answer is 202 and a message id. Your message is queued, and you can follow it with that id.

Authentication

Send your key as a bearer token on every request. Keys start with tr_live_ or tr_test_. A key is shown once when you create it, so store it then. Keep keys on your server, never in a web page or a mobile app.

Authorization: Bearer tr_live_...

Each key has scopes, chosen when you create it. A request outside a key’s scopes gets SCOPE_MISSING.

Send an SMS

POST /api/v1/sms

Queues one message. Needs the sms:send scope and an Idempotency-Key header.

curl https://textrail.devflovv.com/api/v1/sms \
  -H "Authorization: Bearer $TEXTRAIL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14165550123",
    "message": "Your table for two is ready. Come on in."
  }'

{
  "success": true,
  "id": "job_01KA7QW3M9ZP4XN8RT2VD6HJ5B",
  "status": "queued",
  "encoding": "GSM7",
  "chars": 40,
  "priceCents": 2,
  "expiresAt": "2026-10-30T22:15:00.000Z",
  "testMode": false,
  "sendingAvailable": true,
  "notice": null
}

Check a message

GET /api/v1/sms/{id}

Returns the current state of a message your account sent. Needs the sms:read scope. Phone numbers come back masked.

curl https://textrail.devflovv.com/api/v1/sms/job_01KA7QW3M9ZP4XN8RT2VD6HJ5B \
  -H "Authorization: Bearer $TEXTRAIL_API_KEY"

{
  "success": true,
  "sms": {
    "id": "job_01KA7QW3M9ZP4XN8RT2VD6HJ5B",
    "status": "delivered",
    "phoneNumber": "+1••••••0123",
    "country": "CA",
    "priceCents": 2,
    "charged": true,
    "lastError": null,
    "createdAt": "2026-10-30T22:00:00.000Z",
    "sentAt": "2026-10-30T22:00:04.000Z",
    "deliveredAt": "2026-10-30T22:00:07.000Z",
    "expiresAt": "2026-10-30T22:15:00.000Z",
    "testMode": false,
    "notice": null
  }
}

Message statuses

A message moves forward through these. sent means it went out to the carrier. delivered appears only if the carrier reports it, so a message can stay at sent and still have arrived.

Reason codes

lastError says why a message didn’t go as planned.

Verification codes

TextRail makes the code, texts it and checks it, so you store nothing. A code has 6 digits, lasts 5 minutes and allows 5 tries.

Send a code

POST /api/v1/otp/send

Needs the otp:send scope and an Idempotency-Key header. One code is active per key, recipient and purpose. Asking again within 60 seconds gets OTP_COOLDOWN. A code is one SMS at 2 cents.

curl https://textrail.devflovv.com/api/v1/otp/send \
  -H "Authorization: Bearer $TEXTRAIL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14165550123",
    "purpose": "login"
  }'

{
  "success": true,
  "requestId": "otp_01KA7QX8C2HF6TN3PV9WD4MK7S",
  "status": "queued",
  "expiresIn": 300,
  "sendingAvailable": true,
  "notice": null
}

Check a code

POST /api/v1/otp/verify

Needs the otp:verify scope. A code works once. Any failure, whether wrong, expired, used or unknown, is a 200 with verified: false, so the answer gives nothing away.

curl https://textrail.devflovv.com/api/v1/otp/verify \
  -H "Authorization: Bearer $TEXTRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "otp_01KA7QX8C2HF6TN3PV9WD4MK7S",
    "code": "482913"
  }'

{
  "success": true,
  "verified": true
}

Test keys

A tr_test_ key runs the same validation, idempotency and rate limits as a live key, on the same verified account. No real SMS goes out and nothing is charged.

• Messages go straight to sent with testMode: true and a price of 0.
• The code for a test verification is always 000000.

Message length

A message is exactly one SMS and is never split. Too long gets a 422 and costs nothing.

These GSM characters count as two: ^ { } \ [ ] ~ | €. One character outside the GSM alphabet moves the whole message to the limit of 70, and an emoji counts as two of those.

Safe retries

Sending needs an Idempotency-Key header: any unique string you make for that message. If a request times out, send it again with the same key and body. You’ll get the first answer back, with an Idempotent-Replayed: true header, and no second message.

Keep the key with the message in your own records, so a retry after a crash reuses it. The same key with a different body gets IDEMPOTENCY_CONFLICT.

Errors

Errors use normal HTTP status codes and one JSON shape. error.code is stable, so build on that. error.message is for people.

{
  "success": false,
  "error": {
    "code": "MESSAGE_TOO_LONG",
    "message": "The message does not fit in one SMS."
  }
}