Comienza

Referencia de la API de Bulk SMS

BulkSMSAPI es una API de SMS masivos para desarrolladores: envía un mensaje o un lote de hasta 10,000 números por solicitud a 227 países mediante REST, sigue cada mensaje con webhooks firmados y paga por mensaje desde un saldo prepago. Esta referencia cubre cada endpoint, campo, evento y error de la API. Cada página también está disponible en Markdown: añade .md a su dirección.

URL base y formato

Todas las solicitudes van a https://bulksmsapi.cc/v1 sobre HTTPS. Los cuerpos son JSON (Content-Type: application/json, UTF-8) y cada respuesta es JSON, incluidos los errores. Los tiempos son ISO 8601 en UTC. El dinero es una cadena en dólares estadounidenses con cinco decimales ("0.00507"), por lo que los precios inferiores a un centavo son exactos.

Endpoints

Método y rutaQué haceKey
POST /v1/messagesEnviar un mensaje a un númeroYes
POST /v1/batchesEnviar hasta 10,000 números, un mensaje o uno por númeroYes
GET /v1/messages/{id}Un mensaje con su estado y precioYes
GET /v1/messagesMensajes, los más nuevos primero, filtrar por lote o estadoYes
GET /v1/batches/{id}Un lote con conteos por estadoYes
GET /v1/batchesLotes, los más nuevos primeroYes
POST /v1/batches/{id}/cancelCancelar un lote programado, reembolso completoYes
POST /v1/estimatesCotizar una solicitud sin enviarlaYes
GET /v1/balanceSaldo en USDYes
GET /v1/pricingPrecio por segmento para cada paísNo
GET /v1/pricing/{country}Precio para un país (código ISO)No

Primera solicitud

Crea una clave API en la consola, expórtala y envía un mensaje. La respuesta es 202 con el objeto del mensaje: el costo se deduce del saldo y el mensaje se pone en cola.

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"
  }'
202 AcceptedJSON
{
  "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
}

Cómo se mueve un mensaje

Los mensajes aceptados quedan queued (o scheduled si la solicitud tiene send_at). La cola los entrega a la red cada dos segundos, hasta 1,200 por minuto por cuenta, y pasan a sent. El estado final es delivered o failed; un mensaje fallido se reembolsa al saldo de inmediato. Cada estado final activa tu webhook con un evento firmado.

Límites a simple vista

LímiteValor
Destinatarios por solicitud API10,000
Destinatarios por campaña en consola50,000
Solicitudes por minuto por clave600
Mensajes entregados a la red por minuto por cuenta1,200
Texto más largo10 segmentos (1,530 caracteres GSM-7 o 670 UCS-2)
Ventana de programaciónDesde 2 minutos hasta 45 días adelante
Intentos de webhook por evento10
Memoria de Idempotency-Key24 horas
Claves API por cuenta10

Archivos legibles por máquina

Referencia de la API de Bulk SMS | Documentación de BulkSMSAPI