Enviar SMS con un agente de IA vía la API SMS Mailpro™

El email es el canal por defecto. El SMS es el canal de la urgencia. Cuando tu agente de IA necesita alcanzar a un humano real en segundos — una caída, una alerta de fraude, un OTP, una actualización de envío — el SMS es lo que de verdad se lee dentro de un minuto. Esta guía muestra cómo enchufar Claude, GPT o cualquier LLM con tool calling a la API SMS Mailpro™, tanto para envíos individuales como para campañas masivas.

En resumen

• La API SMS Mailpro™ se autentica con id_client + api_key por HTTPS.
• Usa /send/add_single.json para un SMS individual y /send/add.json para envíos masivos.
• Números en formato internacional E.164 (p. ej. +34612345678) o con prefijo 00 — la API acepta los dos y guarda la forma normalizada.
• Cada endpoint está documentado en 20+ lenguajes en nuestro portal para desarrolladores.

Dónde el SMS guiado por IA tiene verdadero sentido

Alertas en tiempo real

Tu pipeline de monitoreo detecta un pico de errores 5xx. Un agente de IA lee la anomalía, clasifica la gravedad y dispara un SMS al ingeniero de guardia con contexto ("API v3, tasa de error ×12 en los últimos 5 min, endpoints CRM afectados") — no un bip vacío. Diagnóstico más rápido, menos fatiga de alertas.

OTPs y flujos de dos factores

El agente recibe una petición "autentica a este usuario", genera un código de 6 dígitos, lo guarda con caducidad y lo envía por SMS. El usuario lo teclea, el agente verifica. Hoy es un flujo a medida; con el próximo endpoint Verify/OTP (ver roadmap de la API SMS) será una sola llamada.

Fallback multicanal

El email no se abrió en 2 horas, pero urge. El agente cae a SMS — "Tu cita es en 1 hora" — usando la misma ficha de contacto de Mailpro™ v3. Orquestación cross-canal guiada por el razonamiento del LLM.

Campañas orientadas a eventos

Black Friday al mediodía: el agente elige la audiencia por frescura ("clientes que abrieron algún email en los últimos 14 días"), escribe una oferta de 140 caracteres y lanza una campaña vía /send/add.json. Oferta en vivo en menos de un minuto, cero clics en un dashboard.

Setup y modelo de precio SMS

id_client + api_key

Mismo patrón de auth que la API email v2. Ambos valores están en tu cuenta Mailpro™ en Configuración → Acceso a la API. La API SMS usa parámetros en snake_case (id_client, no IdClient) — pequeña diferencia con v2, vale la pena señalarla en el prompt del sistema del agente.

Créditos, tarifas por país, saldo de prueba

Los SMS no tienen precio fijo: el costo por mensaje depende del país de destino. Revisa el saldo en cualquier momento:

curl "https://api.mailpro.com/sms/credit/get.json?id_client=YOUR_ID&api_key=YOUR_API_KEY"

Respuesta:

{ "TotalCredits": 1476 }

Para precios por país, ver los precios Mailpro.

Sandbox

Aún no hay sandbox dedicada — prueba con volúmenes pequeños en tu cuenta real. Empieza con /send/add_single.json enviando a tu propio número antes de abrir el grifo del bulk.

Paso a paso: SMS individual enviado por un agente de IA

1. Esquema de la herramienta

tools = [{
    "name": "send_sms",
    "description": "Envía un SMS individual a un número vía Mailpro.",
    "input_schema": {
        "type": "object",
        "properties": {
            "to":      {"type": "string", "description": "Número en formato internacional E.164, p. ej. +34612345678"},
            "message": {"type": "string", "description": "Cuerpo del SMS, máx 160 car. por segmento"}
        },
        "required": ["to", "message"]
    }
}]

2. Formato de los números

Usa el formato internacional E.164: signo +, prefijo de país, número nacional, sin espacios ni guiones. El prefijo 00 en lugar de + también funciona. Ejemplos:

• España: +34612345678
• México: +525512345678
• Argentina: +5491122334455
• Colombia: +573001234567

Si el agente recibe entradas desordenadas ("612 34 56 78"), normaliza antes de enviar — bibliotecas como phonenumbers (Python) o libphonenumber-js (Node) lo resuelven sin esfuerzo.

3. Llamar a /send/add_single.json

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+34612345678" \
  -d "message=Tu código de verificación es 482913. Válido 10 min."

Respuesta:

{
  "Result": "OK",
  "IdSend": 98765,
  "RemainingCredits": 1474
}

4. Estado de entrega en la respuesta

Result: "OK" significa que el SMS fue aceptado por el gateway — aún no entregado al dispositivo. Para confirmación de entrega (DLR), escucha el próximo webhook sms.delivered (ver roadmap de la API SMS). Por ahora, RemainingCredits te indica que el envío fue facturado.

SMS en masa: alcanzar una lista entera

Gestionar listas de números (/list, /phone)

Las listas SMS son el equivalente a las libretas de direcciones email del lado SMS. Endpoints para listar, añadir, editar y eliminar listas y números están en /list/*.json y /phone/*.json.

Enviar una campaña con /send/add.json

curl -X POST "https://api.mailpro.com/sms/send/add.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "id_list=11088" \
  -d "message=Black Friday: 30% de descuento hasta medianoche. mailp.ro/bf2026"

El endpoint encola la campaña y dispara SMS a cada número de la lista.

Programado vs inmediato

Añade plan_date=2026-11-27T12:00:00 para programar. Omítelo para envío inmediato. El agente puede elegir la hora según el huso horario de los destinatarios — pero vigila el tiempo agregado: 10.000 SMS pueden tardar varios minutos en cruzar el gateway.

Importar números en masa vía archivo

¿Construyendo un agente de IA que envía SMS? Los planes de Mailpro incluyen la API de SMS, informes de entrega y el volumen que necesitas — a un precio predecible.

Como la API de email, la API SMS ahora expone un endpoint de subida de archivo:

curl -X POST "https://api.mailpro.com/sms/import/upload.json" \
  -F "id_client=YOUR_ID" \
  -F "api_key=YOUR_API_KEY" \
  -F "id_list=11088" \
  -F "[email protected]" \
  -F "webhook_url=https://example.com/hooks/import-done"

La primera columna del CSV debe llamarse Phone o PhoneNumber. Los números se normalizan del lado del servidor; las entradas inválidas se descartan (y se reportan en el resumen del job). Spec completa en la sección Import de la referencia SMS.

Ejemplos de código

Python (agente → SMS con retry)

import anthropic, requests, time

def send_sms(to, message, retries=3):
    for attempt in range(retries):
        r = requests.post(
            "https://api.mailpro.com/sms/send/add_single.json",
            data={
                "id_client": MAILPRO_ID, "api_key": MAILPRO_KEY,
                "to": to, "message": message
            }
        )
        if r.status_code == 429:
            time.sleep(2 ** attempt)  # backoff exponencial
            continue
        return r.json()
    raise Exception("Envío SMS fallido tras reintentos")

Node.js (webhook Express → Claude → SMS)

import express from "express";
import Anthropic from "@anthropic-ai/sdk";

const app = express();
const ai = new Anthropic();

app.post("/alert", async (req, res) => {
  const { severity, message } = req.body;
  const resp = await ai.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 256,
    tools: [/* esquema send_sms */],
    messages: [{ role: "user", content: `Alerta ${severity}: ${message}. Avisa a guardia.` }]
  });
  for (const b of resp.content) {
    if (b.type === "tool_use") {
      await fetch(`https://api.mailpro.com/sms/send/add_single.json`, {
        method: "POST",
        body: new URLSearchParams({
          id_client: ID, api_key: KEY,
          to: b.input.to, message: b.input.message
        })
      });
    }
  }
  res.sendStatus(200);
});

cURL

curl -X POST "https://api.mailpro.com/sms/send/add_single.json" \
  -d "id_client=YOUR_ID&api_key=YOUR_API_KEY" \
  -d "to=+34612345678" \
  -d "message=Tu backup Mailpro se completó con éxito a las 03:04 UTC."

Para la misma llamada en una veintena de lenguajes más (PHP, Go, Ruby, C#, Java, Swift…), consulta la referencia SMS — cada endpoint trae el snippet equivalente.

Próximamente: Verify/OTP y Phone Lookup

Dos features de la roadmap de la API SMS son particularmente útiles para integraciones de agentes de IA:

Endpoint Verify / OTP

En lugar de construir tu propio flujo OTP (generar código, guardar, enviar, verificar), los próximos endpoints /verify/start y /verify/check hacen todo: generación del código, hash, rate limits, plantillas multilingüe, conteo de intentos. El agente solo llama /verify/start y luego /verify/check.

HLR Phone Lookup

El próximo endpoint /phone/lookup devolverá en tiempo real info de la operadora (mobile / fijo / voip), portabilidad (MNP) y alcanzabilidad. Esencial para limpiar listas de leads antes de una campaña SMS — no tiene sentido enviar a un número desconectado.

Ambas usarán el mismo modelo de auth, quedando inmediatamente consumibles por un agente de IA.

Consejos y trampas

Respuestas en PascalCase (como v2 email)

La API SMS Mailpro™ devuelve Result, IdSend, RemainingCredits — PascalCase. Concuerda con v2 email, difiere de v3 CRM (snake_case). A precisar en el prompt del sistema.

Manejo de STOP y supresión de números

Los usuarios pueden responder STOP para darse de baja. Hoy nuestro gateway lo gestiona y bloquea los envíos futuros automáticamente. El próximo endpoint /suppressions expondrá la lista de supresiones como recurso de API — para auditoría y gestión manual.

GDPR/LGPD y consentimiento

Ten siempre consentimiento explícito antes de enviar SMS de marketing. Para SMS transaccional (OTP, alertas disparadas por acción del usuario), el consentimiento es implícito. El agente no debe decidir si un usuario está opt-in — es una decisión legal, no de prompt.

Caso de estudio (ficticio): "VeloCorreo" — reparto en bici en Madrid con SMS de ETA guiados por IA

VeloCorreo reparte comida y paquetes en Madrid. Históricamente el cliente recibía un SMS "tu repartidor va en camino" en el pickup, y listo. El equipo conectó a Claude detrás del sistema de dispatch: cuando el GPS del repartidor mostraba menos de 500 m del punto de entrega, el agente lanzaba un SMS Mailpro™ con un mensaje a medida según el tipo de pedido ("Tu café llega en 2 minutos — por favor, espera en la puerta"). El NPS en la etapa de llegada subió 18 puntos. El volumen de SMS creció 30%, manteniéndose muy por debajo del ahorro en llamadas al soporte. El equipo de dispatch monitorea los mensajes enviados por el agente en el histórico Mailpro™; de vez en cuando ajusta el prompt cuando el tono no es el adecuado.

Pṟoximo paso

El SMS es el último gran canal del stack Mailpro™. Si aún no leíste la guía pilar sobre agentes de IA y Mailpro, empieza por ahí para la vista completa. Para las guías de email, ver Email transaccional v2 y CRM v3.

Referencia: API SMS Mailpro. Precios: precios Mailpro.

FAQ

¿Un agente de IA puede enviar OTPs vía Mailpro?

Hoy sí, de manera artesanal: generar código de 6 dígitos, guardarlo con caducidad, enviar vía /send/add_single.json. Muy pronto un endpoint dedicado /verify/start + /verify/check hará todo en una sola llamada. Ver roadmap de la API SMS.

¿Cuánto cuesta un SMS?

Depende del país de destino. Ver precios para la tarifa actual.

¿La API soporta números internacionales?

Sí, Mailpro™ envía a 200+ países. Usa el formato E.164 (+<prefijo><número>, p. ej. +34612345678) o el prefijo 00 equivalente — la API acepta los dos.

¿Cómo bloqueo un número que respondió STOP?

Hoy es automático a nivel de gateway. El próximo endpoint /suppressions permitirá listar, añadir y quitar números suprimidos vía API — útil para sincronizar con tu propia base de preferencias.