Présentation de l’API TrekMail Drive pour les développeurs

L’API TrekMail Drive permet aux applications de confiance et aux agents IA d’utiliser le même espace de stockage que celui affiché dans le tableau de bord et le webmail. Utilisez-la pour répertorier les dossiers, téléverser des fichiers, générer des liens publics de téléchargement, restaurer des éléments de la corbeille, auditer l’utilisation du stockage et automatiser les workflows de fichiers répétitifs sans donner à un agent l’accès à l’ensemble de votre compte.

L’automatisation de Drive fait partie de l’API REST v1 de TrekMail. Elle utilise des jetons bearer, des réponses JSON, une protection par idempotence lorsque l’endpoint la prend en charge et la même piste d’audit que celle affichée sous Agents IA et API → Journal d’audit. Le modèle d’autorisation de Drive comporte 11 portées, dont des portées distinctes pour les mots de passe des appareils de synchronisation. Les catalogues d’endpoints et d’outils MCP évoluent. Utilisez donc la liste d’outils renvoyée et les réponses de l’API pour connaître la surface actuellement accessible à votre jeton.

Ce que vous pouvez automatiser

Les tâches courantes de l’API Drive comprennent :

• Téléverser des rapports mensuels dans le Drive du compte.
• Créer un dossier client, ajouter des fichiers et partager un lien de téléchargement.
• Permettre à un agent de rechercher dans les espaces Drive des boîtes aux lettres et de résumer les changements.
• Déplacer d’anciens fichiers vers un dossier d’archive.
• Restaurer des fichiers depuis la corbeille après un nettoyage accidentel.
• Consulter l’état du module Drive avant d’avertir un utilisateur que le stockage est presque plein.

L’API se concentre volontairement sur les fichiers. Elle ne remplace pas le tableau de bord de facturation et n’expose aucune modification des paiements ou des abonnements.

Drive du compte et Drive de la boîte aux lettres

Drive présente deux surfaces de stockage. Le Drive du compte est l’espace partagé de l’entreprise. Il accueille généralement les ressources de marque, les contrats, les documents d’intégration et les dossiers d’équipe. Le Drive de la boîte aux lettres est un espace personnel rattaché à une boîte dans le webmail.

Les requêtes API identifient la cible avec un paramètre space :

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

Les jetons peuvent être limités à certaines boîtes aux lettres. Si un jeton est limité à la boîte 42, les requêtes visant la boîte 99 renvoient une réponse de type « introuvable » au lieu de révéler l’existence de l’autre boîte.

Authentification et URL de base

Utilisez un jeton d’opérations dans l’en-tête Authorization :

Authorization: Bearer tm_live_your_token

Les endpoints Drive se trouvent sous :

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

Créez des jetons depuis Agents IA et API → Jetons. Choisissez uniquement les portées Drive nécessaires à votre workflow.

Les onze portées Drive

Téléversements et fichiers volumineux

Les téléversements suivent un modèle en deux étapes. L’API réserve d’abord le quota et renvoie les instructions de téléversement. Votre client envoie ensuite les octets du fichier à l’URL de téléversement. Enfin, l’API marque le téléversement comme terminé. Les fichiers volumineux peuvent utiliser un téléversement multipartie et actualiser les URL des parties si un transfert prolongé expire.

Pour la plupart des agents IA, l’outil MCP drive_file_upload est plus simple que l’appel direct aux endpoints de téléversement de bas niveau. Il gère la détection de la taille du fichier, le téléversement, la finalisation et l’abandon en cas d’échec dans une seule commande.

Liens de partage

Les liens de partage créent des URL publiques de téléchargement pour des fichiers individuels. Ils sont utiles lorsqu’un fichier est trop volumineux pour un e-mail ou lorsque l’accès doit être révocable. Définissez si possible une date d’expiration et un plafond de téléchargements. Le jeton brut du lien n’est renvoyé qu’une fois, au moment de sa création. Enregistrez donc immédiatement l’URL renvoyée si votre workflow en a besoin.

Sécurité de la suppression et de la purge

Les opérations de suppression ordinaires déplacent les fichiers et dossiers vers la corbeille. Les éléments restent récupérables jusqu’à leur restauration, leur purge ou leur suppression par les règles de conservation du produit. Les opérations de suppression définitive nécessitent des portées de purge et doivent être isolées dans un jeton distinct.

Limite du module Drive

Les agents peuvent consulter l’état, le prix et l’aperçu d’annulation du module Drive avec drive:addon:read. L’achat, le redimensionnement ou l’annulation du module Drive ne sont pas disponibles via les outils d’écriture REST ou MCP. Ces actions restent dans le tableau de bord afin que la facturation du stockage demeure un processus délibéré sous le contrôle de l’utilisateur.

Articles connexes

• Démarrage rapide de l’API Drive
• Portées et autorisations de l’API Drive
• Présentation des outils MCP Drive
• Guide du produit TrekMail Drive