Controles de seguridad e intenciones de eliminación

La API de TrekMail está diseñada para evitar la pérdida accidental de datos. Las operaciones destructivas requieren varios pasos de confirmación, los límites de frecuencia evitan errores masivos y cada acción queda registrada.

Papelera de reciclaje. Al confirmar una intención de eliminación de buzón, el buzón se mueve a una papelera de reciclaje de 7 días (mostrada como Eliminados recientemente en el panel) en lugar de destruirse de inmediato. Puedes enumerar los buzones eliminados y restaurar uno dentro de ese plazo:

GET  /api/v1/mailboxes?status=trashed        # list the recycle bin
POST /api/v1/mailboxes/{id}:restore          # restore to active (scope mailboxes:delete)

Después del periodo de retención, una tarea diaria purga de forma permanente los buzones eliminados. Al restaurar, se vuelve a comprobar el límite de buzones por dominio. Los agentes MCP usan las herramientas restore_mailbox y list_trashed_mailboxes; ahora confirm_delete_intent es recuperable, no irreversible. Al eliminar un dominio o una cuenta, sus buzones se eliminan de forma permanente sin pasar por la papelera.

Eliminación en dos pasos (intenciones de eliminación)

Eliminar buzones y dominios son las operaciones destructivas de mayor impacto en la API. Se utiliza un proceso de dos pasos:

Paso 1: Crear una intención de eliminación

POST /api/v1/mailboxes/{id}:delete-intent

Esto crea una intención de duración limitada que describe qué se eliminará. La respuesta incluye:

• Indicadores de riesgo: advertencias sobre reglas de reenvío, alias o migraciones activas que se verán afectadas.
• Caducidad: la intención caduca después de 10 minutos. Después deberás crear una nueva.
• URL de confirmación: la URL que debes llamar en el paso 2.

En esta etapa no se elimina ningún dato.

Paso 2: Confirmar la intención

POST /api/v1/delete-intents/{id}:confirm
Headers: X-Confirm-Delete: true

Con la papelera de buzones de TrekMail habilitada, la confirmación mueve el buzón a Eliminados recientemente y devuelve una intención completada con status: "executed". El buzón puede restaurarse durante siete días, siempre que el dominio tenga capacidad al restaurarlo.

{
  "id": 1,
  "mailbox_id": 4,
  "mailbox_email": "user@acme.test",
  "status": "executed",
  "risk_flags": [],
  "confirmed_at": "2026-05-28T11:22:08+00:00",
  "executed_at": "2026-05-28T11:22:08+00:00"
}

Después del periodo de recuperación, la limpieza diaria de TrekMail elimina permanentemente el buzón. Antes de que termine, usa la lista de la papelera o el endpoint de restauración. Eliminar un dominio o una cuenta no utiliza esta ruta de recuperación de buzones.

El encabezado X-Confirm-Delete: true es obligatorio en la solicitud de confirmación como comprobación de seguridad adicional.

Indicadores de riesgo

Cuando creas una intención de eliminación, la API comprueba condiciones que podrían indicar que no deseas continuar:

Revisa estos indicadores antes de confirmar. La API no bloquea la confirmación en función de ellos; son únicamente informativos.

Límites de frecuencia en operaciones destructivas

Las operaciones destructivas tienen dos niveles de limitación adicionales al límite estándar por minuto de la API:

• Límite diario por token: cada token puede confirmar una cantidad limitada de intenciones de eliminación al día.
• Espera entre confirmaciones: después de confirmar una eliminación, hay una breve espera antes de aceptar la siguiente confirmación.

Cuando se activan, ambos devuelven 429 Too Many Requests con un encabezado Retry-After.

Control de seguridad de MCP para servidores alojados localmente

Si ejecutas por tu cuenta el servidor MCP stdio, su administrador puede exigir TREKMAIL_ALLOW_DESTRUCTIVE=true antes de habilitar las herramientas de eliminación. Es un control de seguridad local, no un interruptor de funciones del producto TrekMail. El MCP alojado usa los permisos aprobados durante OAuth.

Las herramientas de lectura siguen disponibles dentro de los alcances concedidos. Revisa la tarea y los alcances del agente antes de permitir eliminaciones.

Idempotencia

Los endpoints de escritura que requieren un Idempotency-Key lo indican en la tabla del endpoint y en la especificación OpenAPI. Usa una clave nueva para cada operación lógica antes de reintentar una solicitud:

Idempotency-Key: create-mailbox-alice-2024

• La misma clave con el mismo cuerpo reproduce la respuesta original sin repetir la operación.
• La misma clave con un cuerpo distinto devuelve 409 Conflict.
• Los distintos tokens usan espacios de claves independientes.

El servidor MCP genera claves de idempotencia seguras frente a repeticiones para las llamadas a herramientas, por lo que los reintentos no repiten una operación ya completada.

Controles de seguridad para el envío

El envío de correo a través del servidor MCP cuenta con su propio diseño de seguridad de doble control, similar al control de operaciones destructivas, pero con dos comprobaciones independientes:

Control 1: Control del servidor local

En un servidor MCP alojado localmente, establece TREKMAIL_ALLOW_SENDING=true para permitir la herramienta send_message. El MCP alojado usa los permisos aprobados durante OAuth.

Control 2: Confirmación por llamada

Incluso con el control de entorno habilitado, cada llamada a send_message debe incluir confirm_send=true como parámetro. Sin él, la herramienta devuelve un error que solicita confirmación al agente.

¿Por qué dos controles?

El administrador que configura el servidor MCP establece una vez el control local. El control por llamada obliga al agente a decidir activamente si envía cada mensaje. Ningún control basta por sí solo; ambos deben cumplirse antes de que un correo salga del servidor.

Esto evita envíos accidentales de agentes que exploran las herramientas disponibles sin comprender sus consecuencias. Un agente puede enumerar y leer mensajes libremente (con un token de mensajes), pero no puede enviar hasta que se cumplan ambos controles.

Controles de seguridad para migraciones

La migración de correo mediante el servidor MCP tiene sus propios controles de seguridad, similares a los del envío y las operaciones destructivas.

Control del servidor local para migraciones

En un servidor MCP alojado localmente, establece TREKMAIL_ALLOW_MIGRATION=true para permitir las herramientas de escritura de migraciones (start_migration, retry_migration, delete_migration). El MCP alojado usa los permisos aprobados durante OAuth.

cancel_migration siempre está disponible, independientemente de este ajuste. Es una operación de seguridad que siempre debe estar accesible para detener una migración fuera de control.

Las herramientas de migración de solo lectura (list_migrations, get_migration) funcionan sin controles. test_migration_connection requiere TREKMAIL_ALLOW_MIGRATION=true porque realiza conexiones IMAP salientes.

Confirmación por llamada para migraciones

Cada herramienta de escritura de migraciones requiere un parámetro de confirmación:

• start_migration requiere confirm_start=true
• cancel_migration requiere confirm_cancel=true
• retry_migration requiere confirm_retry=true

Sin el parámetro de confirmación, la herramienta devuelve un error que solicita confirmación al agente.

Límite de concurrencia para todo el servidor

La API aplica un límite global de migraciones simultáneas (valor predeterminado: 20). Al alcanzarlo, las nuevas solicitudes de migración devuelven 503 con migration_capacity_reached y retryable: true. Esto protege los recursos del servidor cuando muchas cuentas migran al mismo tiempo.

Registro de auditoría

Cada acción de modificación de la API se registra en el registro de auditoría, visible en Agentes de IA y API → Registro de auditoría en el panel. Los eventos incluyen:

• Token creado o revocado: quién creó o revocó un token de operaciones y cuándo.
• Token de mensajes creado o revocado: quién creó o revocó un token de mensajes.
• Intención creada: se creó una intención de eliminación para un buzón concreto.
• Intención confirmada: se aceptó la solicitud de eliminación.
• Eliminación ejecutada: el buzón se movió a Eliminados recientemente y comenzó su periodo de recuperación.
• Intención caducada: una intención sin confirmar caducó después de 10 minutos.
• Buzón creado: se aprovisionó un buzón nuevo mediante la API.
• Invitación creada: se envió una invitación para configurar un buzón.
• Reenvío actualizado: se modificaron las reglas de reenvío de un buzón.
• Nueva comprobación de DNS iniciada: se solicitó verificar el DNS de un dominio.
• Migración iniciada: se inició una migración de correo mediante la API.
• Migración cancelada: se canceló una migración en curso.
• Migración reintentada: se reintentó una migración fallida o cancelada.
• Migración eliminada: se eliminó un registro de migración.
• Mensaje leído: se enumeraron o leyeron mensajes mediante la API de mensajes.
• Mensaje enviado: se envió un correo mediante la API de mensajes.
• Error al enviar mensaje: falló un intento de envío de correo.
• Indicadores de mensaje actualizados: se modificaron los indicadores del mensaje (leído/no leído, destacado).
• Mensaje eliminado: se eliminó un mensaje de una carpeta del buzón.
• Mensaje movido: se movió un mensaje entre carpetas.
• Dominio creado: se añadió un dominio mediante la API.
• Dominio eliminado: se eliminó un dominio mediante la API.
• Ticket creado: se abrió un ticket de soporte mediante la API.
• Respuesta a ticket: se publicó una respuesta en un ticket.
• Ticket cerrado: se cerró un ticket mediante la API.
• SMTP configurado: se actualizaron los ajustes de SMTP.
• Conexión SMTP eliminada: se eliminó una conexión SMTP personalizada.
• Prueba SMTP puesta en cola: se inició una prueba de conexión SMTP.
• Token de Cloudflare eliminado: se eliminó de la API un token de Cloudflare almacenado.

Todos los eventos de la API de mensajes, incluidas las lecturas, los envíos, las actualizaciones de indicadores, las eliminaciones y los movimientos, se registran por completo. Los registros de auditoría se conservan durante 90 días.

Cada evento registra el token utilizado, el recurso afectado, la dirección IP y un ID de solicitud.

Filtra el registro de auditoría por tipo de evento, token o intervalo de fechas para investigar una actividad concreta.

Soluciones rápidas

• La intención caducó antes de confirmarse: crea una intención de eliminación nueva. Las intenciones caducan después de 10 minutos.
• "Missing confirm header": añade el encabezado X-Confirm-Delete: true a la solicitud de confirmación.
• 429 al confirmar una eliminación: has alcanzado el límite diario o el periodo de espera. Espera el intervalo indicado por Retry-After.
• Un agente MCP autoalojado indica que las herramientas de eliminación están deshabilitadas: su administrador local puede establecer TREKMAIL_ALLOW_DESTRUCTIVE=true en el entorno de ese proceso MCP.
• Un agente MCP autoalojado indica "Sending is disabled": su administrador local puede establecer TREKMAIL_ALLOW_SENDING=true en el entorno de ese proceso MCP.
• El agente MCP indica "Send not confirmed": el agente debe enviar confirm_send=true como parámetro en cada llamada a send_message.
• Un agente MCP autoalojado indica que las herramientas de migración están deshabilitadas: su administrador local puede establecer TREKMAIL_ALLOW_MIGRATION=true en el entorno de ese proceso MCP.
• 503 "migration_capacity_reached": hay demasiadas migraciones ejecutándose en todo el servidor. Espera unos minutos y vuelve a intentarlo.
• 409 "active migration running": cancela la migración existente o espera a que termine antes de iniciar otra.