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

Si ya leíste nuestra guía sobre agentes de IA y las API de Mailpro™, conoces el esquema: el modelo decide, tu código envía. Este artículo se centra en una sola API, la Email API v2 de Mailpro™, y presenta una configuración funcional para emails transaccionales y de campaña gestionados por Claude, GPT o cualquier LLM compatible con tool calling, con los endpoints y parámetros exactos.

En resumen

• URL base https://api.mailpro.com/v2, respuestas en JSON, token bearer OAuth 2.0 (o el método heredado IdClient + ApiKey).
• Un email a una persona: POST /send/sendmail.json. Una plantilla guardada a toda una lista: POST /send/campaign.json.
• Sigue cada email transaccional con GET /send/{IdSingleSend}/status.json o con los webhooks email.delivered / email.bounced.
• Importa contactos en bloque desde un agente con POST /import/upload.json (CSV o XLSX, hasta 50 MB).

Email gestionado por IA: ¿qué casos de uso valen la pena?

Confirmaciones de pedido inteligentes

Una confirmación estándar es una plantilla. Un agente puede añadir una nota personal ("Gracias por elegir la Blue XL, la favorita de nuestros clientes") y recomendaciones pertinentes, y luego enviarla a través de la API. Conservas la fiabilidad de una plantilla estructurada con la calidez de una nota escrita a mano.

Clasificación automática del soporte

Cuando llega un ticket, el agente lo clasifica, redacta una respuesta y, si tiene suficiente confianza y el tema figura en una lista aprobada, la envía. Todo lo demás pasa a una persona con el borrador adjunto.

Resúmenes en lugar de avalanchas

El agente lee los eventos del día (facturas, altas, alertas) y envía un único resumen a las 18:00: "Hoy: 12 pagadas, 3 vencidas, 2 por revisar." Un solo email, sin ruido. La API se encarga de la entrega; el modelo, de la síntesis.

¿Cómo se configura la Email API v2 en 5 minutos?

1. Obtén las credenciales

En tu cuenta de Mailpro™, ve a Settings → API access. Para un agente, crea un cliente OAuth y solicita solo los scopes que necesita, normalmente email:send y email:read. Los identificadores heredados IdClient (numérico) y ApiKey (GUID) también funcionan, pero no están limitados por scopes, así que resérvalos para tus propios scripts de back-end.

2. Comprueba la conexión

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.mailpro.com/v2/account/credits.json

Deberías recibir tus créditos de email restantes en JSON. Un 401 significa que el token o la clave son incorrectos; un 403 insufficient_scope indica que al token le falta account:read.

3. Encuentra tu ID de remitente

Los emails se envían desde una dirección de remitente validada. GET /senderEmail/list.json las devuelve con sus ID; ese ID es el que pasarás como IDEmailExp.

Paso a paso: haz que Claude envíe un email transaccional

El ejemplo utiliza Claude de Anthropic, pero el mismo esquema funciona con el function calling de OpenAI o el tool use de Gemini: cambia el SDK, no la arquitectura.

1. Define la herramienta

tools = [{
  "name": "send_transactional_email",
  "description": "Envía un email a un cliente a través de Mailpro.",
  "input_schema": {
    "type": "object",
    "properties": {
      "to":      {"type": "string"},
      "subject": {"type": "string"},
      "html":    {"type": "string", "description": "Cuerpo HTML completo"}
    },
    "required": ["to", "subject", "html"]
  }
}]

2. Escribe el prompt del sistema

Ayudas a los agentes de atención al cliente a redactar y enviar emails de seguimiento.
Llama a send_transactional_email solo después de que la persona lo confirme.
Sé conciso y cordial, e incluye siempre un enlace con una llamada a la acción clara.

3. Ejecuta la llamada a /send/sendmail

import requests

def send_transactional_email(args, token, sender_id):
    r = requests.post(
        "https://api.mailpro.com/v2/send/sendmail.json",
        headers={"Authorization": f"Bearer {token}"},
        data={
            "IDEmailExp": sender_id,       # de /senderEmail/list
            "EmailData":  args["to"],      # email,campo1,campo2...
            "Subject":    args["subject"],
            "BodyHTML":   args["html"],
            "ActivateStatistics": "true",  # seguimiento de aperturas y clics
        },
    )
    r.raise_for_status()
    return r.json()   # {"SingleSend": {"IdSingleSend": 8001, ...}}

Campos opcionales útiles: DatePlanned (ISO 8601) para programar el envío en lugar de enviarlo ya, ReplyTo, BodyText para una versión en texto plano y attachments. Devuelve el JSON al modelo como resultado de la herramienta para que pueda decirle al usuario que el email va en camino.

¿Estás conectando envíos transaccionales? Los emails automáticos de Mailpro se disparan al instante con cada evento — recibos, confirmaciones, alertas — con una entrega en la que puedes confiar.

4. Confirma la entrega

GET /send/8001/status.json devuelve delivered, bounced (con BounceType y el DiagCode del servidor), deferred, sent, scheduled o queued. Cuenta con obtener delivered unos cinco minutos después de la entrega al servidor. Para recibir información en tiempo real, suscríbete a los webhooks email.delivered y email.bounced en lugar de consultar el estado una y otra vez.

Campañas: que el agente prepare y una persona pulse enviar

Para un envío a toda una lista, el agente trabaja con una plantilla guardada en lugar de HTML en bruto:

curl -X POST https://api.mailpro.com/v2/send/campaign.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d "IDMessage=55" \
  -d "IDEmailExp=201" \
  -d "ListId=101" \
  -d "Campaign=1" \
  -d "TitleCampaign=April newsletter" \
  -d "DatePlanned=2026-05-01T09:00:00"

DatePlanned es opcional: si lo omites, la campaña sale de inmediato. Un buen esquema consiste en dejar que el agente elija la lista, la plantilla y una hora de envío según la zona horaria de la audiencia, y luego mostrar el plan a una persona que lo apruebe. Las campañas programadas todavía pueden moverse con PATCH /send/{IdSend}/reschedule.json o cancelarse con POST /send/{IdSend}/cancel.json.

Personalización con campos

En /send/sendmail, EmailData recibe la dirección seguida de hasta 25 valores ([email protected],Alice,Dupont,Paris) que rellenan los campos de personalización de la plantilla. En las campañas, los campos proceden de los datos de cada contacto en la lista. El agente solo tiene que colocar el campo en su HTML; la API lo rellena para cada destinatario.

Importa contactos en bloque a partir de un archivo subido por un agente

Cuando el primer paso de un flujo de trabajo es "añade estos 500 nuevos leads", no hagas 500 llamadas a la API. Envía un solo archivo:

curl -X POST https://api.mailpro.com/v2/import/upload.json \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F "ListId=42" \
  -F "[email protected]" \
  -F "WebhookUrl=https://example.com/hooks/import-done"

El archivo debe estar en UTF-8 con una fila de encabezado que incluya Email; las demás columnas se asignan a los campos personalizados de la lista. El endpoint devuelve un ImportJobId de inmediato, procesa el archivo en segundo plano y llama a tu WebhookUrl con el número de filas importadas, omitidas y no válidas.

Errores frecuentes y consejos

• Las direcciones dadas de baja se rechazan. La API responde "Email address unsubscribed." con un 400. Indica al agente que es definitivo, no un error que deba reintentar.
• Vigila los créditos. "Not enough credit available." llega como un 403. Suscríbete al webhook credits.low para que una persona recargue antes de que el agente se tope con el límite.
• Ten en cuenta la cuota de peticiones. Las llamadas a la API cuentan para una cuota mensual compartida por las API de Email, CRM y SMS (GET /account/limits.json). Limita las llamadas a herramientas por conversación y espera antes de reintentar cuando recibas un 429.
• Quédate con JSON. XML es compatible con el sufijo .xml, pero JSON es más sencillo para la salida de herramientas de un LLM.
• Autentica tu dominio. Los emails personalizados escritos por IA siguen necesitando SPF, DKIM y DMARC para llegar a la bandeja de entrada; consulta nuestra guía para resolver problemas de entregabilidad.

Caso práctico (ficticio): "NovaFit", una red de gimnasios con recordatorios de clase escritos por IA

NovaFit gestiona 40 gimnasios y envía un recordatorio 24 horas antes de cada clase reservada. Antes, los recordatorios eran una única plantilla ("Hola, Anna: tu clase de yoga es mañana a las 7:00"). El equipo conectó Claude al sistema de reservas: para cada recordatorio, el agente lee la asistencia reciente del socio y el tipo de clase, escribe una línea personal ("La semana pasada aguantaste la postura del guerrero un minuto entero, ¿lista para el siguiente nivel?") y envía el email con /send/sendmail. Los rebotes llegan a través del webhook email.bounced y se señalan a recepción. La tasa de apertura de los recordatorios pasó del 46 % al 63 % y la asistencia subió 8 puntos, sin cambios en el volumen de emails.

Próximos pasos

La Email API v2 se encarga del envío. Si tu agente también necesita gestionar contactos, etiquetas, segmentos y campos personalizados, lee nuestra guía de la CRM API v3 para IA. Para los mensajes de texto, consulta cómo enviar SMS con un agente de IA. ¿Dudas entre una plataforma gestionada y un servicio de envío en bruto? Consulta nuestra guía de las mejores alternativas a Amazon SES. Referencia completa: la documentación de la Email API v2.