Loslegen
Bulk SMS API-Referenz
BulkSMSAPI ist eine Bulk-SMS-API für Entwickler: Senden Sie eine Nachricht oder einen Batch mit bis zu 10.000 Nummern pro Anfrage in 227 Länder über REST, verfolgen Sie jede Nachricht mit signierten Webhooks und zahlen Sie pro Nachricht von einem Prepaid-Guthaben. Diese Referenz deckt jeden Endpunkt, jedes Feld, jedes Ereignis und jeden Fehler der API ab. Jede Seite ist auch als Markdown verfügbar: Fügen Sie .md zur Adresse hinzu.
Basis-URL und Format
Alle Anfragen gehen über HTTPS an https://bulksmsapi.cc/v1. Die Inhalte sind JSON (Content-Type: application/json, UTF-8), und jede Antwort ist JSON, einschließlich Fehler. Zeiten sind ISO 8601 in UTC. Geldbeträge sind Zeichenketten in US-Dollar mit fünf Dezimalstellen ("0.00507"), sodass Preise unter einem Cent exakt sind.
Endpunkte
| Methode und Pfad | Funktion | Key |
|---|---|---|
| POST /v1/messages | Sende einen Text an eine Nummer | Yes |
| POST /v1/batches | Sende an bis zu 10.000 Nummern, einen Text oder einen pro Nummer | Yes |
| GET /v1/messages/{id} | Eine Nachricht mit Status und Preis | Yes |
| GET /v1/messages | Nachrichten, neueste zuerst, nach Batch oder Status filtern | Yes |
| GET /v1/batches/{id} | Ein Batch mit Anzahl pro Status | Yes |
| GET /v1/batches | Batches, neueste zuerst | Yes |
| POST /v1/batches/{id}/cancel | Einen geplanten Batch stornieren, vollständige Rückerstattung | Yes |
| POST /v1/estimates | Eine Anfrage bewerten, ohne sie zu senden | Yes |
| GET /v1/balance | Guthaben in USD | Yes |
| GET /v1/pricing | Preis pro Segment für jedes Land | No |
| GET /v1/pricing/{country} | Preis für ein Land (ISO-Code) | No |
Eine erste Anfrage
Erstellen Sie einen API-Schlüssel in der Konsole, exportieren Sie ihn und senden Sie eine Nachricht. Die Antwort ist 202 mit dem Nachrichtenobjekt: Die Kosten werden vom Guthaben abgezogen und die Nachricht wird in die Warteschlange gestellt.
curl https://bulksmsapi.cc/v1/messages \
-H "Authorization: Bearer $BULKSMSAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+14155550123",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"reference": "login-7781"
}'// Node.js 18 or newer (built-in fetch)
const res = await fetch("https://bulksmsapi.cc/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
to: "+14155550123",
text: "Your Northwind code is 482913. It expires in 10 minutes.",
reference: "login-7781",
}),
});
const message = await res.json();
console.log(res.status, message.id, message.status, message.price);# Python 3, standard library only
import json, os, urllib.request
req = urllib.request.Request(
"https://bulksmsapi.cc/v1/messages",
data=json.dumps({
"to": "+14155550123",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"reference": "login-7781",
}).encode(),
headers={
"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"],
"Content-Type": "application/json",
"User-Agent": "northwind-app/1.0",
},
method="POST",
)
with urllib.request.urlopen(req) as res:
message = json.load(res)
print(res.status, message["id"], message["status"], message["price"])<?php
// PHP 7.4 or newer with the curl extension
$ch = curl_init("https://bulksmsapi.cc/v1/messages");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("BULKSMSAPI_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"to" => "+14155550123",
"text" => "Your Northwind code is 482913. It expires in 10 minutes.",
"reference" => "login-7781",
]),
]);
$message = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $message["id"], " ", $message["status"], "\n";// Go 1.20 or newer, standard library only
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
body, _ := json.Marshal(map[string]any{
"to": "+14155550123",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"reference": "login-7781",
})
req, _ := http.NewRequest("POST", "https://bulksmsapi.cc/v1/messages", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var message map[string]any
json.NewDecoder(res.Body).Decode(&message)
fmt.Println(res.StatusCode, message["id"], message["status"], message["price"])
}{
"id": "msg_8F3K2Q9TZ1MX",
"object": "message",
"batch_id": "bat_4M7Q1X0PK2RS",
"to": "+14155550123",
"country": "US",
"text": "Your Northwind code is 482913. It expires in 10 minutes.",
"segments": 1,
"price": "0.00507",
"currency": "USD",
"status": "queued",
"error": null,
"reference": "login-7781",
"created_at": "2026-11-07T09:30:12.418Z",
"sent_at": null,
"done_at": null
}Wie eine Nachricht verarbeitet wird
Akzeptierte Nachrichten werden queued (oder scheduled, wenn die Anfrage send_at enthält). Die Warteschlange übergibt sie alle zwei Sekunden an das Netzwerk, bis zu 1.200 pro Minute pro Konto, und sie werden sent. Der endgültige Status ist delivered oder failed; eine fehlgeschlagene Nachricht wird sofort auf das Guthaben zurückerstattet. Jeder endgültige Status ruft Ihren Webhook mit einem signierten Ereignis auf.
Limits auf einen Blick
| Limit | Wert |
|---|---|
| Empfänger pro API-Anfrage | 10,000 |
| Empfänger pro Konsolenkampagne | 50,000 |
| Anfragen pro Minute pro Schlüssel | 600 |
| Nachrichten, die pro Minute pro Konto an das Netzwerk übergeben werden | 1,200 |
| Längster Text | 10 Segmente (1.530 GSM-7 oder 670 UCS-2 Zeichen) |
| Zeitfenster für die Planung | 2 Minuten bis 45 Tage im Voraus |
| Webhook-Versuche pro Ereignis | 10 |
| Idempotency-Key Speicher | 24 Stunden |
| API-Schlüssel pro Konto | 10 |
Maschinenlesbare Dateien
- OpenAPI 3.1 Specifikation für Code-Generatoren und API-Clients.
- llms-full.txt: Diese gesamte Referenz als eine einfache Textdatei.
- Jede Dokumentationsseite als Markdown, zum Beispiel /en/docs/webhooks.md.