SMS-Versand
in Ihren Dienst integrieren.

Schnellstart

1. API-Schlüssel erstellen

   Nach Registrierung, Freigabe und OTP-Anmeldung unterAPI-Schlüssel verwalteneinen Schlüssel erstellen.

2. Credits bereitstellen

   Die API nutzt das Guthaben und die Preise Ihres Kontos. Der Betrag wird abgezogen, sobald die Sendung angenommen wird.

3. Senden und Ergebnisse prüfen

   Speichern Sie die Kampagnen-ID und prüfen Sie die Ergebnisse über die Status-API.

Unterstützte Länder

GET/api/v1/messages/countries

Aktive Länder und tatsächlich geltende Preise fragen Sie über die API ab. Geben Sie beim Senden das Land mit country an und verwenden Sie pro Anfrage nur Nummern desselben Landes. Für Länder ohne hinterlegten Preis werden keine Sendungen angenommen.

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

Mit API-Schlüssel authentifizieren

Fügen Sie jeder externen API-Anfrage den folgenden Header hinzu. Anmelde-Cookies oder OTP-Codes sind nicht nötig.

Authorization: Bearer hex_live_IHR_API_SCHLUESSEL

Der Schlüssel wird nur einmal bei der Erstellung angezeigt. Bewahren Sie ihn in einer Umgebungsvariable auf dem Server auf, niemals im Frontend-Code. Widerrufene Schlüssel und gesperrte Konten können die API nicht nutzen. Sie können bis zu 5 Schlüssel erstellen.

An bis zu 1.000 Nummern auf einmal senden

Senden Sie denselben Text an mehrere Nummern. Die Anfrage wird geprüft, in die Warteschlange gestellt und sofort beantwortet. Für unterschiedliche Inhalte pro Nummer senden Sie separate Anfragen mit jeweils neuem Idempotency-Key.

Enthält die Anfrage auch nur eine ungültige oder doppelte Nummer, wird sie vollständig abgelehnt – ohne Versand und ohne Abbuchung. Duplikate werden nach Umwandlung ins internationale Format geprüft.

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

So wird der Preis berechnet

Anzahl Nummern × Segmente (segments) × KontopreisUCS-2-Text passt mit bis zu 70 Zeichen in 1 Segment, danach 67 Zeichen pro Segment. Einfacher GSM-7-Text passt mit bis zu 160 Zeichen in 1 Segment, danach 153 pro Segment. Erweiterungszeichen zählen doppelt, Emojis nach UTF-16-Länge. unitPrice und cost sind in USDT. Der Preis in der Antwort ist der tatsächlich geltende; 0.025 oben ist nur ein Beispiel.

Ergebnis pro Nummer abfragen

Verwenden Sie die id aus der Sende-API. Abfragbar sind nur per API gesendete Kampagnen desselben Kontos. Die Abfrage liefert gespeicherte Ergebnisse. Für die neuesten Ergebnisse des Netzbetreibers rufen Sie zuerst die folgende Aktualisierungs-API auf.

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

limit ist 1–1.000 (Standard 100), offset ist 0–1.000 (Standard 0). Ist nextOffset null, ist es die letzte Seite. summary zählt alle Nummern nach Status. to wird im internationalen Format ohne + zurückgegeben, Zeitstempel in Unix-Millisekunden. Die Reihenfolge kann von der ursprünglichen Nummernreihenfolge abweichen; unterscheiden Sie die Nachrichten anhand ihrer id.

Neuesten Zustellstatus abrufen

Fragt die Logs des Netzbetreibers ab und aktualisiert die gespeicherten Ergebnisse. Ein Request-Body ist nicht nötig. Lesen Sie die Ergebnisse danach erneut per GET. Dieselbe Kampagne kann alle 30 Sekunden aktualisiert werden. Netzbetreiber-Logs sind bis 48 Stunden nach dem Versand abrufbar. Mit konfigurierten Webhooks können Ergebnisse auch automatisch übernommen werden.

curl -X POST 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{ "id": "35bed356-b84a-452a-8e94-98b538972ecd", "updated": 2 }

updated ist die Anzahl aktualisierter Zeilen. Solange Nachrichten noch warten oder keine neuen Ergebnisse vorliegen, kann der Wert 0 sein. Wir empfehlen, GET im Abstand von mindestens 10 Sekunden aufzurufen und refresh nur bei Bedarf anzufordern.

Statuscodes verstehen

state der Sendeanfrage

PREPARING: wird vorbereitet · RUNNING: in Bearbeitung · PAUSED: pausiert · DONE: Warteschlange abgearbeitet · CANCELED: storniert

Netzbetreiber können neue Statuscodes hinzufügen – behandeln Sie daher auch unbekannte status-Werte. Fehlergründe finden Sie in statusName, description und error.

Fehler behandeln

{ "error": "Nicht genügend Credits. Bitte laden Sie auf und senden Sie die Anfrage erneut.", "code": "INSUFFICIENT_CREDITS" }

Pro API-Schlüssel sind insgesamt 120 Anfragen pro Minute für Senden, Abfragen und Aktualisieren möglich. Wird das Limit erreicht, beachten Sie den Retry-After-Header. Die API ist für Server-zu-Server-Integrationen gedacht; CORS-Aufrufe aus dem Browser werden nicht unterstützt.

Mit Node.js verbinden

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

Erstellen Sie den Anfrageschlüssel einmal pro Vorgang und verwenden Sie ihn auch bei Wiederholungen nach ausbleibender Antwort. Wird ein erfolgreicher Vorgang mit neuem Schlüssel erneut gesendet, gilt er als separate Sendung.