SMS Masivos

Envío de SMS individuales, por lotes y programados. Una sola petición a POST /sms/send acepta varios destinatarios separados por coma, con remitente personalizado, programación de fecha y acortador de URLs integrado.

¿Envías códigos de verificación, login o 2FA? Usa Verificación OTP (POST /v2/otp), no este endpoint. /sms/send no tiene prioridad de red ni manejo de códigos.

Para volúmenes grandes envía lotes de números en una sola petición en lugar de una petición por destinatario: reduce overhead HTTP y evita saturar la API. Consulta la guía SMS Masivos y las Buenas prácticas de envío.

Enviar SMS
POST /sms/send
Enviar SMS
GET /sms/send

Enviar SMS

POST https://api.smsmasivos.com.mx/sms/send

¿Envías códigos de verificación, login o 2FA? No uses este endpoint. /sms/send es para marketing y notificaciones: sin prioridad de red ni manejo de códigos. En pruebas parecerá funcionar, pero en producción tus códigos llegarán tarde o no llegarán. Para verificación usa POST /v2/otp.

Envía un mensaje SMS a uno o múltiples destinatarios. El mensaje se envía sin acentos para garantizar compatibilidad con todas las operadoras.

No uses este endpoint para códigos de verificación, login o 2FA. Aunque el mensaje pueda enviarse, pierdes la generación, expiración, validación y control de intentos disponibles en POST /v2/otp. Más contexto en Verificación OTP.

Para varios destinatarios envía los números separados por coma en una sola petición (máximo 500, sin repetidos), en lugar de una petición por número: reduce overhead y evita saturar la API. Antes de integrar a producción, prueba con sandbox: 1 (ejecuta todas las validaciones y genera referencias, sin entregar el mensaje ni consumir saldo; límite de 1000 pruebas por día). Consulta también las Buenas prácticas de envío.

Detalles que conviene conocer:

  • Los acentos se reemplazan automáticamente (áa); el mensaje siempre sale en alfabeto GSM-7 con límite de 160 caracteres.
  • channel: 2 envía por RCS: requiere sender con un remitente RCS vinculado a tu cuenta y no es compatible con flash.
  • Con shorten_url: 1 el mensaje debe contener exactamente una URL.
  • Los envíos programados (date) usan la zona horaria America/Mexico_City y no están disponibles en sandbox.
Parameters
numbersstringrequerido
Números de teléfono destino separados por coma, máximo 500 por petición, sin números repetidos. Cada número debe tener exactamente 10 dígitos, sin código de país (el país va en country_code). Con find_country_code en 1, cada número debe tener 12 dígitos con el código de país incluido.
messagestringrequerido
Contenido del mensaje SMS, máximo 160 caracteres. Los acentos y caracteres especiales se sustituyen automáticamente (por ejemplo á por a y ñ por n), por lo que el mensaje siempre se envía en alfabeto GSM-7.
senderstringopcional
Remitente alfanumérico registrado en la cuenta (servicio de pago). Si la cuenta no tiene registrado el remitente indicado, el parámetro se ignora y se envía con el remitente por defecto. Obligatorio y debe coincidir con un remitente RCS de la cuenta cuando channel es 2.
country_codestringopcional
Código de país (por defecto 52 para México). No requerido si se usa find_country_code.
find_country_codeenumopcional

Origen del código de país:

  • 0: se toma de country_code
  • 1: se extrae de cada número (los números deben tener 12 dígitos con el país incluido)
01
namestringopcional
Nombre de la campaña (máximo 100 caracteres). Si no se envía, se genera uno automático.
datestringopcional
Fecha programada para envío diferido (formato YYYY-MM-DD HH:MM:SS, zona horaria America/Mexico_City). Debe ser futura. No disponible en modo sandbox.
sandboxenumopcional
1 = modo de prueba: ejecuta todas las validaciones y genera referencias, pero no entrega el mensaje ni consume créditos. Límite de 1000 envíos de prueba por día. No admite envíos programados.01
channelenumopcional

Canal de entrega:

  • 1: SMS
  • 2: RCS

RCS requiere el parámetro sender con un remitente RCS vinculado a la cuenta y no es compatible con flash.

12
flashenumopcional
1 = SMS flash (se muestra directamente en pantalla sin guardarse). La compatibilidad depende del dispositivo y operador. No compatible con RCS (channel: 2).01
shorten_urlenumopcional
1 = acortar la URL del mensaje automáticamente. El mensaje debe contener exactamente una URL: sin URL o con más de una, la petición se rechaza.01
extra_paramsstringopcional
Cadena JSON con hasta 3 pares clave-valor (cada clave y valor de 1 a 255 caracteres) que se devuelven después en los eventos de webhook asociados al mensaje.
read_confirmationobjectopcional
Configuración de confirmación de lectura por URL acortada.

Además de los errores globales de autenticación (auth_*, ver Errores y límites), este endpoint puede responder:

Códigos de error

CódigoCuándo ocurreQué hacer
sms_01El mensaje llegó vacío.Envía message con contenido.
sms_02Mensaje de más de 160 caracteres.Acorta el texto o usa shorten_url si el exceso es por una URL.
sms_03 / sms_04Números ausentes o con formato incorrecto.Envía 10 dígitos por número, separados por coma, sin código de país.
sms_05 / sms_18Código de país ausente o no soportado.Envía country_code (52 para México).
sms_06Nombre de campaña de más de 100 caracteres.Acorta name.
sms_07Créditos insuficientes.Consulta tu saldo con /credits/consult y recarga.
sms_15Más de 500 destinatarios.Divide el envío en lotes de hasta 500.
sms_16Número repetido en la lista.Deduplica los números antes de enviar.
sms_17Límite diario de sandbox (1000) excedido.Espera al día siguiente o prueba con menos envíos.
sms_20 / sms_21Fecha programada en el pasado o con formato inválido.Usa YYYY-MM-DD HH:MM:SS futuro (hora de Ciudad de México).
sms_24Lada no soportada.Verifica el número; contacta a soporte si la lada es válida.
sms_29 / sms_31shorten_url activo sin URL en el mensaje, o con más de una.Incluye exactamente una URL.
sms_36channel inválido.Usa 1 (SMS) o 2 (RCS).
sms_37 / sms_38RCS sin remitente, o con remitente no vinculado.Envía sender con un remitente RCS registrado en tu cuenta.
sms_39 / sms_40flash inválido o combinado con RCS.Usa 0 o 1; flash no está disponible en RCS.

El éxito responde sms_11 (o sms_19 si el envío fue a un solo número y es una línea fija: es informativo, el mensaje sí se envió).

curl -X POST https://api.smsmasivos.com.mx/sms/send \
  -H "Content-Type: application/json" \
  -H "apikey: TU_API_KEY" \
  -d '{
    "numbers": "5512345678",
    "message": "Hola {nombre}, tu pedido esta confirmado.",
    "sender": "MiEmpresa"
  }'
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.smsmasivos.com.mx/sms/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'apikey: ' . getenv('SMSMASIVOS_API_KEY')
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'numbers' => '5512345678',
    'message' => 'Hola {nombre}, tu pedido esta confirmado.',
    'sender' => 'MiEmpresa'
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
import requests

response = requests.post(
    'https://api.smsmasivos.com.mx/sms/send',
    headers={
        'Content-Type': 'application/json',
        'apikey': 'TU_API_KEY'
    },
    json={
        'numbers': '5512345678',
        'message': 'Hola {nombre}, tu pedido esta confirmado.',
        'sender': 'MiEmpresa'
    }
)
print(response.json())
const response = await fetch('https://api.smsmasivos.com.mx/sms/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'apikey': process.env.SMSMASIVOS_API_KEY
  },
  body: JSON.stringify({
    numbers: '5512345678',
    message: 'Hola {nombre}, tu pedido esta confirmado.',
    sender: 'MiEmpresa'
  })
});
const data = await response.json();
console.log(data);
const axios = require('axios');

const { data } = await axios.post(
  'https://api.smsmasivos.com.mx/sms/send',
  {
    numbers: '5512345678',
    message: 'Hola {nombre}, tu pedido esta confirmado.',
    sender: 'MiEmpresa'
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'apikey': process.env.SMSMASIVOS_API_KEY
    }
  }
);
console.log(data);
require 'net/http'
require 'json'

uri = URI('https://api.smsmasivos.com.mx/sms/send')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.path, {
  'Content-Type' => 'application/json',
  'apikey' => ENV['SMSMASIVOS_API_KEY']
})
request.body = {
  numbers: '5512345678',
  message: 'Hola {nombre}, tu pedido esta confirmado.',
  sender: 'MiEmpresa'
}.to_json

response = http.request(request)
puts JSON.parse(response.body)
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("apikey", "TU_API_KEY");

var payload = new
{
    numbers = "5512345678",
    message = "Hola {nombre}, tu pedido esta confirmado.",
    sender = "MiEmpresa"
};

var response = await client.PostAsJsonAsync(
    "https://api.smsmasivos.com.mx/sms/send",
    payload
);
var result = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(result);
OkHttpClient client = new OkHttpClient();

String json = "{"
    + "\"numbers\":\"5512345678\","
    + "\"message\":\"Hola {nombre}, tu pedido esta confirmado.\","
    + "\"sender\":\"MiEmpresa\""
    + "}";

Request request = new Request.Builder()
    .url("https://api.smsmasivos.com.mx/sms/send")
    .post(RequestBody.create(json, MediaType.parse("application/json")))
    .addHeader("apikey", "TU_API_KEY")
    .build();

Response response = client.newCall(request).execute();
System.out.println(response.body().string());
Response
{
  "success": true,
  "message": "sent_messages",
  "status": 200,
  "code": "sms_11",
  "total_messages": 2,
  "references": [
    {
      "reference": "abc123def456ghi789jkl",
      "number": "525512345678"
    },
    {
      "reference": "xyz987uvw654rst321mno",
      "number": "525598765432"
    }
  ],
  "credit": 3
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Enviar SMS

GET https://api.smsmasivos.com.mx/sms/send
Envía un solo SMS con los parámetros en el query string. Recomendamos usar la versión POST para no exponer tu API Key ni el contenido del mensaje en la URL.

Este método expone tu API Key y el mensaje en la URL. Usa la versión POST.

Query parameters
numbersstringrequerido
Números de teléfono destino separados por coma (10 dígitos cada uno, sin código de país; máximo 500)
messagestringrequerido
Contenido del mensaje SMS
senderstringopcional
Remitente alfanumérico (máx 11 caracteres). Si no se especifica, usa el predeterminado de la cuenta.
country_codestringopcional
Código de país (por defecto: 52 para México)
curl https://api.smsmasivos.com.mx/sms/send?numbers=5512345678&message=Hola desde SMS Masivos!
const SMS Masivo = await sms.smsmasivos.list({ numbers: '5512345678', message: 'Hola desde SMS Masivos!' })
SMS Masivo = sms.smsmasivos.list(numbers="5512345678", message="Hola desde SMS Masivos!")
SMS Masivo, err := client.Smsmasivos.List(ctx, nil)
Response
{
  "success": true,
  "message": "sent_messages",
  "status": 200,
  "code": "sms_11",
  "total_messages": 1,
  "references": [
    {
      "reference": "abc123def456ghi789jkl",
      "number": "525512345678"
    }
  ],
  "credit": 1.5,
  "campaignId": 12345
}
{
  "success": false,
  "message": "Parámetros inválidos.",
  "status": 400,
  "code": "<string>"
}
{
  "success": false,
  "message": "API Key inválida o no existe.",
  "status": 401,
  "code": "auth_05"
}
{
  "success": false,
  "message": "La dirección IP no está autorizada para acceder.",
  "status": 403,
  "code": "auth_04"
}
{
  "success": false,
  "message": "Demasiadas solicitudes. Límite: 100 mensajes/segundo (producción) o 100/día (sandbox).",
  "status": 429,
  "code": "rate_01"
}
{
  "success": false,
  "message": "Error interno del servidor. Contacta a soporte con el request_id.",
  "status": 500,
  "code": "server_01",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Objeto de respuesta

Estructura de la respuesta que devuelven estos endpoints.

Atributos
successboolean
messagestring
Mensaje de estado
statusinteger
codestring
Código de respuesta
total_messagesinteger
Número de mensajes enviados
referencesarray<object>
IDs de referencia de los mensajes
creditnumber
Créditos consumidos
campaignIdinteger
ID de campaña (solo cuando showCampaignId=true)
Objeto de respuesta
{
  "success": true,
  "message": "sent_messages",
  "status": 200,
  "code": "sms_11",
  "total_messages": 1,
  "references": [],
  "credit": 1.5,
  "campaignId": 12345
}