Anwendungen

SMS-API für Entwickler

Reines HTTP und JSON über HTTPS, kein SDK nötig. Eine Anfrage sendet eine SMS, Zustellberichte kommen per signiertem Webhook, und Wiederholungen sind mit einem Idempotency-Key unkritisch. Testschlüssel senden nichts und kosten nichts, so bauen Sie die komplette Integration, bevor Sie Guthaben aufladen.

MeineAppjetzt
MeineApp: Ihr Datenexport ist fertig. Download innerhalb von 24 Stunden: tsms.cz/x7k2p9

Eine typische Systemnachricht aus Ihrem Backend, unter dem Namen Ihrer App.

REST, JSON und API-Schlüssel

Die Produktions-URL lautet https://www.topsms.cz. Sie authentifizieren sich mit einem API-Schlüssel im Header Authorization: Bearer clientId:secret. Das Secret wird nur als Hash gespeichert, notieren Sie es also beim Anlegen des Schlüssels.

  • Berechtigungen (Scopes): send zum Senden, read für Status und Guthaben. Optional eine IP-Whitelist pro Schlüssel.
  • Bis zu 10 aktive Schlüssel pro Konto, jeder mit eigenem Namen, etwa getrennt nach Projekt oder Kostenstelle.
  • Rate-Limit pro Schlüssel: standardmäßig 60 Anfragen pro Minute, einstellbar bis 1.000.
  • Massenversand: /api/sms/send-bulk nimmt bis zu 500 Empfänger auf, mit gleichem oder individuellem Text. Bei mehr als 50 Empfängern antwortet die API mit 202 und einer jobId, und die Warteschlange sendet innerhalb von Sekunden bis Minuten.

Zustellberichte per Webhook

Hinterlegen Sie beim API-Schlüssel eine Webhook-URL, und jede Statusänderung (zugestellt, nicht zugestellt, abgelaufen) kommt als JSON-POST auf Ihren Server, mit dem Header X-TopSMS-Signature: sha256=…, einem HMAC-SHA256 über den Rohinhalt mit Ihrem Webhook-Secret. Wir versuchen es dreimal (sofort, nach 30 Sekunden, nach 2 Minuten) mit 5 Sekunden Timeout und erwarten HTTP 2xx.

Lieber abfragen? Nutzen Sie GET /api/sms/status/{id}. Im Dashboard gibt es pro Schlüssel ein Protokoll der letzten 100 Aufrufe und Webhook-Zustellungen einschließlich der Antwort Ihres Servers, 30 Tage lang.

Sichere Wiederholungen und Testmodus

Nach einem Timeout wissen Sie nicht, ob die Anfrage angekommen ist. Senden Sie sie mit demselben Idempotency-Key erneut, und die SMS wird nicht doppelt gesendet: Sie erhalten die ursprüngliche Antwort mit Idempotent-Replayed: true. Der Schlüssel gilt 24 Stunden; ein anderer Inhalt mit demselben Schlüssel ergibt 422, eine noch laufende Anfrage 409. Das gilt für /api/sms/send, /api/sms/send-bulk und /api/verify/send.

Ein Testschlüssel liefert dieselben Antworten wie ein Produktivschlüssel, zusätzlich "test": true, und simuliert nach 2 bis 4 Sekunden den Statuswechsel und den Webhook. Nummern, die auf 0000 enden, simulieren einen Fehler, 0001 den Ablauf.

OpenAPI, PHP-Bibliothek und MCP

  • OpenAPI 3.0: openapi.yaml für Postman, Insomnia oder einen generierten Client.
  • PHP: composer require topsms/topsms-php für Versand, Status, Guthaben und die Prüfung der Webhook-Signatur.
  • MCP-Server: Mit dem npm-Paket topsms-mcp senden Claude, Cursor und andere KI-Assistenten SMS, planen und stornieren sie, verschicken Bestätigungscodes und prüfen Status und Guthaben, über dieselbe API. Siehe MCP-Server.
  • Für Coding-Assistenten: llms.txt und die Authentifizierungsanleitung für automatisierte Clients (beide auf Englisch).

Sie bauen Login-Codes? Nutzen Sie die Verify API, statt Codes selbst zu versenden. Es gelten dieselben Preise wie im Dashboard: 0,084 € pro SMS nach Deutschland, Österreich und in die übrige EU, ohne API-Gebühren.

Eine SMS aus Node.js senden

Das Node.js-Beispiel aus der Dokumentation, ergänzt um einen Idempotency-Key; dieselbe Anfrage in curl, PHP, Python, C# und Java finden Sie dort ebenfalls.

const res = await fetch("https://www.topsms.cz/api/sms/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer CLIENT_ID:SECRET",
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ to: "+4915112345678", text: "MeineApp: Ihr Datenexport ist fertig.", from: "MeineApp" }),
})
console.log(await res.json())

Die Antwort enthält id (damit fragen Sie den Status ab), smsCount (berechnete Teile) und price. Beträge gibt die API in CZK an, der Währung, in der das Guthaben geführt wird. Erzeugen Sie den Schlüssel in der Praxis einmal pro fachlicher Nachricht und verwenden Sie ihn bei Wiederholungen erneut.

Vollständige API-Dokumentation →

Häufige Fragen

Brauche ich ein SDK?

Nein. Die API ist reines HTTP und JSON über HTTPS, jeder HTTP-Client funktioniert: curl, fetch, Guzzle, requests. Für PHP gibt es die optionale Bibliothek topsms/topsms-php, und aus der OpenAPI-Spezifikation lässt sich ein Client generieren.

Wie teste ich, ohne echte SMS zu senden?

Legen Sie im Dashboard einen Testschlüssel an. Er sendet und berechnet nichts, liefert dieselben Antworten wie ein Produktivschlüssel mit "test": true und simuliert Statuswechsel und Webhooks nach 2 bis 4 Sekunden.

Wie sind Webhooks abgesichert?

Jeder Webhook trägt den Header X-TopSMS-Signature mit einem HMAC-SHA256 über den rohen Request-Body, signiert mit dem Webhook-Secret, das beim Anlegen des Schlüssels angezeigt wird. Prüfen Sie die Signatur über den Rohinhalt, nicht über das geparste JSON.

Welche Rate-Limits gelten?

Pro API-Schlüssel standardmäßig 60 Anfragen pro Minute, im Dashboard einstellbar bis 1.000. Eine Massenanfrage zählt als eine Anfrage, auch wenn sie bis zu 500 Nachrichten enthält.

Können KI-Agenten die API nutzen?

Ja. Der offizielle MCP-Server topsms-mcp stellt Versand, Planung, Status, Bestätigungscodes und Guthaben als Werkzeuge für Claude, Cursor und andere Assistenten bereit. Er ruft dieselbe REST-API auf, mit denselben Preisen und Limits.

Testen Sie mit 10 SMS gratis

Kostenloses Konto, aktiv, sobald Sie Ihre Mobilnummer bestätigt haben. Ohne Kreditkarte, ohne Grundgebühr, Prepaid-Guthaben ohne Verfall.

Kostenloses Konto anlegenErst Fragen klären? Kontakt

Weitere Anwendungen