Configurar apps de correo mediante API y MCP

TrekMail ofrece mediante REST y MCP los mismos datos de conexión de Apps y dispositivos que utiliza el panel. Ambas interfaces son de solo lectura y requieren acceso de lectura al buzón.

Nunca devuelven la contraseña del buzón, una contraseña de aplicación ni las credenciales de un proveedor SMTP personalizado. El usuario introduce una contraseña de aplicación directamente en su app de correo, o la contraseña del buzón si este aún la acepta. Aunque un dominio envíe los mensajes salientes mediante un proveedor personalizado, las aplicaciones externas los entregan al endpoint SMTP público de TrekMail; TrekMail aplica internamente la ruta privada del dominio.

Obtener los ajustes de conexión

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

Alcance interno necesario: mailboxes:read. Se aplican las restricciones opcionales domain_ids y mailbox_ids del token.

La respuesta contiene:

• host IMAP entrante, puerto SSL, nombre de usuario y estado de disponibilidad;
• host SMTP saliente, puerto SSL, nombre de usuario y estado de disponibilidad;
• URL del servidor DAV para calendarios y contactos, su estado de conexión y si la dirección devuelta incluye la marca;
• las mismas guías localizadas de tres pasos para Gmail, Outlook, Apple Mail, Thunderbird e IMAP genérico que aparecen en Apps y dispositivos;
• sending.mode: platform, profile o not_configured;
• sending.reason: un motivo estable y legible por máquinas cuando el correo saliente no está listo;
• apple_mail_profile.available, que solo es true cuando la recepción y el envío están listos;
• shared_mailboxes.native_access_enabled, namespace, items[];
• authentication.client_auth_mode: app_password_only o password_or_app_password;
• authentication.accepted_passwords: ["app_password"] o ["mailbox_password", "app_password"], respectivamente;
• authentication.app_passwords_endpoint: el endpoint de gestión de contraseñas de aplicación del buzón;
• password_included: false como garantía explícita de seguridad.

shared_mailboxes.items[] solo incluye miembros con el permiso Leer cuando el acceso nativo a carpetas está habilitado. delegated_send_addresses es una lista aparte de direcciones del equipo disponibles en el campo De con id, email y display_name; puede estar vacía. No da acceso a carpetas ni comprueba que se pueda enviar. Estas direcciones no son identidades de la Message API. Usa los servidores devueltos, también en White Label, en vez de copiar el servidor de la plataforma.

Cada elemento de buzón compartido delegado contiene valores duraderos native_access_status/native_access_ready, rutas estándar exactas en folders, valores operations impuestos por el servidor y valores efectivos send_as_ready/send_as_reason. can_send sigue representando el permiso Enviar como asignado por el administrador; puede ser true aunque SMTP no esté disponible, por lo que la automatización debe comprobar ambos campos de disponibilidad. Si el buzón miembro está inactivo, tiene el inicio de sesión suspendido o el acceso directo desactivado, el buzón compartido sigue apareciendo, pero su motivo de Enviar como será mailbox_unavailable, mailbox_login_suspended o direct_login_unavailable. El campo heredado folder conserva la ruta exacta de la bandeja de entrada. Espera a native_access_ready=true antes de guiar al usuario durante la configuración.

SMTP transporta una respuesta o un reenvío, pero no guarda su copia en Enviados. Por eso, sent_copy.smtp_saves_copy es false; configura el cliente para que añada la copia a sent_copy.folder (el mismo valor que folders.sent) y todo el equipo pueda verla. folders.archive y folders.junk son destinos exactos cuando un cliente no asigna automáticamente Archivo o Spam. Mover un mensaje a Correo no deseado no garantiza por sí solo el entrenamiento del clasificador de spam del servidor.

Solicita siempre este endpoint con el ID del buzón miembro normal y autentica el cliente con la dirección y contraseña de aplicación propias de ese miembro, o la contraseña del buzón si se acepta. No crees una segunda cuenta ni intentes autenticarte directamente con la dirección compartida.

La lista de carpetas shared_mailboxes describe el acceso nativo de quienes pueden leer el buzón. Si items está vacío, comprueba el acceso nativo y Leer. Una lista vacía no demuestra que se haya retirado todo acceso a direcciones compartidas. No se devuelve ninguna contraseña.

El parámetro opcional lang acepta los mismos 13 idiomas que el endpoint del perfil de Apple. Si se omite, TrekMail utiliza Accept-Language y después la configuración regional predeterminada. Cada guía tiene un id estable, tres steps localizados y una action: use_server_settings o download_apple_profile.

connection_status=receiving_only no indica una configuración completa correcta. Configura o restaura la ruta saliente del dominio antes de indicar al usuario que conecte un cliente que valide ambos servidores.

connection_status=unavailable significa que el ciclo de vida del buzón ha cambiado y ya no puede autenticarse directamente. No utilices las coordenadas del servidor devueltas ni ofrezcas un perfil de Apple Mail; actualiza primero el estado del buzón.

Descargar un perfil de Apple Mail

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

La respuesta es un archivo adjunto .mobileconfig. Los valores de lang admitidos son en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar y he. Si se omite lang, TrekMail utiliza Accept-Language y después la configuración regional predeterminada.

El perfil contiene los ajustes IMAP y SMTP, pero ningún campo de contraseña. Apple solicita una contraseña durante la instalación: usa una contraseña de aplicación para app_password_only, o cualquiera de las dos contraseñas aceptadas para password_or_app_password. TrekMail devuelve 409 mail_client_setup_not_ready en lugar de generar un perfil engañoso mientras el correo saliente no está disponible.

Crea una contraseña de aplicación en el webmail, en Configuración, Contraseñas de aplicación, o en el panel, en Buzones, (buzón), Seguridad, Contraseñas de aplicación. El endpoint de configuración de solo lectura no crea ninguna. Para los endpoints REST y las herramientas MCP que gestionan estas contraseñas y el modo de inicio de sesión, consulta Contraseñas de aplicación por API y MCP.

Herramientas MCP

Las herramientas utilizan los mismos endpoints REST y reglas de autorización:

Los transportes MCP devuelven contenido estructurado de herramientas, no una descarga del navegador. Decodifica content_base64 como bytes y guárdalo con file_name; no lo interpretes como JSON o UTF-8 antes de decodificarlo.

Ambas herramientas requieren el alcance OAuth alojado mail:read, que se amplía al alcance interno mailboxes:read. Son de solo lectura y no dependen de ninguna variable de entorno de operaciones destructivas en el servidor stdio autoalojado.

Errores

El endpoint de configuración puede devolver estos valores de sending.reason: mailbox_unavailable, direct_login_unavailable, domain_unavailable, domain_deprovisioning, account_suspended, email_verification_required, mailbox_sending_disabled, smtp_not_configured, managed_smtp_not_in_plan, managed_smtp_entitlement_inactive, smtp_profile_unavailable o smtp_route_invalid.