Versand
Massen-SMS mit POST /v1/batches senden
/v1/batchesSenden 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"
]
}'const res = await fetch("https://bulksmsapi.cc/v1/batches", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "spring-sale-0412",
},
body: JSON.stringify({
name: "Spring sale",
text: "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
to: ["+14155550123", "+447400123456", "+4915123456789"],
}),
});
const batch = await res.json();
console.log(res.status, batch.id, batch.recipients, batch.cost);import json, os, urllib.request
req = urllib.request.Request(
"https://bulksmsapi.cc/v1/batches",
data=json.dumps({
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": ["+14155550123", "+447400123456", "+4915123456789"],
}).encode(),
headers={
"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
"Content-Type": "application/json",
"Idempotency-Key": "spring-sale-0412",
"User-Agent": "northwind-app/1.0",
},
method="POST",
)
with urllib.request.urlopen(req) as res:
batch = json.load(res)
print(res.status, batch["id"], batch["recipients"], batch["cost"])<?php
$ch = curl_init("https://bulksmsapi.cc/v1/batches");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
"Content-Type: application/json",
"Idempotency-Key: spring-sale-0412",
],
CURLOPT_POSTFIELDS => json_encode([
"name" => "Spring sale",
"text" => "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to" => ["+14155550123", "+447400123456", "+4915123456789"],
]),
]);
$batch = json_decode(curl_exec($ch), true);
echo $batch["id"], " ", $batch["recipients"], " ", $batch["cost"], "\n";package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
body, _ := json.Marshal(map[string]any{
"name": "Spring sale",
"text": "Spring sale at Northwind: 20% off until Sunday. Opt out: northwind.example/sms",
"to": []string{"+14155550123", "+447400123456", "+4915123456789"},
})
req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/batches", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "spring-sale-0412")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var batch map[string]any
json.NewDecoder(res.Body).Decode(&batch)
fmt.Println(res.StatusCode, batch["id"], batch["recipients"], batch["cost"])
}{
"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:
| reason | Bedeutung |
|---|---|
| invalid_number | Nach Bereinigung nicht als + und 7 bis 15 Ziffern lesbar. |
| duplicate | Die gleiche Nummer erschien bereits früher in der Anfrage. |
| unsupported_country | Die Nummer gehört nicht zu einem bepreisten Land. |
| too_long | Der personalisierte Text benötigt mehr als 10 Segmente. |
| empty_text | Der personalisierte Text ist leer. |
| suppressed | Die 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.
/v1/batches/{id}/cancelStorniert 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
/v1/batches/{id}Der Batch mit Live-Zählern pro Status. Abfragen Sie ihn für Fortschritt oder nutzen Sie Webhooks.
/v1/batchesBatches 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.