Contraseñas de aplicación por API y MCP

La API REST y MCP permiten enumerar, crear, sustituir y revocar las contraseñas de aplicación de un buzón normal, cambiar su modo de inicio de sesión de apps de correo y definir el ajuste predeterminado de la cuenta para los futuros buzones. Esta página es la referencia para integraciones. Para las instrucciones del panel y el webmail, consulta Contraseñas de aplicación para tus dispositivos.

Una contraseña de aplicación permite acceder a IMAP, SMTP en los puertos 465 y 587, ManageSieve y CalDAV/CardDAV. Nunca abre el nuevo webmail ni el panel. El webmail clásico inicia sesión por IMAP y acepta contraseñas de aplicación. La 2FA del buzón protege solo el inicio de sesión en el nuevo webmail; las apps de correo y el webmail clásico nunca piden su código.

La función no tiene una restricción adicional por plan de buzones. Se siguen aplicando los permisos de los planes de API y MCP existentes; consulta Permisos y alcances de la API.

Autenticación, permisos de API y permisos de miembros

Usa un token Bearer en las solicitudes REST a /api/v1. Las escrituras JSON usan Content-Type: application/json y una cabecera Idempotency-Key.

El permiso para definir contraseñas se comprueba en el rol del miembro, además del permiso de API del token. Se aplica a los tokens de miembros y a los conectores autorizados por miembros. El token del propietario no necesita un permiso adicional para definir contraseñas. Si falta el permiso del miembro, se devuelve 403 scope_blocked_by_membership.

Los conectores OAuth alojados pueden usar los permisos REST correspondientes a cada capacidad. Con los paquetes heredados, mail:read proporciona mailboxes:read y account:read; mail:write también proporciona mailboxes:write. La ampliación de permisos nunca anula las reglas de permisos de miembros ni las reservadas al propietario.

Se aplican las restricciones domain_ids y mailbox_ids del token, incluidas las selecciones en bloque. Los endpoints de contraseñas de aplicación y ambos endpoints de modo devuelven 404 not_found mientras la función está desactivada, después de las comprobaciones de autenticación y middleware. Un buzón inaccesible o inexistente también devuelve 404, así que no interpretes cada 404 como una señal del estado de la función.

Resumen de endpoints

Las rutas siguientes incluyen el prefijo /api/v1. {mailbox} es el ID del buzón normal; {id} es el ID de una entrada de contraseña de aplicación que le pertenece.

Todas las escrituras de esta tabla requieren Idempotency-Key. El endpoint de contraseña es una operación de restablecimiento administrativo existente, independiente de la sustitución de contraseñas de aplicación.

Enumerar contraseñas de aplicación y entender los campos

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

La respuesta contiene mailbox_id, client_auth_mode, limit, active_count y data en el nivel superior; data es un array de entradas. limit es de 25 contraseñas activas por buzón. Las entradas activas aparecen primero, de más reciente a más antigua; las revocadas siguen visibles durante 90 días. Ninguna respuesta de listado contiene un secreto.

Cada entrada contiene:

Los motivos públicos de revocación son revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared y mailbox_trashed. La lista excluye las credenciales generadas internamente por la plataforma.

Crear una contraseña de aplicación

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name es obligatorio: de 1 a 64 caracteres imprimibles. Los espacios en blanco consecutivos se reducen a un solo espacio. El buzón debe ser normal y activo, sin suspensión del inicio de sesión, y tener menos de 25 contraseñas de aplicación activas.

La respuesta 201 contiene la entrada completa en data, añade data.password e incluye message. Por ejemplo, estos son los campos de credenciales de esa respuesta:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

Este ejemplo omite los demás campos del registro descritos arriba. El secreto del ejemplo es ilustrativo. Un secreto real tiene 16 letras minúsculas generadas y se devuelve sin espacios. Las apps también aceptan espacios y mayúsculas; muéstralo en cuatro grupos de cuatro si se lo presentas a un usuario.

La contraseña se devuelve una sola vez. No la incluyas en los registros de la aplicación. El usuario la introduce directamente en la app de correo con la dirección completa del buzón como nombre de usuario. La creación y la sustitución envían un aviso con el nombre de la contraseña de aplicación al buzón y a su correo de recuperación, si está configurado, sin incluir el secreto. La primera contraseña de aplicación emitida con un buzón nuevo es la excepción (ver más abajo).

Usa la API de configuración del cliente de correo para obtener los ajustes de conexión. Un perfil Apple descargado no incluye ninguna contraseña; el usuario introduce la contraseña de aplicación cuando macOS o iOS la solicita durante la instalación.

Obtener la primera contraseña de aplicación con un buzón nuevo

POST /api/v1/mailboxes y POST /api/v1/mailboxes:bulk aceptan un booleano opcional create_app_password. Con true, cada buzón creado recibe también su primera contraseña de aplicación, que se devuelve una sola vez como app_password: los campos del registro descritos arriba más password. Se llama Created with the mailbox y no se envía ningún aviso por correo por ella, porque el buzón es nuevo y quien hace la llamada acaba de recibir su contraseña. Sin el campo (por defecto false), la respuesta no cambia. Se ignora mientras las contraseñas de aplicación no estén habilitadas.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

La respuesta 201 incluye entonces one_time_password, la contraseña del buzón para el webmail, y app_password.password para las apps de correo. En una respuesta en bloque, cada fila creada tiene su propio app_password. Si no se pudo emitir, app_password es null (la creación individual añade también _app_password_warning); el buzón se crea igualmente y puedes crear una con el endpoint anterior. Un reintento exacto de una creación individual con la misma Idempotency-Key devuelve la misma respuesta, con ambos secretos incluidos, sin emitir una segunda contraseña de aplicación. Una repetición en bloque omite los secretos, igual que con one_time_password.

Sustituir o revocar una contraseña

La sustitución no requiere un cuerpo JSON:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

La respuesta 200 contiene la nueva entrada completa en data, su data.password mostrado una vez, replaced_id en el nivel superior que identifica la entrada anterior, y message. La sustitución tiene un data.id nuevo y conserva el nombre. La entrada anterior se revoca con revoked_reason: "rotated", su secreto deja de funcionar de inmediato y se cierra la sesión de las apps que lo usaban. Actualiza el dispositivo con la nueva contraseña.

Para revocar sin emitir una sustitución:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

No se requiere cuerpo. La respuesta 200 contiene status: "revoked" y la entrada revocada completa en data. La app pierde el acceso; los otros dispositivos con contraseñas de aplicación válidas se vuelven a conectar solos. La revocación no se puede deshacer. Intentar sustituir o revocar una entrada ya revocada con una solicitud nueva devuelve 409 conflict.

Cambiar el modo de inicio de sesión de apps de correo de un buzón

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode es obligatorio y acepta:

• app_password_only: las apps de correo exigen una contraseña de aplicación. Se cierra la sesión de las conexiones que usan la contraseña del buzón; las apps con una contraseña de aplicación válida se vuelven a conectar solas.
• password_or_app_password: las apps de correo aceptan la contraseña del buzón o una contraseña de aplicación.

La respuesta 200 contiene mailbox_id, client_auth_mode y message. Volver a establecer el modo actual devuelve 200 y no cambia nada. Cambiar el modo no revoca las contraseñas de aplicación existentes.

Crea contraseñas para los dispositivos antes de exigirlas. Un inicio de sesión rechazado con la contraseña del buzón puede mostrar "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (Error de inicio de sesión. Este buzón solo acepta contraseñas de aplicación: crea una en el webmail, en Configuración > Contraseñas de aplicación). Algunas apps solo muestran un error genérico de contraseña.

Los buzones compartidos no tienen inicio de sesión directo y devuelven 422 mailbox_not_eligible en este endpoint. Los buzones de sistema de la plataforma no pueden cambiar a app_password_only; se devuelve 422 system_mailbox_protected.

Ningún modo cambia el inicio de sesión en el nuevo webmail, Todas las bandejas, los tokens de la API de mensajes, las migraciones al buzón, las reglas de correo ni el reenvío. Los miembros de buzones compartidos usan las credenciales y el modo de su propio buzón normal.

Cambiar modos en bloque

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

Proporciona mode y exactamente un selector:

Las restricciones de la cuenta y del token limitan todas las selecciones. Un ID explícito fuera del acceso permitido, o un ID desconocido, devuelve 404 en lugar de aplicar una selección parcial. Un dominio desconocido o de otra cuenta devuelve 422 validation_error. Si hay cero o varios selectores, se devuelve 422 invalid_selection.

Pueden coincidir como máximo 1000 buzones. Una selección mayor devuelve 422 selection_too_large antes de hacer ningún cambio. Limita el dominio o envía lotes explícitos.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched cuenta los buzones seleccionados; updated cuenta los cambios de modo reales; skipped cuenta los buzones compartidos, en la papelera o en proceso de eliminación, además de los buzones de sistema de la plataforma al exigir contraseñas de aplicación. Los buzones pausados o con el inicio de sesión suspendido pueden actualizar su modo para cuando se recupere el acceso. Los que ya tienen el modo solicitado cuentan en matched, pero no en updated ni skipped, así que la operación se puede repetir sin riesgo. Las cuentas suspendidas se rechazan con 403.

Leer el estado del buzón y definir el ajuste predeterminado de la cuenta

Mientras las contraseñas de aplicación están activadas, GET /api/v1/mailboxes y GET /api/v1/mailboxes/{mailbox} incluyen estos campos en los recursos de buzones:

• client_auth_mode: app_password_only o password_or_app_password.
• app_passwords_count: número entero de contraseñas de aplicación activas y visibles, excluidas las credenciales internas de la plataforma.

Ambos campos se omiten mientras la función está desactivada. Los buzones compartidos no tienen modo de inicio de sesión directo utilizable ni contraseñas de aplicación; solicita las credenciales de un buzón normal de miembro.

GET /api/v1/account requiere account:read. Sus campos habituales de nivel superior siguen disponibles: id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits y created_at. Solo añade new_mailbox_client_auth_mode cuando las contraseñas de aplicación están activadas y la plataforma aplica el ajuste predeterminado de la cuenta a los buzones nuevos. De lo contrario, GET sigue disponible y omite ese campo.

Solo el propietario de la cuenta puede cambiar el ajuste predeterminado:

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

El campo obligatorio acepta los mismos dos modos. Es el único campo de la cuenta que se puede escribir aquí. La respuesta contiene id, new_mailbox_client_auth_mode y message en el nivel superior. PATCH devuelve 404 salvo que se cumplan ambas condiciones para exponer el campo, y 403 scope_blocked_by_membership para cualquier token de miembro o conector autorizado por un miembro.

Un token del propietario limitado por domain_ids o mailbox_ids devuelve 403 token_resource_constrained. Usa un token del propietario sin restricciones de recursos o cambia el ajuste predeterminado en la configuración de la cuenta.

El ajuste predeterminado afecta a los futuros buzones creados en el panel, en bloque, mediante invitaciones, por API y agentes. Nunca cambia los existentes. La creación individual por API puede proporcionar explícitamente client_auth_mode en POST /api/v1/mailboxes; si se omite, se sigue el ajuste predeterminado de la cuenta. Los buzones existentes conservan password_or_app_password tras el lanzamiento. El ajuste predeterminado de los nuevos es app_password_only salvo que el propietario de la cuenta lo cambie.

Un restablecimiento de la contraseña del buzón revoca automáticamente las contraseñas de aplicación

POST /api/v1/mailboxes/{mailbox}/password requiere mailboxes:write, el mismo permiso del miembro para definir contraseñas, e Idempotency-Key. Su cuerpo requiere password, la nueva contraseña del buzón, que debe cumplir la política de contraseñas del buzón. No es un endpoint para crear contraseñas de aplicación.

Cada restablecimiento administrativo correcto a través de este endpoint, incluido el cambio de contraseña de un agente MCP, revoca todas las contraseñas de aplicación con el motivo mailbox_password_reset. No hay opción para evitarlo. Mientras la función está activada, la respuesta incluye app_passwords_revoked, un número entero, junto a status, sync_pending y message:

• 200, status: "updated", sync_pending: false cuando se ha completado la sincronización con el servidor de correo.
• 202, status: "update_pending", sync_pending: true cuando la contraseña se ha guardado y la sincronización está pendiente. Las contraseñas de aplicación ya están revocadas en ese momento.

El restablecimiento también revoca los tokens de mensajes existentes del buzón. Es una consecuencia de restablecer la contraseña del buzón, no de sustituir una contraseña de aplicación individual ni de cambiar el modo de las apps de correo.

Los cambios de contraseña de autoservicio en el webmail solo revocan las contraseñas de aplicación cuando el usuario marca Revocar también todas las contraseñas de aplicación. Recuperar la contraseña, suspender el inicio de sesión, convertir el buzón en compartido y moverlo a Eliminados recientemente las revoca todas. Restaurar el acceso o el buzón no recupera los secretos revocados. Consulta Suspender el inicio de sesión por API.

Idempotencia y secretos mostrados una vez

Usa una Idempotency-Key nueva para cada escritura intencionada y reutilízala solo para reintentar el transporte con el mismo método, ruta y cuerpo. Las claves son obligatorias y admiten hasta 255 caracteres. Las respuestas correctas se almacenan en caché durante el periodo predeterminado de 24 horas; reutilizar una clave para una solicitud distinta devuelve 409 idempotency_mismatch.

La repetición de una creación o sustitución de contraseña de aplicación devuelve los mismos identificadores seguros, pero omite data.password. Incluye _idempotency_replay_warning y la cabecera de respuesta X-Idempotency-Replayed: true. Una repetición no permite recuperar un secreto perdido. Usa el data.id devuelto para sustituir la entrada activa con una clave nueva y obtener una contraseña utilizable. Guarda el nuevo ID después de la sustitución.

Repetir una revocación correcta con la misma clave devuelve su resultado guardado. Una solicitud de revocación nueva sobre esa entrada revocada devuelve 409 conflict. Los cambios de modo se pueden repetir por naturaleza, pero da una clave nueva a cada cambio intencionado: reutilizar una clave anterior después de cambiar de modo puede repetir una respuesta antigua en lugar de aplicar tu nueva intención.

Límites de solicitudes y errores

La creación está limitada a 60 por hora y cuenta, y la sustitución a 30 por hora y cuenta. Estos límites de cuenta se comparten entre quienes llaman por API y MCP, no son cupos independientes por token. Los cambios de modo en bloque tienen un límite adicional de 10 solicitudes por minuto. El limitador habitual de la API también se aplica a estas rutas; su valor predeterminado es de 60 solicitudes por minuto y credencial. Una solicitud limitada devuelve 429 rate_limited; respeta la cabecera Retry-After antes de reintentar.

Los errores usan el objeto error estándar con code, message, hint, request_id y retryable. Gestiona el código legible por máquina en lugar de comparar el texto.

Herramientas MCP y control de acciones destructivas

MCP usa la misma autorización REST y los mismos campos de respuesta. Las herramientas directas son:

Las herramientas de creación de buzones create_mailbox_generated_password y bulk_create_mailboxes aceptan la misma entrada opcional create_app_password que REST.

Las herramientas de escritura también aceptan idempotency_key opcional. REST usa el campo de cuerpo mode para cambiar el modo del buzón; la herramienta MCP llama a esa entrada client_auth_mode. Sus selectores en bloque tienen las mismas reglas de acceso y el límite de 1000 buzones de REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

En el servidor autoalojado, todas las escrituras anteriores requieren TREKMAIL_ALLOW_DESTRUCTIVE=true. La creación de credenciales también está sujeta a este control, porque concede acceso al buzón. Los listados y las lecturas de cuenta no requieren esa variable. Pide al usuario que apruebe el cambio previsto de credencial o acceso antes de ejecutar una escritura. Las herramientas directas que devuelven secretos indican al agente que muestre la contraseña una vez, pida al usuario que la pegue en la app y nunca la guarde en archivos o memoria ni la repita en mensajes o llamadas a herramientas posteriores.

Perfiles de los directorios de ChatGPT/OpenAI y Claude

Estos perfiles proporcionan un enlace seguro de configuración en el panel para crear y sustituir contraseñas, en lugar de generar un secreto en el chat. La creación de buzones también es allí un enlace al panel, así que la primera contraseña de aplicación sale de la tarjeta Buzón creado del panel, no de create_app_password. El destino es /app/mailboxes/{mailbox_id}/security#app-passwords; el usuario inicia sesión y completa la acción allí.

El perfil de OpenAI expone get_mailbox_app_password_setup_link y get_mailbox_app_password_replacement_setup_link. El de Claude conserva los nombres create_mailbox_app_password y rotate_mailbox_app_password, pero devuelve el enlace seguro de configuración en lugar de data.password. No prometas un secreto de esas herramientas de directorio ni pidas al usuario que lo pegue en la conversación.

Para obtener los datos de conexión, usa get_mail_client_setup. Para la configuración general de conectores, consulta Conectar agentes de IA. Los buzones White Label usan la misma función de API y los hosts de webmail y correo de la marca; llama a la credencial contraseña de aplicación en las instrucciones para usuarios.