# Test an SMS API without sending: keys, DLRs, webhooks

> How to test an SMS integration without sending a single SMS: test API keys, simulated delivery reports for failure and expiry, and signed test webhooks.

Published: 2026-11-15 · 6 min read · Web version: https://topsms.eu/blog/sms-api-sandbox-testing · Deutsch: https://topsms.eu/de/blog/sms-api-testen-sandbox.md

## In short

Create a test API key in the TopSMS dashboard. It accepts the same requests and returns the same responses as a live key, but sends and charges nothing. After 2 to 4 seconds the message gets a simulated delivery report: numbers ending in 0000 fail, 0001 expire, all others are delivered, and the report is posted to your webhook with the same HMAC signature as live traffic and "test": true.

An SMS integration has more moving parts than the send request: error handling, delivery reports, webhooks, retries, verification codes. Testing all of that against real phones is slow, costs money and fills somebody’s inbox. A sandbox lets you test the whole loop without sending anything. This guide shows how test keys work at TopSMS and how to use them in development and CI.

## Live key, test key: what is the difference?

When you create an API key in the dashboard, tick **Test key**. The key works with the same endpoints and the same base URL; there is no separate sandbox host to switch to later.

|  | Live key | Test key |
| --- | --- | --- |
| Request validation | yes | yes, identical |
| SMS handed to the network | yes | no |
| Credit charged | yes | no; `price` shows what it would cost |
| Delivery report | from the operator | simulated after 2 to 4 seconds |
| Webhook | signed | signed, with `"test": true` |
| Status query | `/api/sms/status/{id}` | same endpoint |

The test key also works with bulk sending, the Verify API, the HTTP GET API and e-mail to SMS, so you can test any entry point.

## Step 1: send with the test key

```
# delivered after 2-4 s
curl -X POST https://www.topsms.cz/api/sms/send \
  -H "Authorization: Bearer TEST_CLIENT_ID:TEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"to":"+4915112345678","text":"Test 1","from":"MyShop"}'

# simulated failure (number ends in 0000) and expiry (0001)
-d '{"to":"+4915112340000","text":"Test 2"}'
-d '{"to":"+4915112340001","text":"Test 3"}'
```

The response has the same shape as a live one, plus `test: true`:

```
{ "ok": true, "test": true, "channel": "sms", "id": "cmx...", "externalId": "test-1a2b3c4d",
  "to": "+4915112345678", "from": "MyShop", "smsCount": 1, "price": 0.089, "status": "sent" }
```

## Step 2: simulate delivery, failure and expiry

The last four digits of the recipient number decide the outcome:

- `…0000`: `failed`, as for an invalid number (`errorCode: "undelivered"`),
- `…0001`: `expired`, as for a phone that stayed switched off (`errorCode: "expired"`),
- anything else: `delivered` with a `deliveredAt` timestamp.

The status changes 2 to 4 seconds after sending, so your code really has to wait for the asynchronous report instead of assuming success. You can poll `/api/sms/status/{id}` with the `id` or the `externalId`, or receive the webhook. Write one test per outcome: the user sees “sent”, “not delivered” and “phone unreachable” the way you intend.

## Step 3: receive and verify the webhook

Enter a webhook URL for the key. The dashboard shows the key’s webhook secret, which you can copy again later from the key list; store it in your configuration. Every report carries the header `X-TopSMS-Signature: sha256=…`, an HMAC-SHA256 of the raw body with that secret. A simulated failure looks like this:

```
{ "event": "sms.status", "id": "cmx...", "externalId": "test-1a2b3c4d",
  "to": "+4915112340000", "from": "MyShop", "status": "failed", "price": 0, "currency": "EUR",
  "deliveredAt": null, "failedAt": "2026-11-15T09:12:03.000Z",
  "errorMessage": "...", "errorCode": "undelivered", "sentAt": "...", "test": true }
```

Verify the signature over the raw body, before parsing JSON, and compare in constant time. An example with Node.js and Express:

```
import express from 'express'
import crypto from 'crypto'

const app = express()
const SECRET = process.env.TOPSMS_WEBHOOK_SECRET

app.post('/topsms/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex')
  const given = req.get('X-TopSMS-Signature') || ''
  const ok = given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
  if (!ok) return res.sendStatus(401)

  const event = JSON.parse(req.body.toString('utf8'))
  if (event.test) console.log('test event', event.status)
  // update the message status in your database here
  res.sendStatus(200)
})
```

Respond with HTTP 2xx within 5 seconds. If your endpoint fails, TopSMS tries again after 30 seconds and after 2 minutes, three attempts in total. Redirects are not followed, so give the final URL. Make your handler idempotent: the same report can arrive more than once if your first 200 got lost.

## Step 4: the test webhook button

You do not even need to send a message to test your endpoint. In the dashboard under API access, open **Log & webhook** for the key and press **Send a test webhook**. TopSMS posts a sample `sms.status` event with `"test": true`, signed with the key’s secret, and shows your server’s HTTP status or a readable error: certificate not valid for the domain, connection refused, timeout, redirect. The same log lists the last 100 API calls of the key and every webhook attempt with your server’s response, kept for 30 days.

## Step 5: test verification codes

With a test key, `POST /api/verify/send` sends nothing and returns `testCode`. The code is always the first digits of `12345678`: `123456` for the default six digits. All limits stay active (five attempts, five codes per hour per number, 30 seconds between codes), so you can also test lock-outs and the “resend code” button. Then `POST /api/verify/check` with the test code returns `valid: true`.

## Using test keys in CI

- Keep the test key in your CI secrets and the live key only in production. One test key per environment keeps the logs apart.
- Use numbers ending in 0000 and 0001 in your fixtures for the failure paths.
- For webhook tests in CI without a public URL, call your handler directly with a body you sign yourself using the same HMAC; use the dashboard button to test the real network path once.
- Use an `Idempotency-Key` in tests too, so you see that a retried request returns the original response instead of a second message.

## Going live

Create a live key with the same settings, replace the key in your configuration and send one real SMS to your own phone. New accounts get €0.50 free credit after phone verification, enough for a few live tests at €0.089 per SMS to Germany and Austria. Details are in the [documentation](https://topsms.eu/docs#test-mode); if you are starting from zero, read [SMS API integration in 5 minutes](https://topsms.eu/blog/sms-api-in-5-minutes) first. [Create a free account](https://topsms.eu/#register).

## Frequently asked questions

### Does a test key check my requests at all?

Yes. Number format, text, sender, blacklist and the key’s permissions are checked as with a live key, and errors come back with the same codes. Only the hand-over to the network and the charge are skipped.

### How do I test the Verify API?

With a test key, /api/verify/send sends nothing and the code is the first digits of 12345678 (123456 for six digits). The response also contains it as testCode, so automated tests can read it.

### Does the test webhook use the real signature?

Yes. Simulated delivery reports and the “Send a test webhook” button sign the body with your key’s webhook secret in the X-TopSMS-Signature header, exactly like live reports.

### What does the price field mean in test mode?

It shows what the message would have cost with a live key. The credit does not change.

## Related pages

- [Test mode in the documentation](https://topsms.eu/docs#test-mode)
- [Webhooks and signature](https://topsms.eu/docs#webhooks)
- [SMS API for developers](https://topsms.eu/use-cases/sms-api-for-developers)
- [SMS API in 5 minutes](https://topsms.eu/blog/sms-api-in-5-minutes)
