Envío

Envía un SMS con POST /v1/messages

Ver como Markdown Especificación OpenAPI

POST/v1/messages

Envía un mensaje a un número. El costo se deduce del saldo cuando se acepta la solicitud.

Cuerpo de la solicitud

tostringrequerido
El número en formato internacional, por ejemplo +14155550123. Se eliminan espacios, guiones, paréntesis y el prefijo 00.
textstringrequerido
El mensaje. Hasta 10 segmentos; ver Texto y segmentos.
referencestringopcional
Tu propio ID, hasta 100 caracteres. Aparece en el objeto del mensaje y en cada webhook.
send_atstringopcional
Hora ISO 8601 para enviar, de 2 minutos a 45 días después. Sin esto, el mensaje se encola inmediatamente.

Añade un encabezado Idempotency-Key para reintentos seguros: ver Idempotencia.

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"])
}

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
}

El objeto de mensaje

Campos

idstring
ID del mensaje, msg_ seguido de 12 caracteres.
objectstring
Siempre message.
batch_idstring
El lote al que pertenece el mensaje (un mensaje individual también obtiene un lote).
tostring
El número en formato E.164, después de limpiarlo.
countrystring
Código ISO 3166 del país al que se facturó el número.
textstring
El texto enviado, con campos de fusión completados.
segmentsinteger
Número de segmentos SMS que usa el texto.
pricestring
Precio de este mensaje en USD, 5 decimales (precio por segmento multiplicado por segmentos).
currencystring
Siempre USD.
statusstring
scheduled, queued, sent, delivered, failed o canceled.
errorobject or null
Para mensajes failed o canceled: código y mensaje.
referencestring or null
Tu propia referencia de la solicitud.
created_atstring
Cuando se aceptó la solicitud (ISO 8601, UTC).
sent_atstring or null
Cuando el mensaje se entregó a la red.
done_atstring or null
Cuando se estableció el estado final (delivered, failed o canceled).

Obtener un mensaje

GET/v1/messages/{id}

Un mensaje por su ID msg_. Los mensajes de otras cuentas responden 404.

curl https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

const res = await fetch("https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX", {
  headers: { Authorization: `Bearer ${process.env.BULKSMSAPI_KEY}` },
});
const message = await res.json();
console.log(message.status, message.error);

import json, os, urllib.request

req = urllib.request.Request(
    "https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX",
    headers={"Authorization": "Bearer " + os.environ["BULKSMSAPI_KEY"], "User-Agent": "northwind-app/1.0"},
)
with urllib.request.urlopen(req) as res:
    message = json.load(res)
print(message["status"], message["error"])

<?php
$ch = curl_init("https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BULKSMSAPI_KEY")],
]);
$message = json_decode(curl_exec($ch), true);
echo $message["status"], "\n";

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BULKSMSAPI_KEY"))
	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(message["status"], message["error"])
}

Listar mensajes

GET/v1/messages

Mensajes de la cuenta, los más recientes primero.

Parámetros de consulta

batch_idstringopcional
Solo mensajes de este lote bat_.
statusstringopcional
scheduled, queued, sent, delivered, failed o canceled.
limitintegeropcional
De 1 a 100, predeterminado 20.
starting_afterstringopcional
Un id msg_: la página comienza después de este. Usa el último id de la página anterior.

curl "https://bulksmsapi.cc/v1/messages?status=failed&limit=50" \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

200 OKJSON

{
  "object": "list",
  "data": [ { "id": "msg_8F3K2Q9TZ1MX", "object": "message", "status": "failed", "...": "..." } ],
  "has_more": false
}

AnteriorAutenticación SiguienteLotes