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.
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:
deliveredwith adeliveredAttimestamp.
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-Keyin 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; if you are starting from zero, read SMS API integration in 5 minutes first. Create a free account.
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.