API de Email Entrante: Como Recibir Email Programaticamente para Agentes de IA

Una API de email entrante permite a tu aplicacion recibir email programaticamente. En lugar de consultar un buzon o escanear una bandeja de entrada, los mensajes entrantes se entregan a tu codigo en tiempo real via webhooks. Para agentes de IA que necesitan leer, comprender y responder emails, una API de email entrante es el bloque fundamental que hace posibles los flujos de trabajo de email autonomos.

Esta guia explica como funcionan las APIs de email entrante, como configurar una con AgentSend, y por que el modelo de webhook por buzon es mas adecuado para agentes de IA que los enfoques tradicionales como la consulta IMAP o el parseo de entrada a nivel de dominio.

Que Es una API de Email Entrante?

Una API de email entrante es un servicio que acepta email entrante en tu nombre y lo entrega a tu aplicacion como datos estructurados. El flujo tipico funciona asi: los registros MX dirigen el correo entrante a los servidores del proveedor de la API, el proveedor parsea el email sin procesar en un payload estructurado (remitente, asunto, cuerpo, adjuntos, cabeceras), y luego entrega ese payload a una URL de webhook que tu configuras.

La ventaja clave sobre la recepcion de email tradicional es que tu aplicacion nunca gestiona un servidor de correo. No hay conexion IMAP que mantener, no hay intervalo de consulta POP3 que ajustar, y no hay parseo de MIME sin procesar que implementar. Recibes un payload JSON limpio via HTTP POST, lo procesas y respondes con un codigo de estado 200. Esa es toda la integracion.

Para agentes de IA, esto importa porque los agentes necesitan reaccionar al email entrante en tiempo real. Un agente de soporte al cliente no puede esperar cinco minutos a la siguiente consulta IMAP para descubrir un nuevo ticket. Una API de webhook de email entrega el mensaje en el momento en que llega, permitiendo a tu agente comenzar a procesar inmediatamente.

Como Funciona el Email Entrante en AgentSend

La API de recepcion de email de AgentSend esta construida alrededor de webhooks por buzon. Cuando creas un buzon, puedes configurar una URL de webhook que recibe cada mensaje entrante para ese buzon especifico. Cada buzon esta aislado: no hay una capa de enrutamiento compartida donde necesites inspeccionar las direcciones de los destinatarios y despachar al manejador correcto.

Cada entrega de webhook incluye una firma HMAC en la cabecera X-AgentSend-Signature. Tu aplicacion verifica esta firma usando el secreto de webhook de tu buzon para confirmar que el payload fue enviado por AgentSend y no fue alterado en transito. Si tu endpoint no esta disponible temporalmente, AgentSend reintenta la entrega con retroceso exponencial durante hasta 24 horas.

Configurando el Email Entrante

Comenzar con la API de buzon de email de AgentSend requiere dos pasos: crear un buzon con una URL de webhook, y luego manejar los payloads entrantes.

Paso 1: Crear un Buzon con un Webhook

Usando cURL:

curl -X POST https://api.agentsend.io/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "webhook_url": "https://yourapp.com/webhooks/inbound-email",
    "webhook_secret": "whsec_your_secret_here"
  }'

Usando Python:

import requests

resp = requests.post(
    "https://api.agentsend.io/v1/inboxes",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "support-agent",
        "webhook_url": "https://yourapp.com/webhooks/inbound-email",
        "webhook_secret": "whsec_your_secret_here",
    },
)
inbox = resp.json()
print(inbox["email"])  # support-agent@yourteam.agentsend.io

Paso 2: Manejar el Payload del Webhook

Cuando llega un email, AgentSend envia un payload JSON a tu URL de webhook. Aqui hay un manejador minimo en Python usando Flask:

import hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"

@app.route("/webhooks/inbound-email", methods=["POST"])
def handle_inbound():
    # Verify HMAC signature
    signature = request.headers.get("X-AgentSend-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "invalid signature"}), 401

    payload = request.json
    sender = payload["from"]
    subject = payload["subject"]
    body = payload["body_text"]
    thread_id = payload["thread_id"]

    # Pass to your AI agent for processing
    process_with_agent(sender, subject, body, thread_id)

    return jsonify({"status": "ok"}), 200

API de Email Entrante vs Enfoques Tradicionales

Hay varias formas de recibir email programaticamente. Aqui se comparan los enfoques mas comunes para casos de uso de agentes de IA.

La diferencia critica es el aislamiento. Mailgun y SendGrid operan a nivel de dominio: apuntas los registros MX de tu dominio a sus servidores, y todo el correo entrante para ese dominio llega a un solo endpoint de webhook. Tu eres responsable de inspeccionar la direccion del destinatario en cada payload y enrutarlo al agente correcto. Con AgentSend, cada buzon tiene su propio webhook, su propio secreto de firma y su propio historial de hilos. No hay logica de enrutamiento que construir o mantener.

API de Buzon de Email: Creando Buzones Programaticamente

Uno de los aspectos mas potentes de una API de buzon de email es la capacidad de crear buzones sobre la marcha. Cuando tu plataforma incorpora un nuevo cliente, aprovisiona un nuevo agente de IA o lanza un nuevo flujo de trabajo, puedes crear un buzon dedicado con una sola llamada API. Cada buzon obtiene su propia direccion de email automaticamente: sin configuracion DNS, sin configuracion manual, sin esperar propagacion.

Esto es particularmente util para arquitecturas multi-agente. Un sistema de soporte al cliente podria crear buzones separados para preguntas de facturacion, soporte tecnico y gestion de cuentas. Cada buzon se enruta a un agente especializado con su propio endpoint de webhook y su propio historial de conversacion. Escalar de un agente a cincuenta es un bucle de llamadas API, no un proyecto de migracion DNS.

Casos de Uso para APIs de Email Entrante

Una API de email entrante desbloquea una variedad de flujos de trabajo de agentes autonomos que son dificiles o imposibles de construir con infraestructura de email tradicional.

• Agentes de soporte al cliente — Reciben tickets de soporte via email, clasifican la intencion, resuelven preguntas comunes automaticamente y escalan problemas complejos a agentes humanos con el contexto completo del hilo.
• Agentes de investigacion — Se suscriben a boletines, reciben informes y procesan fuentes de informacion entrantes. El agente lee cada email, extrae datos relevantes y actualiza una base de conocimiento sin intervencion humana.
• Agentes de programacion — Reciben solicitudes de reuniones y respuestas de disponibilidad via email. El agente analiza el contenido, verifica calendarios y envia respuestas de confirmacion, todo a traves de su propia direccion de email dedicada.
• Agentes con enfoque de salida y manejo de respuestas — Los agentes que envian correos de prospeccion, secuencias de seguimiento o notificaciones pueden recibir y procesar respuestas a traves del mismo buzon, manteniendo el contexto completo de la conversacion.

En cada caso, la API de email entrante elimina la carga de infraestructura. Tu codigo de agente se enfoca en comprender y responder mensajes, no en mantener conexiones IMAP, parsear MIME o enrutar emails al manejador correcto.