Comece agora
Referência da API Bulk SMS
BulkSMSAPI é uma API de SMS em massa para desenvolvedores: envie um texto ou um lote de até 10.000 números por requisição para 227 países via REST, acompanhe cada mensagem com webhooks assinados e pague por mensagem a partir de um saldo pré-pago. Esta referência cobre todos os endpoints, campos, eventos e erros da API. Cada página também está disponível como Markdown: adicione .md ao seu endereço.
URL base e formato
Todas as requisições vão para https://bulksmsapi.cc/v1 via HTTPS. Os corpos são JSON (Content-Type: application/json, UTF-8), e toda resposta é JSON, incluindo erros. Os horários são ISO 8601 em UTC. O dinheiro é uma string em dólares americanos com cinco decimais ("0.00507"), então preços abaixo de um centavo são exatos.
Endpoints
| Método e caminho | O que faz | Key |
|---|---|---|
| POST /v1/messages | Envie um texto para um número | Yes |
| POST /v1/batches | Envie para até 10.000 números, um texto ou um por número | Yes |
| GET /v1/messages/{id} | Uma mensagem com seu status e preço | Yes |
| GET /v1/messages | Mensagens, mais recentes primeiro, filtrar por lote ou status | Yes |
| GET /v1/batches/{id} | Um lote com contagens por status | Yes |
| GET /v1/batches | Lotes, mais recentes primeiro | Yes |
| POST /v1/batches/{id}/cancel | Cancelar um lote agendado, reembolso total | Yes |
| POST /v1/estimates | Precificar uma requisição sem enviá-la | Yes |
| GET /v1/balance | Saldo em USD | Yes |
| GET /v1/pricing | Preço por segmento para cada país | No |
| GET /v1/pricing/{country} | Preço para um país (código ISO) | No |
Uma primeira requisição
Crie uma chave API no console, exporte-a e envie uma mensagem. A resposta é 202 com o objeto da mensagem: o custo é deduzido do saldo e a mensagem é colocada na fila.
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
}Como uma mensagem se move
Mensagens aceitas ficam queued (ou scheduled quando a requisição tem send_at). A fila as entrega à rede a cada dois segundos, até 1.200 por minuto por conta, e elas se tornam sent. O status final é delivered ou failed; uma mensagem falha é reembolsada ao saldo imediatamente. Cada status final chama seu webhook com um evento assinado.
Limites em resumo
| Limite | Valor |
|---|---|
| Destinatários por requisição API | 10,000 |
| Destinatários por campanha no console | 50,000 |
| Requisições por minuto por chave | 600 |
| Mensagens entregues à rede por minuto por conta | 1,200 |
| Texto mais longo | 10 segmentos (1.530 caracteres GSM-7 ou 670 UCS-2) |
| Janela de agendamento | De 2 minutos a 45 dias no futuro |
| Tentativas de webhook por evento | 10 |
| Memória de Idempotency-Key | 24 horas |
| Chaves API por conta | 10 |
Arquivos legíveis por máquina
- Especificação OpenAPI 3.1 para geradores de código e clientes API.
- llms-full.txt: toda esta referência em um arquivo de texto simples.
- Cada página da documentação em Markdown, por exemplo /en/docs/webhooks.md.