API de emails transaccionales para agentes de IA: guía Mailpro™ v2

Si leíste nuestra guía pilar sobre agentes de IA y la API Mailpro™, ya sabes por qué conectar un agente de IA a una API de email es el camino más corto entre "chatbot" y "colega digital". Este artículo profundiza en una API específica — la Mailpro™ Email API v2 — con un setup funcional tanto para envíos transaccionales como para campañas, pilotados por Claude, GPT o cualquier LLM con tool calling.

En resumen

• La Mailpro™ Email API v2 acepta IdClient + ApiKey por HTTPS — sin SDK.
• Los dos endpoints más usados son /send/sendmail.json (transaccional) y /send/campaign.json (bulk).
• Cualquier LLM con tool calling puede operar la API mediante un wrapper mínimo.
• Cada endpoint está documentado en 20+ lenguajes en nuestro portal para desarrolladores.

Email guiado por IA: los casos de uso que importan

Confirmaciones de pedido inteligentes

Las confirmaciones estándar tienen forma de plantilla. Tu agente de IA puede ir más allá: puede escribir una nota personal ("Gracias por elegir el XL Azul, favorito entre nuestros clientes") y adjuntar recomendaciones dinámicas, y luego llamar a la API de email para despachar todo. Mantienes la fiabilidad de la plantilla y ganas la calidez de una nota humana.

Triaje automático de soporte

Cuando llega un ticket, el agente lo clasifica, redacta una respuesta y — si la confianza es alta — la envía directamente. Los tickets de baja confianza van a un humano. Este modelo híbrido es exactamente lo que los equipos de soporte en producción están desplegando hoy.

Generación de digests

A escala, los ejecutivos quieren resúmenes, no mareas. Un agente lee 40 facturas al día y emite un digest a las 18h: "Hoy: 12 pagadas, 3 vencidas, 2 para revisar". Un email, cero ruido. La API Email Mailpro™ se encarga de la entrega; el LLM, de la síntesis.

Setup en 5 minutos

1. Obtener tu IdClient y ApiKey

Ambos se ven en tu cuenta Mailpro™ en Configuración → Acceso a la API. IdClient es un ID numérico; ApiKey es un GUID. Mantén la clave en secreto — trátala como una contraseña.

2. Comprobar con /account/credits.json

Antes de enchufar Claude, verifica que tus credenciales funcionan:

curl "https://api.mailpro.com/v2/account/credits.json?IdClient=YOUR_ID&ApiKey=YOUR_API_KEY"

Debes recibir un JSON con tus créditos de email restantes. En 401, revisa la clave. En 500, consulta nuestra página de estado.

3. Explorar la referencia completa

Cada endpoint está documentado — con la forma de la solicitud / respuesta y un panel "probar ahora" — en la referencia API Email v2. Ábrela en una segunda pestaña y tenla a mano.

Paso a paso: Claude envía un email transaccional

Usamos Claude de Anthropic para este ejemplo, pero el mismo patrón funciona con function calling de OpenAI o tool use de Gemini — cambia el SDK, la arquitectura no.

1. Definir el esquema de la herramienta

tools = [{
    "name": "send_transactional_email",
    "description": "Envía un email puntual a un único destinatario vía Mailpro.",
    "input_schema": {
        "type": "object",
        "properties": {
            "to":      {"type": "string", "format": "email"},
            "subject": {"type": "string"},
            "html":    {"type": "string", "description": "Cuerpo HTML completo"},
            "from":    {"type": "string", "description": "Dirección de remitente validada"}
        },
        "required": ["to", "subject", "html", "from"]
    }
}]

2. Escribir el prompt del sistema

¿Configurando envíos transaccionales? Los emails automáticos de Mailpro se disparan al instante en cada evento — recibos, confirmaciones, alertas — con una entrega fiable.

Eres un asistente que ayuda a agentes de customer success a redactar y
enviar emails de seguimiento. Cuando el humano confirme, usa la
herramienta `send_transactional_email`. Sé conciso, cordial, e incluye
siempre un enlace call-to-action claro.

3. Procesar la llamada y pegarle a /send/sendmail.json

import requests, json, anthropic

def execute_tool(name, args):
    if name != "send_transactional_email":
        return {"error": "herramienta desconocida"}
    r = requests.po directamente. Usa [FirstName], [LastName] y otros placeholders Mailpro™ para personalización por contacto — la API los resuelve al momento del envío con los datos de tu lista.
    

Lanzar la campaña con /send/campaign.json

curl -X POST "https://api.mailpro.com/v2/send/campaign.json" \
  -d "IdClient=YOUR_ID&ApiKey=YOUR_API_KEY" \
  -d "AddressBookId=42" \
  -d "IDMessage=9001" \
  -d "PlanDate=2026-05-01T09:00:00"

PlanDate es opcional — omítelo y la campaña sale al instante. Inclúyelo y Mailpro™ programa el envío por ti. Buen patrón: deja al agente elegir PlanDate según la zona horaria del destinatario.

Personalización con placeholders

Placeholders como [FirstName] y [LastName] son estándar; los campos personalizados ([Field1], [Field2]…) mapean las columnas custom de tu lista en el orden en que las definiste. El agente no necesita conocer los valores — referencia el placeholder en el HTML generado, la API rellena por destinatario.

Importar contactos en masa desde el upload del agente

Cuando la primera acción del agente es "añade 500 leads nuevos", no quieres 500 llamadas individuales. Usa el endpoint /import/upload.json que agregamos recientemente:

curl -X POST "https://api.mailpro.com/v2/import/upload.json" \
  -F "IdClient=YOUR_ID" \
  -F "ApiKey=YOUR_API_KEY" \
  -F "AddressBookId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

El endpoint encola el archivo y devuelve un ImportJobId

Para la misma llamada en una veintena de lenguajes más (PHP, Go, Ruby, C#, Java, Swift…), abre la referencia de la API Email v2 — cada endpoint incluye el snippet equivalente listo para copiar.

Trampas y consejos

• Campos de respuesta en PascalCase. v2 devuelve Result, IDSend, RemainingCredits (no camelCase). Si el agente parsea respuestas, indícalo en el prompt del sistema — si no, alucinará result y idSend.
• Las direcciones dadas de baja se descartan silenciosamente. Usa Force=1 en /email/add solo con consentimiento explícito: salta la verificación opt-out, con riesgo GDPR/LGPD en caso contrario.
• Rate limit: 500 solicitudes/minuto por clave. Agrupa contactos en /email/add (bulk) en vez de una /email/addSingle por contacto.
• Quédate con JSON. XML es compatible (sufijo .xml), pero JSON se parsea más rápido y va mejor con la salida de tool call de LLMs.

Caso de estudio (ficticio): "NovaFit" — cadena de gimnasios con recordatorios de clase personalizados por IA

NovaFit opera 40 gimnasios y envía emails de recordatorio 24 horas antes de cada reserva. Históricamente los recordatorios eran plantilla ("Hola {primer nombre}, tu clase de yoga es mañana a las 7 AM"). El equipo de growth conectó a Claude detrás del sistema de r