Descripción de la API de TrekMail Drive para desarrolladores

La API de TrekMail Drive permite que aplicaciones de confianza y agentes de IA trabajen con el mismo almacenamiento de archivos que ves en el panel y el webmail. Utilízala para enumerar carpetas, cargar archivos, generar enlaces públicos de descarga, restaurar elementos de la papelera, auditar el uso del almacenamiento y automatizar flujos de archivos repetitivos sin dar a un agente acceso a toda tu cuenta.

La automatización de Drive forma parte de la API REST v1 de TrekMail. Utiliza tokens bearer, respuestas JSON, protección de idempotencia cuando el endpoint la admite y el mismo registro de auditoría que aparece en Agentes de IA y API → Registro de auditoría. El modelo de permisos de Drive tiene 11 ámbitos, incluidos ámbitos independientes para las contraseñas de dispositivos de sincronización. Los catálogos de endpoints y herramientas MCP evolucionan, así que utiliza la lista de herramientas devuelta y las respuestas de la API para conocer la superficie disponible actualmente para tu token.

Qué puedes automatizar

Las tareas habituales de la API de Drive incluyen:

• Cargar informes mensuales en Drive de la cuenta.
• Crear una carpeta para un cliente, añadir archivos y compartir un enlace de descarga.
• Permitir que un agente busque en espacios de Drive de buzones y resuma los cambios.
• Mover archivos antiguos a una carpeta de archivo.
• Restaurar archivos desde la papelera después de una limpieza accidental.
• Consultar el estado del complemento de Drive antes de avisar a un usuario de que el almacenamiento está casi lleno.

La API está centrada intencionadamente en los archivos. No sustituye al panel de facturación ni permite modificar pagos o suscripciones.

Drive de la cuenta y Drive del buzón

Drive tiene dos superficies de almacenamiento. Drive de la cuenta es el espacio compartido de la empresa. Suele ser el lugar indicado para recursos de marca, contratos, material de incorporación y carpetas del equipo. Drive del buzón es el almacenamiento personal asociado a un buzón dentro del webmail.

Las solicitudes de la API identifican el destino con un parámetro space:

account       # Account Drive
mailbox:42    # mailbox-personal Drive for mailbox ID 42
123           # internal Drive space ID, if your integration stores it

Los tokens pueden restringirse a determinados buzones. Si un token está limitado al buzón 42, las solicitudes para el buzón 99 devuelven una respuesta similar a "no encontrado" en lugar de revelar que el otro buzón existe.

Autenticación y URL base

Utiliza un token de operaciones en el encabezado Authorization:

Authorization: Bearer tm_live_your_token

Los endpoints de Drive se encuentran bajo:

https://trekmail.net/api/v1/drive

Crea tokens en Agentes de IA y API → Tokens. Elige únicamente los ámbitos de Drive que necesite tu flujo de trabajo.

Los once ámbitos de Drive

Cargas y archivos grandes

Las cargas utilizan un patrón de dos pasos. Primero, la API reserva cuota y devuelve instrucciones de carga. A continuación, el cliente envía los bytes del archivo a la URL de carga. Por último, la API marca la carga como completada. Los archivos grandes pueden utilizar una carga multiparte y renovar las URL de las partes si caduca una transferencia larga.

Para la mayoría de los agentes de IA, la herramienta MCP drive_file_upload es más sencilla que llamar directamente a endpoints de carga de bajo nivel. Se ocupa de detectar el tamaño del archivo, cargarlo, completar la operación y cancelarla en caso de fallo con un solo comando.

Enlaces compartidos

Los enlaces compartidos crean URL públicas de descarga para archivos individuales. Son útiles cuando un archivo es demasiado grande para enviarlo por correo o cuando el acceso debe poder revocarse. Siempre que sea posible, define una fecha de caducidad y un límite de descargas. El token sin procesar del enlace solo se devuelve una vez, al crearlo, así que guarda inmediatamente la URL devuelta si tu flujo la necesita.

Seguridad al eliminar y purgar

Las operaciones de eliminación normales mueven archivos y carpetas a la papelera. Los elementos pueden recuperarse hasta que se restauran, se purgan o se eliminan según las reglas de retención del producto. Las operaciones de eliminación permanente requieren ámbitos de purga y deben aislarse en un token independiente.

Límite del complemento de Drive

Los agentes pueden consultar el estado, el precio y la vista previa de cancelación del complemento de Drive con drive:addon:read. Comprar, cambiar el tamaño o cancelar el complemento de Drive no está disponible mediante herramientas de escritura REST o MCP. Esas acciones permanecen en el panel para que la facturación del almacenamiento siga siendo un proceso deliberado y controlado por el usuario.