SMS Versand mit HTTPS und API Key

Kurzbeschreibung

Mit dieser Schnittstelle können Sie SMS per HTTPS-Aufruf mit API Key versenden. Damit sind Sie unabhängig von Benutzer und Passwort.

Weiter unten finden Sie Beispiel-Aufrufe und Statuscodes.

Weitere Schnittstellen wie Guthaben-Abfrage, Sendeberichte und mehr finden Sie unter Hilfe -> Schnittstellen.

API Key

Zuerst benötigen Sie einen API-Key. Diesen erstellen, rotieren und löschen Sie unter Einstellungen -> API Keys

API URL

Die Schnittstelle akzeptiert verschiedene Formate als Eingabe.

POST oder GET: https://www.sms4.de/cgi-bin/sms_api.pl
Für JSON POST: Content-Type: application/json
Für Webform POST: Content-Type: application/x-www-form-urlencoded
Oder normaler GET Aufruf der URL mit Parametern

Parameter

Parameter	Pflicht	Beschreibung
apikey	Ja	API Key
sender	Ja	Die Absenderkennung muss eine Handynummer oder 6 bis 11 Zeichen Text ohne Sonderzeichen sein. Eine zu kurzer Absender gibt einen Fehler, ein zu langer wird abgeschnitten.
to	Ja	Die Handynummer des Empfängers. Eine einzelne Nummern oder als Liste mit Nummern im JSON-Format ["Nr1","Nr2"] oder Komma-separiert im Web-Format.
text	Ja	SMS Text als einzelner String oder als Array von Texten im JSON-Format `["Text1","Text2"]`. Bei einem Array muss die Anzahl der Texte exakt mit der Anzahl der Empfängernummern in to übereinstimmen – jede Nummer erhält dann ihren eigenen Text.
smstype	Nein	Tarif. Erlaubt: 1 oder 7. Wenn nicht gesetzt: Tarif 1
senddate	Nein	Zeitgesteuerter Versand im Format YYYYMMDDHHMM, z.B. 202612241450 für 24.12.2026 14:50
test	Nein	1 = Testsendung (Simulation), 0 = normaler Versand

Folgende Felder sind Pflichtfelder: apikey, sender, to, text

Fehlt der Parameter smstype, wird Tarif 1 verwendet. Die Tarif-Beschreibung finden Sie auf der Preisliste
Fehlt der Parameter test wird 0 genommen und die SMS versendet.

Status

Die API liefert ein Feld "Status" zurück. Der Wert ist entweder OK, Error oder Test. Test liefert sie nur, wenn der Parameter test=1 beim Aufruf der API gesetzt ist.
Wenn mehr als eine SMS gesendet wird (mehrere Empfänger), wird die Anfrage als Job gespeichert. In diesem Fall liefert die API statuscode 5 mit jobid und smsid = 0.

Fehlercodes

Statuscode	Statustext
0	SMS erfolgreich versendet
5	SMS erfolgreich für späteren Versand gespeichert
10	Falsche Authentifizierung, API Key falsch oder fehlt
11	API Key fehlt
20	Handynummer fehlt
21	Ungültige Handynummer
22	Handynummer zu kurz
23	Handynummer zu lang
25	SMS Text fehlt
26	Anzahl der Texte stimmt nicht mit der Anzahl der Empfängernummern überein
30	Ungültiger SMS Tarif (nur 1 und 7 erlaubt)
40	Test SMS aufgebraucht
41	Guthaben aufgebraucht
42	Monatslimit erreicht
43	Kontingent aufgebraucht
50	Absender fehlt
53	Die Absenderkennung muss eine Handynummer oder 6 bis 11 Zeichen Text ohne Sonderzeichen sein.
51	Ungültige Absenderkennung
52	Absenderkennung zu kurz
61	Sendezeit ungültig oder in der Vergangenheit
99	Störung beim SMSC

Beispielaufrufe

1) POST JSON

Verwenden Sie Content-Type: application/json
Sie können den Text an eine einzelne Nummer senden oder gleichzeitig an mehrere Nummern als Array.
Optional können Sie eine Sendezeit setzen.

POST https://www.sms4.de/cgi-bin/sms_api.pl
Content-Type: application/json

{
  "apikey": "DEIN_APIKEY",
  "sender": "sms4test",
  "to": ["49170000001", "49170000002"],
  "text": "Geplante Nachricht an mehrere Empfaenger",
  "smstype": 7,
  "senddate": "202612241800",
  "replyto": "antwort@example.com",
  "test": 0
}

2) POST Webform

Sie können auch einen normalen Post absetzen, wie es ein Webbrowser tun würde.
Verwenden Sie dazu Content-Type: application/x-www-form-urlencoded.

POST https://www.sms4.de/cgi-bin/sms_api.pl
Content-Type: application/x-www-form-urlencoded

apikey=YOUR_APIKEY&sender=sms4test&to=49170000001&text=Test-Nachricht%20via%20sms4%20API&smstype=1&test=0

3) GET Web

https://www.sms4.de/cgi-bin/sms_api.pl?apikey=YOUR_APIKEY&sender=sms4test&to=49170000001&text=Hallo%20Welt&smstype=1&test=0

4) POST JSON mit individuellen Texten pro Empfänger

Das Feld text ist ein Array – ein Text pro Empfänger.
Die Anzahl der Texte muss exakt mit der Anzahl der Nummern in to übereinstimmen (Fehlercode 26 sonst).
Die Nachrichten werden sofort als Batch-Job in die Warteschlange gestellt (statuscode 5, jobid wird zurückgegeben).
senddate wird in diesem Modus ignoriert – der Versand erfolgt zur nächsten vollen Minute.

POST https://www.sms4.de/cgi-bin/sms_api.pl
Content-Type: application/json

{
  "apikey": "DEIN_APIKEY",
  "sender": "sms4test",
  "to":   ["49170000001", "49170000002", "49170000003"],
  "text": ["Hallo Max!",  "Hallo Anna!", "Hallo Tom!"],
  "smstype": 1
}

Antwort bei Erfolg:

{
  "jobid": "a1b2c3d4e5f67890abcd1234ef567890",
  "smsid": 0,
  "status": "OK",
  "statuscode": 5,
  "statustext": "SMS erfolgreich fuer spaeteren Versand gespeichert"
}

Beispielantworten der API

Die SMS Schnittstelle gibt eine smsid zurück, mit welcher Sie Sendeberichte pullen können.
Weitere Infos finden Sie unter Schnittstelle für Sendeberichte
Bei mehreren Empfängern wird stattdessen eine jobid zurückgegeben.

Erfolg

{
  "jobid": 0
  "smsid": 12345678,
  "status": "OK",
  "statuscode": 0,
  "statustext": "SMS erfolgreich versendet",
}

Die Job-ID gibt es aktuell nur für gespeicherte Aufträge in der Zukunft.

Erfolg (Testmodus, test=1)

{
  "jobid": 0
  "smsid": 12345678,
  "status": "Test",
  "statuscode": 0,
  "statustext": "SMS erfolgreich versendet",
}

Erfolg (geplanter Versand zu späterer Zeit)

{
  "jobid": "1a2b3c4d56",
  "smsid": 0
  "status": "OK",
  "statuscode": 5,
  "statustext": "SMS erfolgreich fuer spaeteren Versand gespeichert",
}

Fehler bei Authentifizierung

{
  "jobid": 0,
  "smsid": 0,
  "status": "Error",
  "statuscode": 10,
  "statustext": "Falsche Authentifizierung, API Key falsch oder fehlt"
}

Kontakt