Commencer
Référence de l'API Bulk SMS
BulkSMSAPI est une API SMS en masse pour développeurs : envoyez un texte ou un lot de jusqu'à 10 000 numéros par requête vers 227 pays via REST, suivez chaque message avec des webhooks signés, et payez par message depuis un solde prépayé. Cette référence couvre chaque endpoint, champ, événement et erreur de l'API. Chaque page est aussi disponible en Markdown : ajoutez .md à son adresse.
URL de base et format
Toutes les requêtes vont vers https://bulksmsapi.cc/v1 en HTTPS. Les corps sont en JSON (Content-Type: application/json, UTF-8), et chaque réponse est en JSON, y compris les erreurs. Les heures sont au format ISO 8601 en UTC. L'argent est une chaîne en dollars US avec cinq décimales ("0.00507"), donc les prix inférieurs à un centime sont exacts.
Endpoints
| Méthode et chemin | Fonction | Key |
|---|---|---|
| POST /v1/messages | Envoyer un texte à un numéro | Yes |
| POST /v1/batches | Envoyer à jusqu'à 10 000 numéros, un texte ou un par numéro | Yes |
| GET /v1/messages/{id} | Un message avec son statut et son prix | Yes |
| GET /v1/messages | Messages, les plus récentes en premier, filtrer par lot ou statut | Yes |
| GET /v1/batches/{id} | Un lot avec décompte par statut | Yes |
| GET /v1/batches | Lots, les plus récents en premier | Yes |
| POST /v1/batches/{id}/cancel | Annuler un lot programmé, remboursement intégral | Yes |
| POST /v1/estimates | Estimer le coût d'une requête sans l'envoyer | Yes |
| GET /v1/balance | Solde en USD | Yes |
| GET /v1/pricing | Prix par segment pour chaque pays | No |
| GET /v1/pricing/{country} | Prix pour un pays (code ISO) | No |
Première requête
Créez une clé API dans la console, exportez-la et envoyez un message. La réponse est 202 avec l'objet message : le coût est déduit du solde et le message est mis en file d'attente.
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
}Parcours d'un message
Les messages acceptés sont mis en file d'attente (queued) ou programmés (scheduled si la requête a un send_at). La file les transmet au réseau toutes les 2 secondes, jusqu'à 1 200 par minute par compte, et ils passent à l'état sent. Le statut final est delivered ou failed ; un message échoué est immédiatement remboursé sur le solde. Chaque statut final déclenche un webhook signé.
Limites en un coup d'œil
| Limite | Valeur |
|---|---|
| Destinataires par requête API | 10,000 |
| Destinataires par campagne console | 50,000 |
| Requêtes par minute par clé | 600 |
| Messages transmis au réseau par minute par compte | 1,200 |
| Texte le plus long | 10 segments (1 530 caractères GSM-7 ou 670 caractères UCS-2) |
| Fenêtre de programmation | De 2 minutes à 45 jours à l'avance |
| Tentatives de webhook par événement | 10 |
| Mémoire Idempotency-Key | 24 heures |
| Clés API par compte | 10 |
Fichiers machine-readable
- Spécification OpenAPI 3.1 pour générateurs de code et clients API.
- llms-full.txt : cette référence complète en un seul fichier texte.
- Chaque page de documentation au format Markdown, par exemple /en/docs/webhooks.md.