Bulk-SMS-API v1

Authentifizierung

Erstellen Sie einen Schlüssel in der Konsole unter API und Webhooks; Schlüssel werden nach Ihrer ersten gutgeschriebenen Aufladung freigeschaltet. Senden Sie ihn bei jeder Anfrage als Bearer-Token. Ein Schlüssel wird einmal angezeigt; Sie können bis zu 5 Schlüssel behalten und jeden davon sofort widerrufen.

Authorization: Bearer smsb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Preise

Öffentlich, kein Schlüssel erforderlich. Der Preis pro SMS-Segment für jedes Ziel oder für einen ISO-Code.

GEThttps://smsbulk.cc/rest/v1/rates

GEThttps://smsbulk.cc/rest/v1/rates/{ISO}

{
  "country": "US",
  "name": "United States",
  "dial_code": "+1",
  "rate": "0.00485",
  "currency": "USD",
  "per": "message segment"
}

Guthaben

GEThttps://smsbulk.cc/rest/v1/credit

{ "credit": "125.40000", "currency": "USD", "account": "A418820037715" }

Kostenvoranschlag

Berechnet den Versand, ohne ihn zu senden. Verwendet denselben Text wie Senden.

POSThttps://smsbulk.cc/rest/v1/quote

{
  "recipients": 2,
  "messages": 2,
  "segments": { "min": 1, "max": 1 },
  "encoding": "GSM-7",
  "total": "0.01240",
  "currency": "USD",
  "credit": "125.40000",
  "credit_after": "125.38760",
  "countries": [
    { "country": "US", "recipients": 1, "rate": "0.00485", "segments": 1, "subtotal": "0.00485" },
    { "country": "GB", "recipients": 1, "rate": "0.00755", "segments": 1, "subtotal": "0.00755" }
  ],
  "left_out": []
}

Senden

Erstellt eine Kampagne, zieht den Gesamtbetrag von Ihrem Guthaben ab und reiht die Nachrichten ein. Antwortet mit 201 und der Kampagne. Nummern, die nicht gesendet werden können, werden in left_out aufgeführt und nie berechnet.

POSThttps://smsbulk.cc/rest/v1/send

HTTP/1.1 201 Created
{
  "campaign": {
    "id": "C507318264409",
    "name": null,
    "status": "sending",
    "source": "api",
    "test": false,
    "recipients": 2,
    "cost": "0.01240",
    "refunded": "0.00000",
    "net_cost": "0.01240",
    "currency": "USD",
    "send_at": null,
    "created_at": "2026-11-07T14:02:11.000Z",
    "started_at": "2026-11-07T14:02:11.000Z",
    "finished_at": null,
    "client_ref": "order-batch-17"
  },
  "messages": 2,
  "left_out": []
}

Kampagnen

GEThttps://smsbulk.cc/rest/v1/campaigns?limit=25&before={id}

GEThttps://smsbulk.cc/rest/v1/campaigns/{id}

GEThttps://smsbulk.cc/rest/v1/campaigns/{id}/messages?status=failed&limit=100&after={message id}

Eine einzelne Kampagne enthält Zählungen pro Status: eingereiht, gesendet, zugestellt, fehlgeschlagen und abgebrochen. Nachrichtenlisten-Seite mit after und has_more; bis zu 1.000 pro Seite.

Nachrichten

GEThttps://smsbulk.cc/rest/v1/messages/{id}

GEThttps://smsbulk.cc/rest/v1/messages?to=%2B14155550142&status=delivered&client_ref=order-batch-17&limit=50

{
  "id": "M220947781305",
  "campaign": "C507318264409",
  "to": "+14155550142",
  "country": "US",
  "segments": 1,
  "encoding": "GSM-7",
  "price": "0.00485",
  "status": "delivered",
  "reason": null,
  "reason_text": null,
  "refunded": false,
  "client_ref": "order-batch-17",
  "created_at": "2026-11-07T14:02:11.000Z",
  "sent_at": "2026-11-07T14:02:12.000Z",
  "finished_at": "2026-11-07T14:02:16.000Z"
}

Eine geplante Kampagne abbrechen

POSThttps://smsbulk.cc/rest/v1/campaigns/{id}/cancel

Funktioniert bis zum Startzeitpunkt. Die gesamten Kosten werden in einer Buchungszeile auf Ihr Guthaben zurückerstattet und der Kampagnenstatus wird auf abgebrochen gesetzt.

Webhooks

Setzen Sie eine Endpunkt-URL in der Konsole. Wir POSTEN JSON für message.delivered, message.failed und campaign.done, plus Test, wenn Sie Testereignis senden drücken. Jedes Ereignis trägt vier Header, und jede 2xx-Antwort innerhalb von 10 Sekunden gilt als empfangen.

Die Zustellung wird 8 Mal versucht: sofort, dann nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde, 3 Stunden, 6 Stunden und 12 Stunden. Jeder Versuch wird im Zustellungsprotokoll der Konsole mit seinem HTTP-Status und dem Anfang Ihrer Antwort angezeigt.

{
  "id": "dlv_3f9a1c07b2e44d58a6c1",
  "event": "message.failed",
  "created": "2026-11-07T14:02:16.000Z",
  "data": {
    "message": "M220947781305",
    "campaign": "C507318264409",
    "to": "+447400123456",
    "country": "GB",
    "status": "failed",
    "reason": "not_in_service",
    "segments": 1,
    "price": "0.00755",
    "client_ref": "order-batch-17"
  }
}

Signatur überprüfen

import crypto from "node:crypto";

// raw = the request body exactly as received (string), secret = your sbw_ signing secret
export function verify(raw, headers, secret) {
  const ts = headers["smsbulk-timestamp"];
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(ts + "\n" + raw).digest("base64");
  const got = headers["smsbulk-signature"] || "";
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
}

import base64, hashlib, hmac, time

def verify(raw: bytes, headers, secret: str) -> bool:
    ts = headers.get("Smsbulk-Timestamp", "")
    mac = hmac.new(secret.encode(), ts.encode() + b"\n" + raw, hashlib.sha256).digest()
    want = "sha256=" + base64.b64encode(mac).decode()
    fresh = abs(time.time() - int(ts or 0)) < 300
    return fresh and hmac.compare_digest(want, headers.get("Smsbulk-Signature", ""))

Fehler und Limits

Fehler verwenden den HTTP-Status und einen JSON-Body: {"error":{"code":"insufficient_credit","message":"..."}}. Es wird nichts berechnet, wenn eine Anfrage fehlschlägt.

Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.

Ausgelassene Codes

Nummern, die vor der Preisberechnung entfernt wurden, werden in left_out mit ihrer Position in Ihrer Liste, dem gesendeten Wert, einem Code und dem Grund zurückgegeben.

Status und Gründe

Fragen zur API? Öffnen Sie ein Ticket in der Konsole oder lesen Sie die FAQ.