¿Qué hace AgenticEmail: correo electrónico para agentes de IA?
AgenticEmail proporciona a un agente una bandeja de entrada de correo electrónico real y direccionable que posee. A diferencia de una API de solo envío, cada bandeja de entrada envía y recibe: el correo entrante llega como JSON analizado a través de un webhook o una transmisión WebSocket. Úsalo siempre que un agente necesite ser contactable en una dirección de correo electrónico, no solo poder enviar.
Desencadenantes comunes: el agente debe registrarse en un servicio de terceros, recibir un código de verificación u OTP, ser notificado por correo electrónico, ejecutar un flujo de soporte o alcance, o intercambiar correos con un humano u otro agente.
Configuración
- Obtén una clave API (comienza con
am_) en https://app.agenticemail.dev. El nivel gratuito incluye bandejas de entrada reales, envío, recepción y webhooks. - Expórtala:
export AGENTICEMAIL_API_KEY=am_... - Elige una ruta de integración a continuación. Todas llaman a
https://api.agenticemail.dev.
Elige una ruta
- Servidor MCP alojado (recomendado para agentes con capacidad MCP como Claude, Cursor y el SDK de IA de Vercel). Conecta
https://api.agenticemail.dev/mcpcon la clave API como token Bearer. El agente obtiene estas herramientas directamente:create_inbox,list_inboxes,list_threads,get_thread,list_messages,get_message,send_message,reply_to_message. - CLI (
npm i -g agenticemail-cli), para agentes impulsados por shell. - SDK (
npm i agenticemailpara TypeScript, opip install 'agenticemail[e2e]'para Python), para código.
Configuración del cliente MCP
Clientes nativos HTTP (Claude, Cursor y otros que hablen HTTP transmisible):
{
"mcpServers": {
"agenticemail": {
"type": "http",
"url": "https://api.agenticemail.dev/mcp",
"headers": { "Authorization": "Bearer ${AGENTICEMAIL_API_KEY}" }
}
}
}
Cliente solo Stdio, conéctalo:
npx mcp-remote https://api.agenticemail.dev/mcp \
--header "Authorization: Bearer $AGENTICEMAIL_API_KEY"
Flujo básico: crear, enviar, recibir, responder
CLI:
INBOX=$(agenticemail inboxes create --username assistant | jq -r .id)
agenticemail messages send "$INBOX" --to [email protected] \
--subject "Hola" --text "Enviado por un agente."
agenticemail messages list "$INBOX" --limit 5
agenticemail messages reply "$INBOX" <msgId> --text "En ello."
agenticemail wait-for-message "$INBOX" --timeout 300
SDK de TypeScript:
import { AgenticEmail } from "agenticemail";
const client = new AgenticEmail({ apiKey: process.env.AGENTICEMAIL_API_KEY! });
const inbox = await client.inboxes.create({ username: "assistant" });
await client.messages.send(inbox.id, {
to: ["[email protected]"],
subject: "Hola",
text: "Enviado por un agente.",
});
const { data } = await client.messages.list(inbox.id, { limit: 5 });
const msg = await client.messages.get(inbox.id, data[0].id);
await client.messages.reply(inbox.id, msg.id, { text: "Gracias." });
SDK de Python:
from agenticemail import AgenticEmail
client = AgenticEmail(api_key=os.environ["AGENTICEMAIL_API_KEY"])
inbox = client.inboxes.create(username="assistant")
client.messages.send(inbox.id, to=["[email protected]"], subject="Hola", text="...")
for m in client.messages.list(inbox.id, limit=5).data:
print(m.subject)
REST (si no usas un SDK)
URL base https://api.agenticemail.dev, encabezado Authorization: Bearer $AGENTICEMAIL_API_KEY.
| Método | Ruta | Propósito |
|---|---|---|
| POST | /v1/inboxes | Crear una bandeja de entrada. Cuerpo { "username": "assistant" } (opcional). |
| GET | /v1/inboxes | Listar bandejas de entrada. |
| POST | /v1/inboxes/{id}/messages | Enviar. Cuerpo { "to": ["[email protected]"], "subject": "...", "text": "..." }. |
| GET | /v1/inboxes/{id}/messages | Listar. Consulta limit, cursor. |
| GET | /v1/inboxes/{id}/messages/{msgId} | Obtener un mensaje analizado. |
| POST | /v1/inboxes/{id}/messages/{msgId}/reply | Responder en el hilo. |
| POST | /v1/webhooks | Registrar un webhook. Cuerpo { "url": "...", "eventTypes": ["message.received"] }. |
Cada objeto de mensaje tiene un booleano encrypted para que un cliente sepa si debe descifrar.
Recibir correo entrante
Registra un webhook para que el correo nuevo llegue al agente en el momento en que llega:
agenticemail webhooks create --url https://tu-app/hook \
--event-types message.received
Cada evento lleva el remitente, asunto, texto, HTML y archivos adjuntos analizados. También hay disponible una transmisión WebSocket para los mismos eventos si el agente ya está en ejecución (agenticemail events tail).
Cifrado de extremo a extremo (opcional)
Para correo entre agentes, AgenticEmail ofrece cifrado de extremo a extremo opcional: la clave privada se genera y mantiene en el cliente (SDK o CLI), nunca en el servidor, por lo que la plataforma no puede leer el contenido. Actívalo en la CLI con agenticemail keys generate <inbox> y luego agenticemail keys publish <inbox>, después de lo cual messages send y messages get cifran y descifran automáticamente. En el SDK, pasa una identidad e2e al construir el cliente:
import { AgenticEmail, generateIdentity } from "agenticemail";
const client = new AgenticEmail({
apiKey: process.env.AGENTICEMAIL_API_KEY!,
e2e: { identity: generateIdentity(), autoPublish: true },
});
Qué cubre y qué no, explicado honestamente:
- Es opcional y funciona solo entre dos bandejas de entrada de AgenticEmail que hayan publicado cada una una clave. El texto plano es el valor predeterminado.
- La clave privada está solo en el lado del cliente y nunca llega al servidor, por lo que ni la plataforma ni su proveedor de nube pueden leer el contenido cifrado.
- Un envío a una dirección externa (Gmail, un servidor corporativo) vuelve al texto plano, porque no hay una clave publicada para cifrar.
- Los metadatos de enrutamiento (De, Para, tiempo, tamaño) permanecen visibles, como exige SMTP.
- Pierde la clave privada y los correos cifrados antiguos serán irrecuperables. Ese es el costo de que el servidor nunca la tenga.
Documentación
Documentación completa: https://agenticemail.dev/docs