Versand

Massen-SMS mit POST /v1/batches senden

POST/v1/batches

Senden Sie bis zu 10.000 Nummern in einer Anfrage. Die gesamten Kosten werden sofort vom Guthaben abgebucht.

Anfragekörper

  • toarray of stringsoptional

    Nummern für einen gemeinsamen Text. Verwenden Sie entweder to mit text oder messages.

  • textstringoptional

    Der gemeinsame Text, erforderlich mit to.

  • messagesarray of objectsoptional

    Ein {to, text} pro Empfänger für personalisierte Texte.

  • namestringoptional

    Eine Bezeichnung für die Konsole, bis zu 100 Zeichen.

  • referencestringoptional

    Ihre eigene ID, bis zu 100 Zeichen, wird im Batch und jeder Nachricht zurückgegeben.

  • send_atstringoptional

    ISO 8601 Zeit, 2 Minuten bis 45 Tage im Voraus.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-0412" \
  -d '{
    "name": "Spring sale",
    "text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
    "to": [
      "+14155550123",
      "+447400123456",
      "+4915123456789"
    ]
  }'
202 AcceptedJSON
{
  "id": "bat_6TQ2W8M1ZK4N",
  "object": "batch",
  "name": "Spring sale",
  "status": "queued",
  "source": "api",
  "encoding": "GSM-7",
  "recipients": 3,
  "max_segments": 1,
  "cost": "0.02741",
  "refunded": "0.00000",
  "currency": "USD",
  "counts": { "scheduled": 0, "queued": 3, "sent": 0, "delivered": 0, "failed": 0, "canceled": 0 },
  "send_at": null,
  "reference": null,
  "created_at": "2026-11-07T09:31:40.102Z",
  "completed_at": null,
  "set_aside": []
}

Zurückgestellte Nummern

Jede Nummer wird einzeln bereinigt und bepreist. Nicht sendbare Nummern werden aus dem Batch ausgeschlossen, nicht berechnet und in set_aside mit einem Grund aufgeführt:

reasonBedeutung
invalid_numberNach Bereinigung nicht als + und 7 bis 15 Ziffern lesbar.
duplicateDie gleiche Nummer erschien bereits früher in der Anfrage.
unsupported_countryDie Nummer gehört nicht zu einem bepreisten Land.
too_longDer personalisierte Text benötigt mehr als 10 Segmente.
empty_textDer personalisierte Text ist leer.
suppressedDie Nummer steht auf Ihrer Nicht-Senden-Liste.

Wenn keine Nummer übrig bleibt, schlägt die Anfrage mit dem Code des ersten Grundes fehl (z.B. invalid_number) und es wird nichts berechnet.

Personalisierter Text pro Nummer

Verwenden Sie messages, um jedem Empfänger einen eigenen Text zu geben: Namen, Zeiten, Beträge. Jeder Text wird einzeln gezählt und bepreist, sodass ein Batch ein- und zweisegmentige Nachrichten mischen kann.

curl https://bulksmsapi.cc/v1/batches \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminders, 14 May",
    "send_at": "2026-05-13T16:00:00Z",
    "messages": [
      { "to": "+14155550123", "text": "Hi Ana, your dental check-up is tomorrow at 09:30." },
      { "to": "+14155550178", "text": "Hi Sam, your dental check-up is tomorrow at 11:00." }
    ]
  }'

Planung

Mit send_at warten der Batch und seine Nachrichten im Status scheduled und wechseln zur geplanten Minute in die Warteschlange. Die Kosten werden bei Annahme der Anfrage abgebucht, daher hat ein geplanter Batch immer seine Mittel. Ein geplanter Batch kann bis zum Start storniert werden.

POST/v1/batches/{id}/cancel

Storniert einen geplanten Batch: Jede Nachricht wird storniert und die vollen Kosten werden als eine Rückerstattungszeile dem Guthaben gutgeschrieben. Ein gestarteter Batch antwortet mit 409 not_cancelable.

curl -X POST https://bulksmsapi.cc/v1/batches/bat_6TQ2W8M1ZK4N/cancel \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

Batches abrufen und auflisten

GET/v1/batches/{id}

Der Batch mit Live-Zählern pro Status. Abfragen Sie ihn für Fortschritt oder nutzen Sie Webhooks.

GET/v1/batches

Batches des Kontos, neueste zuerst, mit Limit (1 bis 100) und starting_after (eine bat_ ID).

Batch-Felder

  • idstring

    bat_ gefolgt von 12 Zeichen.

  • statusstring

    scheduled, queued, sending, completed oder canceled.

  • sourcestring

    api oder console.

  • encodingstring

    GSM-7 oder UCS-2, falls Text Unicode benötigt.

  • recipientsinteger

    In den Batch aufgenommene Nummern.

  • max_segmentsinteger

    Höchste Segmentanzahl unter den Texten.

  • coststring

    Vom Guthaben abgezogener Betrag, USD.

  • refundedstring

    Bisher für fehlgeschlagene oder abgebrochene Nachrichten erstatteter Betrag.

  • countsobject

    Nachrichten pro Status: scheduled, queued, sent, delivered, failed, canceled.

  • send_atstring or null

    Geplante Zeit, falls vorhanden.

  • completed_atstring or null

    Wenn die letzte Nachricht einen Endstatus erreicht hat.

Größere Listen

Teilen Sie Listen mit über 10.000 Nummern in mehrere Anfragen auf, jede mit eigener Idempotency-Key (z.B. Listen-ID und Teilnummer). Nachrichten werden in Reihenfolge mit bis zu 1.200 pro Minute pro Konto an das Netzwerk übergeben, sodass eine Kampagne mit 50.000 Nummern in unter einer Stunde unterwegs ist. Die Konsole nimmt 50.000 Nummern pro Kampagne aus einer Einfügung oder CSV-Datei.

Massen-SMS mit POST /v1/batches senden | BulkSMSAPI Dokumentation