Send your first message in ten minutes

The fastest useful thing you can do with a messaging API is get one message from your terminal to a handset and see the receipt come back. Everything below runs against the sandbox, which speaks the same schema as production and returns simulated carrier responses, so nothing here costs anything or reaches a real person.

Create a key

Keys are scoped two ways: to an environment, and to a set of route classes. A sandbox key can call every endpoint but will never reach a real network. Scope it narrowly now and widen it later - a key that can only send transactional traffic cannot be misused to run a marketing blast.

tr_sbx_9f2c41ad...   sandbox, all routes
tr_live_71ba03e8...  production, transactional + marketing

Store it as an environment variable. The API has no session, no refresh token and no cookie, so the key is the only credential in play and it should never reach a client bundle.

Reserve a sender identity

Every message needs a sender the destination network recognises. In sandbox you can reserve any alphanumeric string instantly. In production the same call submits a registration to the network, which is the step that actually gates a launch - see the sender registration guide for how long each market takes.

curl https://api.textreach.online/v2/senders \
  -H "Authorization: Bearer $TEXTREACH_KEY" \
  -d id="LUXPLAY" \
  -d market="MT" \
  -d type="alphanumeric"

Post one message

A send needs three things: who it is from, where it is going, and what it says. The body can be raw text or a template reference, and templates are strongly preferred because they render server side with locale fallback and give you a stable identifier to report on later.

curl https://api.textreach.online/v2/messages \
  -H "Authorization: Bearer $TEXTREACH_KEY" \
  -H "Idempotency-Key: quickstart-001" \
  -d sender_id="LUXPLAY" \
  -d to="+35679xxxxxx" \
  -d template="deposit_bonus_v3" \
  -d locale="en-MT"

{
  "id": "msg_01J9Q4TX",
  "state": "queued",
  "route": "MT-direct-01",
  "segments": 1,
  "eta_ms": 190
}

Always send an idempotency key. It is honoured for twenty four hours, which means a retried request after a timeout returns the original message rather than sending a second one. This is the single cheapest way to avoid double-messaging a player during an incident.

Read the receipt

The response above is an acknowledgement that the gateway took the message, not proof of delivery. State moves through queued, submitted, and then either delivered or failed with a carrier reason code attached. Poll the resource while you are learning, then move to events.

{
  "id": "msg_01J9Q4TX",
  "state": "delivered",
  "route": "MT-direct-01",
  "segments": 1,
  "timeline": [
    { "state": "queued",    "at": "2026-08-21T09:14:02Z" },
    { "state": "submitted", "at": "2026-08-21T09:14:02Z" },
    { "state": "delivered", "at": "2026-08-21T09:14:06Z" }
  ]
}

Point a webhook at it

Polling is fine for one message and hopeless for a million. Register an HTTPS endpoint once, store the signing secret you get back, and delivery states arrive as they happen. The delivery receipts guide covers verification, retries and idempotent consumption in detail.

curl https://api.textreach.online/v2/webhooks \
  -H "Authorization: Bearer $TEXTREACH_KEY" \
  -d url="https://example.internal/hooks/textreach" \
  -d events="message.delivered,message.failed,message.inbound"

Moving to production

Swap the key and keep the code. Sandbox and production share one schema, one set of error codes and one state machine, so the only differences you will meet are real ones: registration status, market licensing, and the fact that carriers occasionally take their time. Before you switch, check that:

• Your webhook consumer returns a 2xx in under two seconds and is safe to call twice.
• Every send carries an idempotency key derived from something stable in your own system.
• Consent is written to the platform, not only to your database, so the gateway can enforce it.
• The markets on your licence are attached to the key, or sends will be refused with a 409.