Send your first message in the sandbox

What you will build

This guide takes you from a new Telnxo account to a working test message, a delivery receipt and a short checklist for going live. It is written for developers and for the non-developers who sit next to them, so each step explains both what to do and why it matters. You should be able to finish the first send in about ten minutes and the full checklist in under an hour.

The sandbox behaves like the live platform in the ways that matter for integration work: it accepts the same request shape, validates the same fields, returns message IDs and produces delivery receipts. What it does not do is spend balance or reach a real handset. That makes it the right place to build and test your integration, your error handling and your webhook receiver before any customer sees a message.

Before you start

Gather these items first so you do not stop halfway through:

• A Telnxo account with a confirmed email address
• A phone number in international format, for example +919800000000
• A place to run an HTTP request: a terminal with curl, Postman or your own code
• A public HTTPS address if you want to test webhooks (a tunnelling tool works for development)

Keep the sandbox key out of source control from the first minute. Treat it like a password even though it cannot spend money: a leaked key lets someone fill your logs with noise and, worse, teaches your team to be casual about keys.

Step by step

1. Create the account. Sign up, confirm your email address and sign in to the dashboard. If your organisation already has an account, ask an administrator to invite you instead of creating a second one, so that logs and billing stay in one place
2. Open the developer area. Choose Developers in the dashboard and create a key marked as sandbox. Copy it immediately, because it is shown only once. If you lose it, create a new one and revoke the old one
3. Send a request. Use the example below. Replace the key, the destination number and, if your account already has one, the sender
4. Check the response. Look for a success status and a message ID. Store the ID: you need it to find the message in Logs and to match later events
5. Read the receipt. Open the message in Logs or receive the event on your webhook. In the sandbox the message moves from queued to delivered within a few seconds

Example request

curl -X POST https://api.example.telnxo.com/v1/sms \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+919800000000","sender":"TELNXO","text":"Hello from the sandbox"}'

A well-formed response contains an HTTP 2xx status, a message ID and an initial status such as queued or accepted. The initial status only says that Telnxo took responsibility for the message. It does not say the handset received it. Delivery is reported later, which is why receipts matter.

What each field does

Understanding statuses

Every message moves through a small set of states. Learning them now saves hours of confusion later.

Treat delivered and failed as final. Treat everything else as in progress. Build your application so that a message that never reaches a final state after a sensible period raises an alert rather than silently waiting.

Test the webhook path

Polling the API for status works for a first test but does not scale. For anything real, register a webhook URL and let Telnxo call you. Our guide on webhooks, retries and signature checks covers the receiver in detail. For now, make sure your endpoint returns a 2xx status quickly and logs the raw body, so you can see exactly what arrives.

Moving from sandbox to live

Going live is a configuration change plus a short list of checks. The code you wrote against the sandbox should need no changes apart from the key and, in some countries, the sender and template values.

• Replace the sandbox key with a live key stored in your secret manager
• Confirm the sender ID is approved for each destination country
• In India, confirm the entity, header and template are registered and mapped (see the DLT checklist)
• Add balance and set a low-balance alert above your daily spend
• Send one real message to a number you control before any customer traffic
• Set up monitoring on failed and rejected counts

Do not skip the single real message. It exercises the parts the sandbox cannot: operator routing, sender approval and handset delivery. A one-minute test catches registration mistakes that would otherwise surface as a thousand failures.

Habits that pay off later

• One key per application. If an application is compromised you revoke one key, not all of them.
• Store message IDs. Support can find a message by ID in seconds; by guesswork it can take hours.
• Log request and response bodies (without secrets) for a short period so you can reproduce issues.
• Keep sandbox and live configuration separate so a test can never use a live key by accident.
• Write idempotent code. If your system retries after a timeout, make sure a customer does not receive two copies.

Where to go next

Once your first message works, read about how segments and encoding affect cost, then about API key practice. If your first live message does not arrive, start with why messages fail or arrive late.

Further reading

• Telnxo API reference in your dashboard (authoritative for paths and fields)
• RFC 3986, URI generic syntax, for building request URLs correctly
• E.164 numbering plan recommendation, for the number format