Configuración del cliente de correo mediante API y MCP

TrekMail ofrece mediante REST y MCP los mismos datos de conexión de Aplicaciones 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 ni las credenciales de un proveedor SMTP personalizado. El usuario introduce la contraseña directamente en su aplicación de correo. 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 Aplicaciones 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, el espacio de nombres configurado y una entrada items[] por cada buzón compartido delegado a este buzón normal;
• password_included: false como garantía explícita de seguridad.

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 Puede responder 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 propias de ese miembro. No crees una segunda cuenta ni intentes autenticarte directamente con la dirección compartida.

Cuando el acceso nativo está desactivado, shared_mailboxes.native_access_enabled es false e items está vacío. Si está activado pero items está vacío, el buzón normal no tiene actualmente ninguna membresía activa en buzones compartidos. En ninguno de los casos se incluye contraseña alguna del buzón compartido o del miembro.

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 al usuario la contraseña del buzón durante la instalación. TrekMail devuelve 409 mail_client_setup_not_ready en lugar de generar un perfil engañoso mientras el correo saliente no está disponible.

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.