Garde-fous de sécurité et intentions de suppression

L’API TrekMail est conçue pour éviter les pertes de données accidentelles. Les opérations destructives exigent plusieurs étapes de confirmation, les limites de débit empêchent les erreurs de masse et chaque action est consignée.

Corbeille. La confirmation d’une intention de suppression de boîte aux lettres déplace désormais la boîte vers une corbeille de 7 jours (affichée sous Supprimés récemment dans le tableau de bord), au lieu de la détruire immédiatement. Vous pouvez répertorier les boîtes supprimées et en restaurer une pendant cette période :

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

Après la période de conservation, une tâche quotidienne purge définitivement les boîtes supprimées. La restauration vérifie à nouveau votre limite de boîtes par domaine. Les agents MCP utilisent les outils restore_mailbox et list_trashed_mailboxes; confirm_delete_intent est désormais récupérable et non irréversible. La suppression d’un domaine ou d’un compte supprime définitivement ses boîtes sans utiliser la corbeille.

Suppression en deux étapes (intentions de suppression)

La suppression d’une boîte aux lettres et celle d’un domaine sont les opérations destructives les plus lourdes de conséquences dans l’API. Elles suivent un processus en deux étapes :

Étape 1 : créer une intention de suppression

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

Cette opération crée une intention à durée limitée qui décrit ce qui sera supprimé. La réponse contient :

• Indicateurs de risque : avertissements concernant les règles de transfert, les alias ou les migrations actives qui seront affectés.
• Expiration : l’intention expire après 10 minutes. Vous devez ensuite en créer une nouvelle.
• URL de confirmation : l’URL à appeler pour l’étape 2.

Aucune donnée n’est supprimée à ce stade.

Étape 2 : confirmer l’intention

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

Lorsque la corbeille de boîtes aux lettres TrekMail est activée, la confirmation déplace la boîte vers Supprimés récemment et renvoie une intention terminée avec status: "executed". La boîte peut être restaurée pendant sept jours, à condition que le domaine dispose d’une place au moment de la restauration.

{
  "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"
}

Après la période de récupération, le nettoyage quotidien de TrekMail supprime définitivement la boîte. Utilisez auparavant la liste de la corbeille ou l’endpoint de restauration. La suppression d’un domaine ou d’un compte ne suit pas ce mécanisme de récupération des boîtes.

L’en-tête X-Confirm-Delete: true est obligatoire dans la requête de confirmation et constitue une vérification de sécurité supplémentaire.

Indicateurs de risque

Lorsque vous créez une intention de suppression, l’API recherche les situations susceptibles d’indiquer que vous ne souhaitez pas continuer :

Examinez ces indicateurs avant de confirmer. L’API ne bloque pas la confirmation en fonction des indicateurs de risque; ils sont uniquement informatifs.

Limites de débit des opérations destructives

Les opérations destructives possèdent deux niveaux de limitation supplémentaires au-delà de la limite standard par minute de l’API :

• Limite quotidienne par jeton : chaque jeton peut confirmer un nombre limité d’intentions de suppression par jour.
• Délai entre les confirmations : après la confirmation d’une suppression, un court délai s’applique avant que la confirmation suivante soit acceptée.

Lorsqu’elles sont déclenchées, les deux limites renvoient 429 Too Many Requests avec un en-tête Retry-After.

Contrôle de sécurité MCP pour les serveurs hébergés localement

Si vous exécutez vous-même le serveur MCP stdio, son administrateur peut exiger TREKMAIL_ALLOW_DESTRUCTIVE=true avant de rendre les outils de suppression disponibles. Il s’agit d’un contrôle de sécurité local, et non d’un commutateur de fonctionnalité du produit TrekMail. Le MCP hébergé utilise les autorisations approuvées lors d’OAuth.

Les outils de lecture restent disponibles dans les portées accordées. Examinez la tâche et les portées de l’agent avant d’autoriser les suppressions.

Idempotence

Les endpoints d’écriture qui exigent un Idempotency-Key l’indiquent dans le tableau des endpoints et la spécification OpenAPI. Utilisez une nouvelle clé pour chaque opération logique avant de réessayer une requête :

Idempotency-Key: create-mailbox-alice-2024

• La même clé avec le même corps reproduit la réponse d’origine sans répéter l’opération.
• La même clé avec un corps différent renvoie 409 Conflict.
• Des jetons différents utilisent des espaces de clés indépendants.

Le serveur MCP génère des clés d’idempotence résistantes aux répétitions pour les appels d’outils. Les nouvelles tentatives ne répètent donc pas une opération déjà terminée.

Garde-fous pour l’envoi

L’envoi d’e-mails par le serveur MCP dispose de sa propre protection à double contrôle, semblable à celle des opérations destructives, mais avec deux vérifications indépendantes :

Contrôle 1 : contrôle du serveur local

Pour un serveur MCP hébergé localement, définissez TREKMAIL_ALLOW_SENDING=true afin d’autoriser l’outil send_message. Le MCP hébergé utilise les autorisations approuvées lors d’OAuth.

Contrôle 2 : confirmation par appel

Même lorsque le contrôle d’environnement est activé, chaque appel de send_message doit inclure le paramètre confirm_send=true. Sans lui, l’outil renvoie une erreur demandant à l’agent de confirmer.

Pourquoi deux contrôles ?

Le contrôle local est défini une fois par l’administrateur qui configure le serveur MCP. Le contrôle par appel oblige l’agent à décider activement d’envoyer chaque e-mail. Aucun contrôle ne suffit à lui seul; les deux doivent être validés avant qu’un e-mail quitte le serveur.

Cela empêche les envois accidentels par des agents qui explorent les outils disponibles sans en comprendre les conséquences. Un agent peut répertorier et lire librement les messages avec un jeton de messages, mais il ne peut pas en envoyer tant que les deux contrôles ne sont pas satisfaits.

Garde-fous pour les migrations

La migration d’e-mails par le serveur MCP possède ses propres garde-fous, semblables à ceux de l’envoi et des opérations destructives.

Contrôle du serveur local pour les migrations

Pour un serveur MCP hébergé localement, définissez TREKMAIL_ALLOW_MIGRATION=true afin d’autoriser les outils d’écriture de migration (start_migration, retry_migration, delete_migration). Le MCP hébergé utilise les autorisations approuvées lors d’OAuth.

cancel_migration reste disponible quel que soit ce réglage. Cette opération de sécurité doit toujours être accessible pour arrêter une migration qui s’emballe.

Les outils de migration en lecture seule (list_migrations, get_migration) fonctionnent sans garde-fous. test_migration_connection exige TREKMAIL_ALLOW_MIGRATION=true, car il établit des connexions IMAP sortantes.

Confirmation par appel pour les migrations

Chaque outil d’écriture de migration exige un paramètre de confirmation :

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

Sans ce paramètre, l’outil renvoie une erreur demandant à l’agent de confirmer.

Limite de simultanéité à l’échelle du serveur

L’API impose une limite globale de migrations simultanées (valeur par défaut : 20). Une fois la limite atteinte, les nouvelles demandes de migration renvoient 503 avec migration_capacity_reached et retryable: true. Cette mesure protège les ressources du serveur lorsque de nombreux comptes migrent simultanément.

Journalisation d’audit

Chaque action de modification de l’API est consignée dans le journal d’audit, accessible sous Agents IA et API → Journal d’audit dans le tableau de bord. Les événements comprennent :

• Jeton créé ou révoqué : qui a créé ou révoqué un jeton d’opérations, et quand.
• Jeton de messages créé ou révoqué : qui a créé ou révoqué un jeton de messages.
• Intention créée : une intention de suppression a été créée pour une boîte précise.
• Intention confirmée : la demande de suppression a été acceptée.
• Suppression exécutée : la boîte a été déplacée vers Supprimés récemment et sa période de récupération a commencé.
• Intention expirée : une intention non confirmée a expiré après 10 minutes.
• Boîte créée : une nouvelle boîte a été provisionnée via l’API.
• Invitation créée : une invitation de configuration de boîte a été envoyée.
• Transfert mis à jour : les règles de transfert d’une boîte ont été modifiées.
• Nouvelle vérification DNS déclenchée : la vérification DNS d’un domaine a été demandée.
• Migration démarrée : une migration d’e-mails a été lancée via l’API.
• Migration annulée : une migration en cours a été annulée.
• Migration relancée : une migration échouée ou annulée a été relancée.
• Migration supprimée : un enregistrement de migration a été supprimé.
• Message lu : des messages ont été répertoriés ou lus via l’API de messages.
• Message envoyé : un e-mail a été envoyé via l’API de messages.
• Échec d’envoi du message : une tentative d’envoi d’e-mail a échoué.
• Indicateurs de message mis à jour : les indicateurs du message (lu/non lu, suivi) ont été modifiés.
• Message supprimé : un message a été supprimé d’un dossier de boîte.
• Message déplacé : un message a été déplacé entre des dossiers.
• Domaine créé : un domaine a été ajouté via l’API.
• Domaine supprimé : un domaine a été retiré via l’API.
• Ticket créé : un ticket d’assistance a été ouvert via l’API.
• Réponse au ticket : une réponse a été publiée dans un ticket.
• Ticket fermé : un ticket a été fermé via l’API.
• SMTP configuré : les paramètres SMTP ont été mis à jour.
• Connexion SMTP supprimée : une connexion SMTP personnalisée a été supprimée.
• Test SMTP mis en file d’attente : un test de connexion SMTP a été lancé.
• Jeton Cloudflare supprimé : un jeton Cloudflare stocké a été supprimé via l’API.

Tous les événements de l’API de messages, y compris les lectures, les envois, les mises à jour d’indicateurs, les suppressions et les déplacements, sont intégralement consignés. Les enregistrements d’audit sont conservés pendant 90 jours.

Chaque événement enregistre le jeton utilisé, la ressource affectée, l’adresse IP et un ID de requête.

Filtrez le journal d’audit par type d’événement, jeton ou plage de dates afin d’examiner une activité précise.

Corrections rapides

• L’intention a expiré avant sa confirmation : créez une nouvelle intention de suppression. Les intentions expirent après 10 minutes.
• « Missing confirm header » : ajoutez l’en-tête X-Confirm-Delete: true à la requête de confirmation.
• Erreur 429 lors de la confirmation d’une suppression : vous avez atteint la limite quotidienne ou le délai entre confirmations. Attendez la durée indiquée par Retry-After.
• Un agent MCP auto-hébergé indique que les outils de suppression sont désactivés : son administrateur local peut définir TREKMAIL_ALLOW_DESTRUCTIVE=true dans l’environnement de ce processus MCP.
• Un agent MCP auto-hébergé indique « Sending is disabled » : son administrateur local peut définir TREKMAIL_ALLOW_SENDING=true dans l’environnement de ce processus MCP.
• L’agent MCP indique « Send not confirmed » : l’agent doit transmettre confirm_send=true comme paramètre à chaque appel de send_message.
• Un agent MCP auto-hébergé indique que les outils de migration sont désactivés : son administrateur local peut définir TREKMAIL_ALLOW_MIGRATION=true dans l’environnement de ce processus MCP.
• Erreur 503 « migration_capacity_reached » : trop de migrations sont en cours sur le serveur. Attendez quelques minutes et réessayez.
• Erreur 409 « active migration running » : annulez la migration existante ou attendez qu’elle se termine avant d’en démarrer une nouvelle.

Articles connexes

• Présentation de l’API
• Portées de l’API et autorisations des offres
• Connexion des agents IA (MCP)
• Création et gestion des jetons API