Panoramica dell’API TrekMail Drive per sviluppatori

L’API TrekMail Drive consente alle applicazioni attendibili e agli agenti IA di usare lo stesso spazio per i file visibile nella dashboard e nella webmail. Usala per elencare le cartelle, caricare file, generare link pubblici di download, ripristinare elementi dal cestino, controllare l’utilizzo dello spazio e automatizzare flussi ripetitivi sui file senza concedere a un agente l’accesso all’intero account.

L’automazione di Drive fa parte dell’API REST v1 di TrekMail. Usa token bearer, risposte JSON, protezione dell’idempotenza quando l’endpoint la supporta e lo stesso audit trail mostrato in Agenti IA e API → Registro di audit. Il modello di autorizzazione di Drive include 11 ambiti, con ambiti separati per le password dei dispositivi di sincronizzazione. I cataloghi degli endpoint e degli strumenti MCP evolvono, quindi usa l’elenco degli strumenti restituito e le risposte dell’API per conoscere la superficie attualmente disponibile per il tuo token.

Cosa puoi automatizzare

Le attività tipiche dell’API Drive includono:

• Caricare i report mensili nel Drive dell’account.
• Creare una cartella per un cliente, aggiungere file e condividere un link di download.
• Consentire a un agente di cercare negli spazi Drive delle caselle e riepilogare le modifiche.
• Spostare i vecchi file in una cartella di archivio.
• Ripristinare file dal cestino dopo una pulizia accidentale.
• Leggere lo stato del componente aggiuntivo Drive prima di avvisare un utente che lo spazio è quasi pieno.

L’API è volutamente incentrata sui file. Non sostituisce la dashboard di fatturazione e non espone modifiche ai pagamenti o agli abbonamenti.

Drive dell’account e Drive della casella

Drive dispone di due superfici di archiviazione. Il Drive dell’account è lo spazio aziendale condiviso. In genere è il posto adatto per risorse del marchio, contratti, materiale di onboarding e cartelle del team. Il Drive della casella è lo spazio personale associato a una casella nella webmail.

Le richieste API identificano la destinazione con un parametro space:

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

I token possono essere limitati a caselle specifiche. Se un token è limitato alla casella 42, le richieste per la casella 99 restituiscono una risposta simile a "non trovato" invece di rivelare l’esistenza dell’altra casella.

Autenticazione e URL di base

Usa un token operativo nell’intestazione Authorization:

Authorization: Bearer tm_live_your_token

Gli endpoint Drive si trovano sotto:

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

Crea i token da Agenti IA e API → Token. Scegli solo gli ambiti Drive richiesti dal tuo flusso di lavoro.

Gli undici ambiti Drive

Caricamenti e file di grandi dimensioni

I caricamenti usano un modello in due passaggi. Per prima cosa l’API riserva la quota e restituisce le istruzioni di caricamento. Il client invia quindi i byte del file all’URL di caricamento. Infine, l’API contrassegna il caricamento come completato. I file di grandi dimensioni possono usare un caricamento multiparte e aggiornare gli URL delle parti se un trasferimento lungo scade.

Per la maggior parte degli agenti IA, lo strumento MCP drive_file_upload è più semplice della chiamata diretta agli endpoint di caricamento di basso livello. Gestisce in un unico comando il rilevamento delle dimensioni, il caricamento, il completamento e l’interruzione in caso di errore.

Link di condivisione

I link di condivisione creano URL pubblici di download per singoli file. Sono utili quando un file è troppo grande per l’email o quando l’accesso deve poter essere revocato. Imposta una data di scadenza e un limite di download quando possibile. Il token grezzo del link viene restituito una sola volta, al momento della creazione, quindi salva subito l’URL restituito se il flusso di lavoro ne ha bisogno.

Sicurezza di eliminazione e cancellazione definitiva

Le normali operazioni di eliminazione spostano file e cartelle nel cestino. Gli elementi rimangono recuperabili finché non vengono ripristinati, eliminati definitivamente o rimossi dalle regole di conservazione del prodotto. Le operazioni di eliminazione definitiva richiedono ambiti specifici e devono essere isolate in un token separato.

Limite del componente aggiuntivo Drive

Gli agenti possono leggere lo stato, il prezzo e l’anteprima di annullamento del componente aggiuntivo Drive con drive:addon:read. L’acquisto, il ridimensionamento o l’annullamento del componente aggiuntivo Drive non sono disponibili tramite strumenti di scrittura REST o MCP. Queste azioni rimangono nella dashboard affinché la fatturazione dello spazio sia un flusso intenzionale e controllato dall’utente.