Enviar SMS

¿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.

post/sms/send

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.

Autorización

apikeystringheaderrequerido

Cuerpo de la petición

application/json

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.

senderstring

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_codestring

Código de país (por defecto 52 para México). No requerido si se usa find_country_code.

find_country_codeenum

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)

enum:01

namestring

Nombre de la campaña (máximo 100 caracteres). Si no se envía, se genera uno automático.

datestring

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.

sandboxenum

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.

enum:01

channelenum

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.

enum:12

flashenum

1 = SMS flash (se muestra directamente en pantalla sin guardarse). La compatibilidad depende del dispositivo y operador. No compatible con RCS (channel: 2).

enum:01

shorten_urlenum

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.

enum:01

extra_paramsstring

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_confirmationobject

Configuración de confirmación de lectura por URL acortada.

▸ Ver atributos hijos▾ Ocultar atributos hijos

urlstring· uri

URL a la que se agrega un identificador de seguimiento dentro del mensaje.

contactinteger

Identificador de contacto a asociar (opcional).

Respuesta

200Mensaje enviado exitosamente

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

▸ Ver atributos del elemento▾ Ocultar atributos del elemento

referencestring

ID único de referencia del mensaje

numberstring

Número de teléfono del destinatario

creditnumber

Créditos consumidos

campaignIdinteger

ID de campaña (solo cuando showCampaignId=true)

400Error de validación o lógica de negocio

successboolean

Siempre false para respuestas de error

messagestring

Descripción del error en español

statusinteger

Código HTTP de la respuesta

codestring

Código de error estructurado ({dominio}_{número}). Identifica de forma única la causa del error para manejo programático.

401No autorizado: API Key no provista, inválida o expirada

successboolean

Siempre false

messagestring

Descripción del error de autenticación en español

statusinteger

Código HTTP

codestring

Código de error de autenticación (auth_01, auth_05, auth_06, auth_07, auth_99)

403Prohibido: La dirección IP no está autorizada para acceder (IP whitelist)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error: auth_04 (IP no autorizada en whitelist)

429Demasiadas peticiones: Límite de rate limit excedido (100 mensajes/segundo producción, 1000 envíos de prueba por día en sandbox)

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error de rate limit

500Error interno del servidor

successboolean

Siempre false

messagestring

Descripción del error

statusinteger

Código HTTP

codestring

Código de error interno

request_idstring· uuid

Identificador único de la petición. Inclúyelo al contactar a soporte.

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

Códigos de error

Código	Cuándo ocurre	Qué hacer
`sms_01`	El mensaje llegó vacío.	Envía `message` con contenido.
`sms_02`	Mensaje de más de 160 caracteres.	Acorta el texto o usa `shorten_url` si el exceso es por una URL.
`sms_03` / `sms_04`	Nú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_18`	Código de país ausente o no soportado.	Envía `country_code` (52 para México).
`sms_06`	Nombre de campaña de más de 100 caracteres.	Acorta `name`.
`sms_07`	Créditos insuficientes.	Consulta tu saldo con `/credits/consult` y recarga.
`sms_15`	Más de 500 destinatarios.	Divide el envío en lotes de hasta 500.
`sms_16`	Número repetido en la lista.	Deduplica los números antes de enviar.
`sms_17`	Límite diario de sandbox (1000) excedido.	Espera al día siguiente o prueba con menos envíos.
`sms_20` / `sms_21`	Fecha programada en el pasado o con formato inválido.	Usa `YYYY-MM-DD HH:MM:SS` futuro (hora de Ciudad de México).
`sms_24`	Lada no soportada.	Verifica el número; contacta a soporte si la lada es válida.
`sms_29` / `sms_31`	`shorten_url` activo sin URL en el mensaje, o con más de una.	Incluye exactamente una URL.
`sms_36`	`channel` inválido.	Usa `1` (SMS) o `2` (RCS).
`sms_37` / `sms_38`	RCS sin remitente, o con remitente no vinculado.	Envía `sender` con un remitente RCS registrado en tu cuenta.
`sms_39` / `sms_40`	`flash` 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ó).