Cuentas conectadas mediante API y MCP

Las cuentas conectadas permiten que un buzón de correo web lea y envíe mensajes desde buzones externos, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 o cualquier servidor IMAP. La API de mensajes y las herramientas MCP ofrecen la misma capacidad de forma programática: puedes listar, añadir, probar, editar y eliminar cuentas conectadas, además de dirigir las llamadas habituales de mensajes (listar, leer, enviar, marcas, mover, eliminar y carpetas) a una cuenta conectada en lugar del buzón propio del token.

En pocas palabras: mailbox_id elige el buzón de TrekMail en cuyo nombre puede actuar el agente, mientras que external_account_id elige Gmail u otro buzón conectado dentro de él. No son intercambiables.

Planes, límites y tamaño del catálogo

La gestión de cuentas conectadas ofrece siete herramientas de mensajes. Un token con ámbitos limitados solo ve las herramientas que realmente puede usar, no el catálogo completo del producto.

Antes de empezar

• Las cuentas conectadas son una función de correo web y usan la superficie del token de mensajes (/api/v1/messages/...), autorizada por un token de mensajes con los ámbitos indicados abajo, no por un token de la API del panel.
• Los límites del plan se aplican por buzón: Starter 5, Pro 10, Agency 30. El plan Nano no incluye cuentas conectadas.
• Cada endpoint está limitado al buzón propio del token. Un token solo puede ver y gestionar sus propias cuentas conectadas, nunca las de otro buzón.
• Las credenciales y los tokens OAuth siempre aparecen enmascarados en las respuestas. Puedes escribir una contraseña o contraseña de aplicación, pero nunca volver a leerla.
• Las cuentas de Outlook.com y Microsoft 365 se conectan mediante el inicio de sesión de Microsoft (OAuth) en la interfaz de correo web. La API puede gestionarlas y usarlas después de conectarlas, pero no realiza el paso interactivo de consentimiento de Microsoft.

Ámbitos

Dirigir una llamada de mensajes a una cuenta conectada requiere el mismo ámbito que ya necesita esa llamada (por ejemplo, listar sus mensajes requiere messages:read; enviarlos requiere messages:send).

Gestionar cuentas conectadas

Ruta base: /api/v1/messages/external-accounts

Añadir una cuenta

POST /api/v1/messages/external-accounts
Scope: messages:write

Cuerpo de la solicitud:

Llama primero a POST /external-accounts/detect para completar automáticamente provider y la configuración del servidor. La llamada de almacenamiento ejecuta una prueba IMAP + SMTP real antes de guardar; un 422 con una categoría de error (auth, tls, network, transient_throttle) significa que las credenciales no funcionaron y no se almacenó nada.

Dirigir llamadas de mensajes a una cuenta conectada

Cada endpoint de mensajes que opera sobre un buzón acepta un external_account_id opcional. Indícalo para ejecutar la llamada en esa cuenta conectada en lugar del buzón propio del token; omítelo para usar el propio buzón. Se aplica a listar, leer, enviar, responder, marcar, mover y eliminar mensajes, y a listar carpetas.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

El envío solo con external_account_id se realiza mediante el servidor SMTP propio de esa cuenta (con SPF/DKIM de su proveedor). Si proporcionas en su lugar un identity_id vinculado al origen, se usa el dominio o la ruta del perfil guardado de esa identidad Enviar como, pero se sigue guardando la copia de Enviados en el buzón conectado. La cuenta debe estar operativa (status: active); una cuenta desconectada devuelve un error que solicita volver a conectarla. Consulta Direcciones Enviar como mediante API y MCP.

Herramientas MCP

La misma capacidad está disponible para agentes de IA mediante MCP (tanto en el servidor stdio privado como en el servidor MCP público):

Las herramientas de mensajes, list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all y prepare_forward, aceptan el argumento opcional external_account_id. El envío, la creación de borradores y la programación también aceptan un identity_id vinculado al origen que devuelve list_identities.

Como las herramientas de gestión abren conexiones salientes a servidores de correo arbitrarios con credenciales proporcionadas por el usuario, siguen la misma política de seguridad que el resto de la función de cuentas conectadas: lista de hosts permitidos, bloqueo de rangos privados, lista de puertos permitidos y límites de conexiones por host.