Package Information
Available Nodes
Documentation generating…
Documentation
n8n-nodes-topsms
This is an n8n community node for TopSMS, an SMS gateway for the EU (topsms.eu) and for Czechia and Slovakia (topsms.cz). Use it to send and schedule SMS, send one message to many recipients, send and check one-time verification codes (OTP), check delivery status and read your credit balance.
Installation · Credentials · Operations · Delivery reports (webhooks) · Example workflow · Compatibility · Resources
Installation
In n8n, go to Settings → Community Nodes → Install, enter n8n-nodes-topsms and confirm.
See the n8n community nodes installation guide for other options (for example npm install n8n-nodes-topsms in a queue-mode or Docker setup).
Credentials
Create an API key in the TopSMS dashboard (Dashboard → API), then add a TopSMS API credential in n8n:
| Field | Value |
|---|---|
| Region | TopSMS.eu (EUR account) for accounts created on topsms.eu, TopSMS.cz (CZK account) for accounts created on topsms.cz. Both use the same API; amounts are returned in your account currency. Custom URL is only for testing environments. |
| Client ID | The key's Client ID |
| Secret | The key's secret (shown only once when the key is created) |
Requests are sent with the header Authorization: Bearer <clientId>:<secret>. When you save the credential, n8n checks it by reading your credit balance (GET /api/credit, needs the key's read scope). Sending needs the send scope.
Test keys: tick Test key when creating an API key to build and test your workflow for free. A test key sends nothing and charges nothing; responses contain "test": true, a simulated delivery report arrives after 2–4 seconds (numbers ending in 0000 fail, 0001 expire) and Send Code returns the code in testCode.
Operations
| Resource | Operation | API |
|---|---|---|
| Message | Send – one SMS. Optional: Sender ID, Send At (schedule up to 30 days ahead), Idempotency Key | POST /api/sms/send |
| Message | Send Bulk – the same text to up to 500 recipients (over 50 recipients, or with Always Queue, the batch is queued and returns a jobId) |
POST /api/sms/send-bulk |
| Message | Get Status – delivery status (queued, sent, delivered, failed, expired) with timestamps, carrier and errorCode |
GET /api/sms/status/{id} |
| Scheduled Job | Get – progress of a scheduled send or a queued batch | GET /api/sms/jobs/{id} |
| Scheduled Job | Cancel – cancel a scheduled send or a batch that has not started; the price is refunded | DELETE /api/sms/jobs/{id} |
| Verification | Send Code – generate a one-time code and send it by SMS (Brand, Code Length 4–8, Validity 60–1800 s, Language cs/en/de, Sender ID) | POST /api/verify/send |
| Verification | Check Code – check the code the user entered, by verification ID or by phone number (max 5 attempts) | POST /api/verify/check |
| Account | Get Credit – balance, currency and price per SMS | GET /api/credit |
Notes:
- Phone numbers must be in international format, e.g.
+420601234567,+4915112345678. - Send At is interpreted in the workflow's time zone (Workflow settings → Timezone) unless the value already contains a zone, e.g.
2026-12-24T09:00:00+01:00. Credit is charged when the message is scheduled; use Scheduled Job → Cancel with the returnedjobIdto cancel it. - Sender ID: leave empty to use your account's default sender (or TopSMS). A custom name must be approved for your account (Dashboard → Sender ID).
- Idempotency Key: repeating a request with the same key within 24 hours returns the original response instead of sending again – useful together with n8n's Retry On Fail.
- The node can be used as a tool by n8n AI agents.
Errors
API errors are shown as readable messages, with the original TopSMS message in the error details, for example:
| HTTP | TopSMS code | Message in n8n |
|---|---|---|
| 401 | Authentication failed: check the Client ID and Secret … | |
| 402 | insufficient_credit |
Insufficient credit: top up your TopSMS account and try again |
| 403 | sender_not_allowed, sender_protected, sender_needs_topup |
Sender ID is not allowed for this account … / needs a manual review … / available after your first paid top-up |
| 403 | urls_need_topup |
Messages containing links can be sent after your first paid top-up |
| 403 | The API key is missing the required permission (scope) … / IP whitelist | |
| 409 | not_cancellable, campaign_job |
The job can no longer be cancelled … |
| 429 | TopSMS rate limit reached / too many verification codes for this number | |
| 500 | record_failed |
The SMS was sent but could not be recorded; credit was refunded. Do not resend it … |
Enable the node's On Error → Continue setting to handle errors per item.
Delivery reports (webhooks)
TopSMS can push delivery reports to a URL, but the webhook URL is set per API key in the TopSMS dashboard – the API has no endpoint for registering webhooks, so this package has no trigger node. Use n8n's built-in Webhook node instead:
- Add a Webhook node: HTTP Method
POST, RespondImmediately(TopSMS expects a 2xx response within 5 seconds). Activate the workflow and copy the Production URL. - In the TopSMS dashboard open API → your key → Webhook, paste the URL and copy the generated webhook secret. Use Send test webhook to check the connection. Only messages sent with that API key are reported.
- Verify the signature. Every request carries the header
X-TopSMS-Signature: sha256=<hex HMAC-SHA256 of the raw body, keyed with the webhook secret>. Add a Crypto node after the Webhook node:- Action: Hmac, Type: SHA256, Encoding: HEX
- Value:
{{ JSON.stringify($json.body) }}(TopSMS sends compact JSON, so re-serializing the parsed body reproduces the signed bytes) - Secret: your webhook secret (better: store it in an n8n variable or credential)
- Property Name:
signature
- Add an If node:
{{ 'sha256=' + $json.signature }}is equal to{{ $json.headers['x-topsms-signature'] }}. Continue only on the true branch; stop or alert on false.
Alternatively, on self-hosted n8n with NODE_FUNCTION_ALLOW_BUILTIN=crypto, enable Raw Body on the Webhook node and verify in a Code node with crypto.timingSafeEqual over the raw body.
Payload (event: "sms.status", sent on every final status change; 3 attempts: immediately, after 30 s and after 2 min):
{
"event": "sms.status",
"id": "cmg8x…",
"externalId": "123456789",
"to": "+420601234567",
"from": "MyShop",
"status": "delivered",
"price": 0.0392,
"currency": "EUR",
"deliveredAt": "2026-11-08T10:15:03.000Z",
"failedAt": null,
"errorMessage": null,
"errorCode": null,
"sentAt": "2026-11-08T10:15:04.120Z"
}
status is delivered, failed or expired; errorCode explains failures (expired, undelivered, rejected, deleted, unknown, repeated_failure, not_sent). Test keys and the dashboard's test webhook add "test": true. The id matches the id returned by Send, so you can match reports to your records.
Example workflow
Send an order confirmation when a new order arrives, and log delivery later via the webhook. Copy the JSON below and paste it into the n8n editor (Ctrl+V / Cmd+V), then select your TopSMS credential:
{
"nodes": [
{
"parameters": { "httpMethod": "POST", "path": "new-order", "options": {} },
"name": "New order",
"type": "n8n-nodes-base.webhook",
"typeVersion": 2,
"position": [0, 0]
},
{
"parameters": {
"resource": "message",
"operation": "send",
"to": "={{ $json.body.phone }}",
"text": "=Thank you for your order {{ $json.body.orderId }}. We will let you know when it ships.",
"additionalFields": { "idempotencyKey": "=order-{{ $json.body.orderId }}" }
},
"name": "Send confirmation SMS",
"type": "n8n-nodes-topsms.topSms",
"typeVersion": 1,
"position": [220, 0]
}
],
"connections": {
"New order": { "main": [[{ "node": "Send confirmation SMS", "type": "main", "index": 0 }]] }
}
}
An OTP flow works the same way: Verification → Send Code when the user signs up (store the returned id), then Verification → Check Code with that id and the code the user typed; continue when valid is true.
Compatibility
Built with @n8n/node-cli 0.55 and tested against the n8n 2.46 engine packages (n8n-workflow, n8n-core). No runtime dependencies.
Development
npm install
npm run build
npm run lint
npm test # unit tests + the node executed by n8n-core's declarative engine against a local mock server
npm run dev # starts n8n on http://localhost:5678 with this node loaded
test/e2e.js is an optional end-to-end check against a real TopSMS API with a test API key (nothing is sent or charged):
TOPSMS_BASE_URL=https://topsms.eu TOPSMS_TEST_CLIENT_ID=… TOPSMS_TEST_SECRET=… node --test test/e2e.js
Resources
- n8n community nodes documentation
- TopSMS API documentation · OpenAPI spec · Integrations
- Support: info@topsms.eu