Connecter des agents IA à TrekMail via MCP
Connectez tout client MCP compatible à TrekMail avec une autorisation par navigateur, un pont CLI universel ou des jetons statiques aux portées limitées.
Détails de l’article
Type, difficulté, forfaits et date de dernière mise à jour.
▼
Détails de l’article
Type, difficulté, forfaits et date de dernière mise à jour.
- Type
- Guide
- Difficulté
- Intermédiaire
- Forfaits
- Nano · Starter · Pro · Agency
- Dernière mise à jour
- 23 août 2026
Le serveur MCP de TrekMail permet aux clients IA compatibles de gérer votre infrastructure de messagerie en langage naturel. Son catalogue couvre les domaines, boîtes mail, marques et équipes White Label, Drive, e-mails, calendriers, migrations, assistance, facturation et services connexes via la même API TrekMail.
Le catalogue complet n'est pas chargé dans chaque conversation. TrekMail construit tools/list à partir de l'identifiant actif : les outils hors de ses portées sont omis, tout comme ceux exclus par l'ensemble d'outils sélectionné, le mode lecture seule, les limites de transport ou un réglage de sécurité local. Un identifiant de messagerie aux portées limitées présente donc une liste compacte d'outils de messagerie.
Choisir votre mode de connexion
| Méthode | Quand l'utiliser | Temps de configuration |
|---|---|---|
| Client MCP distant (recommandé) | Votre client accepte une URL MCP distante et prend en charge l'autorisation par navigateur. | ~30 secondes |
| Client CLI ou de bureau | Votre client accepte un serveur de commande/stdio ou dispose de sa propre commande MCP distante. | ~1 minute |
| mcp-remote sur tout hôte | Vous avez besoin d'un pont stdio universel vers l'endpoint MCP hébergé. | ~1 minute |
| Auto-héberger le paquet stdio | Vous voulez cibler une instance TrekMail privée, exécuter le serveur dans un conteneur ou utiliser des jetons tm_live_ statiques plutôt qu'OAuth. |
~5 minutes |
Les méthodes 1 à 3 utilisent OAuth 2.1 : lors de la première connexion, votre navigateur ouvre la page de consentement TrekMail, vous examinez les autorisations demandées et le client reçoit un jeton limité à votre compte. Aucun jeton tm_live_ de longue durée n'est copié dans le client. Révoquez une connexion à tout moment depuis Agents IA et API → Jetons → Applications connectées.
Fonctionnalités obtenues
- Un ensemble d'outils propre à la connexion, filtré avant l'enregistrement selon les autorisations et réglages de sécurité de la connexion actuelle.
- OAuth 2.1 + enregistrement dynamique du client : votre client IA s'enregistre, vous guide sur une page de consentement dans le navigateur et reçoit un jeton à portée limitée. Aucun copier-coller de jetons de longue durée pour les méthodes web, bureau ou CLI.
- Architecture à deux jetons : un jeton d'opérations distinct pour l'infrastructure et un jeton de messages pour toutes les opérations webmail. Avec OAuth, les jetons de messages sont créés automatiquement par boîte mail selon les besoins.
- Idempotence automatique pour les opérations qui l'exigent, afin qu'une nouvelle tentative ne répète pas la même opération.
- Suppression en deux étapes : la suppression d'une boîte mail exige une intention et une confirmation explicites, puis place la boîte dans Éléments récemment supprimés pour permettre sa récupération.
- Contrôles de sécurité auto-hébergés : l'administrateur de son propre serveur MCP stdio peut exiger une approbation pour les actions de suppression, d'envoi et de migration.
- Journalisation d'audit complète : chaque opération API et MCP est consignée pendant 90 jours.
Avant de commencer
- Tous les forfaits peuvent connecter des agents.
- Nano : outils Email Verifier. L'ajout de Drive Storage donne aussi à l'agent les fonctions Drive auxquelles le compte a droit, dont la navigation, le chargement, le partage, la restauration et la purge.
- Starter : Drive complet, Email Verifier complet et accès en lecture seule aux autres domaines (domaines, boîtes mail, migrations, tickets et plus). Utilisez le tableau de bord pour les écritures que Starter n'expose pas via API, comme créer des migrations, répondre aux tickets ou modifier la réponse automatique.
- Pro / Agency : accès complet en lecture et écriture à chaque famille.
- Essai ou module White Label : ajoute des outils de marque, clients/équipe et activité tant que le droit est actif. Sans lui, ces schémas sont omis. Pendant le délai de grâce après résiliation, seul le propriétaire reçoit les outils de lecture.
- Première utilisation ? Le bouton Démarrer la visite de la page Agents IA et API explique la connexion d'un agent, les étapes propres à chaque client, les jetons manuels, les applications connectées et le journal d'audit.
- Pour les méthodes OAuth (1, 2, 3), vous n'avez pas à créer de jeton manuellement. Le client le crée avec le flux d'autorisation du navigateur. Pour la méthode stdio auto-hébergée (4), créez d'abord un jeton
tm_live_dans le tableau de bord.
1. Client MCP distant (recommandé)
Utilisez cette méthode lorsque votre client IA prend en charge les serveurs MCP distants et l'autorisation par navigateur.
Raccourci : l'onglet Connecter un agent de la page Agents IA et API vous demande quel client vous utilisez et affiche ensuite le parcours exact de ce client, le chemin du menu ou le fichier de configuration, ainsi qu'un extrait prêt à l'emploi contenant déjà votre adresse. Si votre client y figure, suivez ces indications plutôt que les étapes génériques ci-dessous.
- Ouvrez les réglages MCP, intégrations ou connecteurs de votre client.
- Choisissez Ajouter un serveur MCP distant ou Ajouter un connecteur personnalisé. Le libellé exact dépend du client.
- Saisissez :
- Nom :
TrekMail - URL du serveur MCP distant :
https://trekmail.net/mcp
- Nom :
- Confirmez la connexion. Votre navigateur ouvre la page d'autorisation TrekMail.
- Connectez-vous, examinez les autorisations demandées et approuvez l'accès. Revenez au client lorsque le navigateur confirme la connexion.
La première autorisation émet un jeton à durée limitée. Les clients compatibles le renouvellent automatiquement. Pour vous déconnecter, utilisez l'action du client ou révoquez l'application dans Jetons → Applications connectées sur TrekMail.
2. Client CLI ou de bureau
Pour un client qui accepte une commande stdio, utilisez le pont indépendant du client ci-dessous :
npx -y mcp-remote https://trekmail.net/mcp
Configurez cette commande comme serveur MCP dans votre client. La première connexion ouvre votre navigateur pour l'autorisation.
Certains clients proposent aussi leur propre commande d'ajout d'un serveur MCP distant. Elle convient tout autant : utilisez https://trekmail.net/mcp comme URL du serveur et suivez les invites du client.
Exemple propre au client : Claude Code
claude mcp add trekmail https://trekmail.net/mcp -t http
Exemple propre au client : Claude Desktop
Modifiez votre fichier de configuration (macOS : ~/Library/Application Support/Claude/claude_desktop_config.json · Windows : %APPDATA%\Claude\claude_desktop_config.json) et ajoutez :
{
"mcpServers": {
"trekmail": {
"url": "https://trekmail.net/mcp",
"transport": "http"
}
}
}
Redémarrez Claude Desktop. La fenêtre OAuth s'ouvre lorsque vous mentionnez TrekMail pour la première fois dans une conversation.
Exemple propre au client : Cursor
Cursor n'a pas d'écran pour un serveur distant. Il lit ~/.cursor/mcp.json (ou .cursor/mcp.json
dans un projet) :
{
"mcpServers": {
"trekmail": {
"url": "https://trekmail.net/mcp"
}
}
}
Exemple propre au client : Windsurf
Windsurf lit ~/.codeium/windsurf/mcp_config.json. Notez que la clé est serverUrl, et non url : un
serveur distant configuré avec url est ignoré :
{
"mcpServers": {
"trekmail": {
"serverUrl": "https://trekmail.net/mcp"
}
}
}
Enregistrez le fichier et redémarrez le client pour qu'il détecte la modification. La première connexion ouvre votre navigateur afin d'approuver l'accès.
3. mcp-remote (CLI)
Utile pour les tests ou les clients MCP non-Anthropic qui ne prennent pas encore directement en charge les serveurs OAuth distants, mcp-remote est un petit pont Node entre stdio et HTTP distant.
npx -y mcp-remote https://trekmail.net/mcp
La première exécution ouvre votre navigateur pour OAuth. Ensuite, le jeton est mis en cache sous ~/.mcp-auth/ et utilisé automatiquement.
Vous pouvez le relier à tout client MCP stdio en le faisant pointer vers la commande mcp-remote plutôt que vers un point d'entrée Node local.
4. Stdio auto-hébergé (Claude Desktop / Docker / npm)
Si vous préférez des jetons tm_live_ statiques à OAuth (par exemple pour des serveurs sans surveillance, des instances TrekMail privées ou des déploiements en conteneur), clonez et exécutez le paquet MCP stdio sur votre propre hôte.
Créez d'abord un jeton API sur la page Agents IA et API → Jetons. Pour lire ou envoyer des e-mails, créez aussi un jeton de messages via l'API avec votre jeton d'opérations (consultez les instructions de l'onglet Connecter un agent).
Installer le serveur MCP
git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build
Claude Desktop (stdio)
Ajoutez ceci au fichier de configuration MCP de Claude Desktop :
macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"trekmail": {
"command": "node",
"args": ["./trekmail-mcp/build/index.js"],
"env": {
"TREKMAIL_BASE_URL": "https://trekmail.net",
"TREKMAIL_API_TOKEN": "tm_live_your_token",
"TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
"TREKMAIL_ALLOW_SENDING": "false",
"TREKMAIL_ALLOW_MIGRATION": "false"
}
}
}
}
Mettez à jour le chemin args pour cibler l'emplacement où vous avez cloné le dépôt. Remplacez les jetons par les vôtres. Vous pouvez omettre TREKMAIL_MESSAGE_TOKEN si seuls les outils d'infrastructure vous sont utiles, ou TREKMAIL_API_TOKEN si seuls les outils de messages vous sont utiles. Au moins un jeton est requis.
Claude Code (stdio)
Ajoutez ceci aux réglages MCP de Claude Code (.claude/settings.json ou configuration du projet) :
{
"mcpServers": {
"trekmail": {
"command": "node",
"args": ["./trekmail-mcp/build/index.js"],
"env": {
"TREKMAIL_BASE_URL": "https://trekmail.net",
"TREKMAIL_API_TOKEN": "tm_live_your_token",
"TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
"TREKMAIL_ALLOW_SENDING": "false",
"TREKMAIL_ALLOW_MIGRATION": "false"
}
}
}
}
Docker
Si vous préférez Docker, construisez l'image depuis le dépôt et exécutez-la :
git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .
docker run -i \
-e TREKMAIL_BASE_URL=https://trekmail.net \
-e TREKMAIL_API_TOKEN=tm_live_your_token \
-e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
-e TREKMAIL_ALLOW_SENDING=false \
-e TREKMAIL_ALLOW_MIGRATION=false \
trekmail-mcp
npm local (développement)
git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install && npm run build
TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start
Variables d'environnement stdio
Ces contrôles s'appliquent uniquement au processus MCP stdio auto-hébergé que vous exécutez. Ils n'activent ni ne désactivent une fonctionnalité du produit TrekMail.
| Variable | Obligatoire | Valeur par défaut | Description |
|---|---|---|---|
TREKMAIL_BASE_URL |
Oui | Aucune | Votre URL TrekMail (https://trekmail.net) |
TREKMAIL_API_TOKEN |
Au moins un jeton | Aucune | Jeton d'opérations commençant par tm_live_ (outils d'infrastructure) |
TREKMAIL_MESSAGE_TOKEN |
Au moins un jeton | Aucune | Jeton de messages commençant par tm_msg_ (outils de lecture/envoi d'e-mails) |
TREKMAIL_TIMEOUT_MS |
Non | 30000 |
Délai d'expiration des requêtes en millisecondes |
TREKMAIL_ALLOW_DESTRUCTIVE |
Non | false |
Activer les outils d'écriture et de suppression à fort impact, dont les changements d'accès White Label, la marque, la connexion/suppression d'alias de domaine, les intentions de suppression, la suppression de domaines, les changements de transfert, les mots de passe, l'accès aux boîtes mail, SMTP, Cloudflare, la corbeille/purge Drive et la suppression de messages |
TREKMAIL_ALLOW_SENDING |
Non | false |
Activer les actions d'envoi externe, dont les vrais e-mails et les invitations de membres White Label |
TREKMAIL_ALLOW_MIGRATION |
Non | false |
Activer les outils d'écriture de migration (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection). Remarque : cancel_migration et cancel_bulk_migration restent disponibles comme opérations de sécurité. |
Outils Drive pour les agents
Avec un jeton d'opérations contenant des portées Drive, le serveur MCP fournit des outils pour les espaces, l'utilisation, la navigation, les chargements, fichiers, dossiers, la Corbeille, les opérations groupées, les liens publics de partage, la gestion des mots de passe des appareils synchronisés et l'état du module Drive. Votre connexion voit les outils permis par ses portées.
Pour un agent réservé à Drive, définissez TREKMAIL_API_TOKEN et n'accordez que les portées nécessaires au flux de travail. Avec stdio auto-hébergé, laissez les actions destructives désactivées sauf si l'agent exécute une tâche de purge ou de vidage de corbeille révisée. L'achat, le redimensionnement et la résiliation du module Drive ne sont pas des outils MCP; les agents peuvent lire son état et son prix, mais les changements de facturation restent dans le tableau de bord.
Consultez Présentation des outils MCP Drive et Connecter des agents IA à TrekMail Drive.
Outils disponibles
Le serveur MCP expose ces outils aux agents connectés. Leur enregistrement dépend des jetons fournis.
Les outils réellement visibles par un agent dépendent de trois éléments, tous appliqués avant la réponse de tools/list :
- Les portées de votre jeton. Un outil dont votre jeton ne possède pas la capacité n'est jamais enregistré.
- Les contrôles de sécurité stdio locaux. Sur le serveur stdio auto-hébergé, l'administrateur peut exiger une approbation pour l'écriture, l'envoi ou la migration. MCP hébergé utilise plutôt les portées approuvées pendant OAuth.
TREKMAIL_READ_ONLY=true, qui retire tous les outils d'écriture, quelles que soient les portées et les options.
Une connexion auto-hébergée peut donc être volontairement limitée même si son jeton a des portées plus larges. MCP hébergé reste limité aux autorisations approuvées pendant OAuth.
Outils de domaine (jeton d'opérations)
| Outil | Description |
|---|---|
list_domains |
Lister les domaines avec des filtres facultatifs d'état ou de recherche |
get_domain |
Obtenir les détails d'un domaine précis |
get_domain_alias |
Lire une connexion d'alias de domaine et son état de livraison actuel |
set_domain_alias |
Connecter les adresses correspondantes en réception seule à un domaine principal (contrôle stdio auto-hébergé local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
remove_domain_alias |
Déconnecter un alias après confirm_remove: true (contrôle stdio auto-hébergé local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
create_domain |
Ajouter un domaine au compte |
delete_domain |
Supprimer un domaine (contrôle stdio auto-hébergé local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
update_domain_catch_all |
Configurer ou effacer l'adresse catch-all |
set_domain_mail_hosting |
Choisir si TrekMail héberge le courrier entrant du domaine ou s'il reste chez le fournisseur du client et que le domaine sert uniquement à l'envoi |
list_forwarding_addresses |
Lister les adresses de transfert sans boîte d'un domaine |
get_forwarding_address_log |
Voir le traitement récent du courrier d'une adresse : livré, différé, rejeté ou bloqué comme spam avant transfert |
create_forwarding_address |
Créer une adresse de transfert (sans boîte ni stockage) (contrôle stdio auto-hébergé local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
update_forwarding_address |
Remplacer les destinataires ou suspendre/reprendre une adresse (contrôle stdio auto-hébergé local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
delete_forwarding_address |
Supprimer une adresse de transfert (contrôle stdio auto-hébergé local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
retry_domain_dkim |
Relancer le provisionnement de la clé DKIM |
update_domain_note |
Mettre à jour la note administrative d'un domaine |
get_domain_signature |
Lire les réglages de signature par domaine |
update_domain_signature |
Définir la signature par domaine (contrôle stdio auto-hébergé local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
bulk_add_domains |
Ajouter jusqu'à 20 domaines en un appel |
Consultez Alias de domaine via API et MCP pour le comportement des forfaits, les états de réponse, la suppression sûre et les règles de routage en réception seule.
Outils White Label (jeton d'opérations)
L'ensemble white_label contient 20 outils et apparaît uniquement si les droits du compte, l'adhésion actuelle et les portées de l'identifiant le permettent. La marque se configure par domaine; les autres outils gèrent la configuration, les clients, l'accès de l'équipe et l'activité. White Label doit être actif pour écrire. Pendant le délai de grâce après résiliation, seul le propriétaire conserve les outils de lecture.
| Outil | Description |
|---|---|
get_domain_branding |
Lire l'état de marque : mode, état du module, champs, état de zone de courrier, hôtes et dns_records à créer |
set_domain_branding |
Mettre partiellement à jour la marque : mode, nom, couleurs, options et libellés tableau de bord/webmail/zone, assistance/expéditeur, portée |
set_domain_brand_logo |
Charger un logo base64 dans l'emplacement light, dark ou favicon (PNG/JPG, ICO pour favicon, ≤1 MB, sans SVG) |
verify_domain_branding_dns |
Mettre en file la vérification DNS des hôtes de marque actifs |
create_branding_preview |
Créer une URL d'aperçu de marque valable 72 heures |
remove_domain_brand_logo |
Supprimer un emplacement de logo |
remove_domain_branding |
Effacer la marque du domaine ou du compte entier |
get_white_label |
Lire les droits, la marque du compte, la progression et l'état des domaines accessibles |
get_white_label_access_catalog |
Lire les rôles, autorisations et domaines que l'appelant peut accorder |
list_white_label_members |
Rechercher ou filtrer clients, membres et invitations |
get_white_label_member |
Lire un membre, ses autorisations effectives et les opérations suivantes permises |
invite_white_label_member |
Inviter un client ou collègue; stdio local exige aussi l'activation de l'envoi |
update_white_label_member |
Modifier rôle, domaines, autorisations personnalisées ou note |
suspend_white_label_member |
Bloquer l'accès et révoquer les identifiants du membre |
resume_white_label_member |
Reprendre l'adhésion sans réactiver les anciens identifiants |
resend_white_label_invitation |
Remplacer et envoyer une invitation en attente; stdio local exige aussi l'envoi |
remove_white_label_member |
Retirer l'accès après confirm_remove=true |
restore_white_label_member |
Restaurer l'adhésion sans réactiver les anciens identifiants |
list_white_label_activity |
Lire l'activité du compte White Label |
get_white_label_member_activity |
Lire les actions et connexions d'un membre; exige les portées de lecture activité et membre |
Un agent peut configurer la marque de bout en bout : définir la marque, copier les dns_records renvoyés, les publier avec apply_cloudflare_dns, puis vérifier et consulter l'état. Les appels modifiant l'accès restent limités par l'adhésion active et les domaines de l'appelant, même si le jeton demandait des portées plus larges. Consultez le Guide API et MCP de la marque White Label et Gérer les équipes White Label avec API et MCP.
Outils DNS (jeton d'opérations)
| Outil | Description |
|---|---|
get_dns_requirements |
Obtenir les enregistrements DNS requis pour un domaine |
dns_recheck |
Déclencher la vérification DNS (renvoie l'ID) |
get_dns_check |
Interroger les résultats de vérification DNS |
Outils de boîte mail (jeton d'opérations)
| Outil | Description |
|---|---|
list_mailboxes |
Lister les boîtes mail avec filtres facultatifs |
get_mailbox |
Obtenir les détails d'une boîte précise |
get_mail_client_setup |
Obtenir les réglages IMAP/SMTP sans mot de passe, l'URL DAV sûre et sa disponibilité, la disponibilité réelle d'envoi, les guides localisés et les dossiers délégués partagés d'une boîte membre normale |
get_apple_mail_profile |
Générer un profil Apple Mail sans mot de passe en fichier Base64 |
create_mailbox_generated_password |
Créer une boîte avec mot de passe automatique (storage_allocation_mb facultatif réserve du stockage dédié) |
change_mailbox_password |
Modifier le mot de passe d'une boîte |
update_mailbox |
Modifier le nom affiché, la vue conversation ou le niveau d'accès Drive |
set_mailboxes_drive_access |
Définir l'accès Drive de plusieurs boîtes par liste, domaine ou compte entier |
update_mailbox_note |
Mettre à jour la note administrative d'une boîte |
suspend_mailbox_login |
Bloquer la connexion tout en continuant la réception (contrôle stdio auto-hébergé local : TREKMAIL_ALLOW_DESTRUCTIVE) |
resume_mailbox_login |
Lever la suspension; les mots de passe d'appareil révoqués ne sont pas restaurés |
set_mailboxes_login_access |
Suspendre ou restaurer la connexion pour plusieurs boîtes, une liste, un domaine ou toutes |
pause_mailbox |
Désactiver entièrement une boîte, livraison comprise. Utilisez suspend_mailbox_login pour bloquer uniquement la connexion |
resume_mailbox |
Réactiver une boîte suspendue |
enable_imap |
Activer IMAP pour une boîte (requis pour Message API) |
create_invite |
Envoyer une invitation (storage_allocation_mb facultatif préalloue le stockage dédié hérité à l'activation) |
create_invites_bulk |
Envoyer jusqu'à 100 invitations en un appel (storage_allocation_mb par élément pris en charge) |
bulk_create_mailboxes |
Créer jusqu'à 100 boîtes en un appel (storage_allocation_mb par élément pris en charge) |
get_forwarding |
Obtenir la configuration de transfert d'une boîte |
set_forwarding |
Configurer les règles de transfert |
Outils de boîte partagée (jeton d'opérations)
Une boîte partagée est une boîte d'équipe (support@, sales@) que les membres ouvrent dans Webmail avec leur boîte normale et, si activé, avec un accès IMAP/SMTP natif délégué. Elle n'a pas de connexion directe par mot de passe. L'accès est uniforme, tous peuvent lire, et can_send est la seule option (réponse autorisée ou lecture seule). Il n'existe aucun rôle de membre.
| Outil | Description |
|---|---|
list_shared_mailbox_members |
Lister les accès Webmail et IMAP natif délégué (par membre : member_mailbox_id, email, can_read, can_send) |
add_shared_mailbox_member |
Ajouter l'accès Webmail/natif; can_send vaut true par défaut (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
update_shared_mailbox_member |
Basculer l'envoi Webmail/natif (can_send) sans retirer la lecture (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
remove_shared_mailbox_member |
Révoquer l'accès Webmail/natif; la boîte conserve au moins un membre (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
Cycle de vie des boîtes partagées (jeton d'opérations)
| Outil | Description |
|---|---|
create_shared_mailbox |
Créer une boîte partagée depuis un domaine, une partie locale, un nom et des ID de boîtes membres (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
convert_mailbox_to_shared |
Convertir une boîte existante en boîte partagée (remplace l'ancien mot de passe) (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
convert_shared_mailbox_to_regular |
Reconvertir une boîte partagée en boîte normale, révoquer les accès membres et définir un nouveau mot de passe (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
Les trois outils de cycle de vie et les trois outils d'écriture des membres modifient l'accès. Un administrateur stdio local peut exiger TREKMAIL_ALLOW_DESTRUCTIVE=true; list_shared_mailbox_members reste disponible en lecture seule.
Après une création, conversion ou modification des membres, appelez get_mail_client_setup avec l'ID d'une boîte membre normale. Lisez shared_mailboxes.items[], attendez native_access_ready=true, puis vérifiez send_as_ready avant l'envoi. La réponse fournit les chemins Inbox/Sent/Archive/Junk exacts et les indicateurs; SMTP n'enregistre pas la copie Sent partagée. L'erreur réessayable native_access_sync_failed indique que le service a conservé l'état précédent.
Outils Sieve (jeton d'opérations)
| Outil | Description |
|---|---|
get_sieve_script |
Obtenir le script Sieve brut d'une boîte |
upload_sieve_script |
Charger un script Sieve brut pour une boîte |
Outils de suppression (jeton d'opérations)
| Outil | Description |
|---|---|
create_delete_intent |
Étape 1 : créer une intention de suppression temporaire |
confirm_delete_intent |
Étape 2 : confirmer et déplacer la boîte vers Éléments récemment supprimés |
Outils de migration (jeton d'opérations)
| Outil | Description |
|---|---|
test_migration_connection |
Valider les identifiants IMAP et découvrir les dossiers sources avec leur nombre |
list_migrations |
Lister les migrations avec filtres d'état/boîte facultatifs |
get_migration |
Obtenir l'état détaillé avec ventilation par dossier |
start_migration |
Démarrer une migration (contrôle local : TREKMAIL_ALLOW_MIGRATION + confirm_start) |
cancel_migration |
Annuler une migration active (toujours disponible, exige confirm_cancel) |
retry_migration |
Réessayer une migration échouée ou annulée (contrôle local : TREKMAIL_ALLOW_MIGRATION + confirm_retry) |
delete_migration |
Supprimer une migration terminée/échouée (contrôle local : TREKMAIL_ALLOW_MIGRATION + confirm_delete) |
preview_bulk_migration |
Valider et prévisualiser un lot (contrôle local : TREKMAIL_ALLOW_MIGRATION) |
start_bulk_migration |
Démarrer un lot (contrôle local : TREKMAIL_ALLOW_MIGRATION + confirm_start) |
list_bulk_migrations |
Lister les lots avec filtre d'état facultatif |
get_bulk_migration |
Obtenir les détails d'un lot |
cancel_bulk_migration |
Annuler un lot actif (exige confirm_cancel) |
retry_bulk_migration |
Réessayer les tâches échouées (contrôle local : TREKMAIL_ALLOW_MIGRATION + confirm_retry) |
resume_bulk_migration |
Reprendre un lot suspendu (exige confirm_resume) |
delete_bulk_migration |
Supprimer un lot final (contrôle local : TREKMAIL_ALLOW_MIGRATION + confirm_delete) |
update_bulk_migration_job_password |
Modifier le mot de passe source d'une tâche échouée (contrôle local : TREKMAIL_ALLOW_MIGRATION) |
Outils de tickets (jeton d'opérations)
| Outil | Description |
|---|---|
list_tickets |
Lister les tickets avec filtres facultatifs |
get_ticket |
Obtenir les détails d'un ticket |
get_ticket_messages |
Obtenir les messages d'un ticket |
create_ticket |
Créer un ticket |
reply_to_ticket |
Répondre à un ticket |
close_ticket |
Fermer un ticket |
Outils SMTP/routage de domaine (jeton d'opérations)
SMTP se configure par domaine : chaque domaine utilise l'envoi géré ou un profil SMTP enregistré, et une valeur par défaut du compte détermine le choix initial des nouveaux domaines.
| Outil | Description |
|---|---|
get_domain_smtp |
Voir la route (smtp_mode et effective_smtp_mode, qui résout inherit) et son profil |
set_domain_smtp |
Définir platform, profile, not_configured ou inherit; prend en charge set_account_default et apply_to_all (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
list_domain_smtp_profiles |
Lister les profils SMTP enregistrés |
get_domain_smtp_profile_usage |
Voir les domaines et adresses Send As utilisant un profil, sans identifiants |
create_domain_smtp_profile |
Créer et utiliser un profil (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
update_domain_smtp_profile |
Modifier un profil pour tous ses domaines (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
delete_domain_smtp_profile |
Supprimer un profil et réaffecter ses domaines (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
test_domain_smtp |
Lancer un test SMTP asynchrone (renvoie un ID) (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
get_domain_smtp_test_status |
Interroger une tâche de test SMTP |
get_account_smtp_default |
Voir la route par défaut (default_smtp_mode, effective_default_smtp_mode et profil) |
set_account_smtp_default |
Définir platform, profile ou not_configured; associer set_domain_smtp en mode inherit (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
Les outils d'écriture et de test modifient les réglages ou testent une connexion. Un administrateur peut exiger TREKMAIL_ALLOW_DESTRUCTIVE=true; get_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_test_status et get_account_smtp_default restent en lecture seule.
Anciens outils SMTP (obsolètes)
Ces outils de compte restent compatibles, mais ne contrôlent plus le routage par domaine : utilisez les outils ci-dessus.
| Outil | Description |
|---|---|
get_smtp_config |
(obsolète) Voir l'ancien mode SMTP et les détails de connexion |
update_smtp_config |
(obsolète) Modifier l'ancienne configuration SMTP |
delete_smtp_connection |
Supprimer une connexion SMTP personnalisée |
test_smtp |
Lancer un test asynchrone (renvoie l'ID) |
get_smtp_test_status |
Interroger les résultats du test |
Outils de métriques antispam (jeton d'opérations)
| Outil | Description |
|---|---|
get_spam_metrics |
Obtenir les métriques quotidiennes d'un domaine |
get_spam_summary |
Obtenir le résumé agrégé de protection antispam |
Outils de compte (jeton d'opérations)
| Outil | Description |
|---|---|
get_account |
Voir les informations, le forfait, les limites et l'utilisation |
get_billing_status |
Voir l'état de facturation et l'abonnement |
list_invoices |
Lister l'historique des factures |
Gestion des jetons de messages (jeton d'opérations)
| Outil | Description |
|---|---|
create_message_token |
Créer un jeton API de messages (renvoyé en clair une fois) |
list_message_tokens |
Lister tous les jetons de messages d'une boîte |
revoke_message_token |
Révoquer un jeton (contrôle local : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
Outils de messagerie (jeton de messages)
Le jeton de messages déverrouille 62 outils couvrant toute l'interface de messagerie, y compris les comptes externes connectés. Les outils sont organisés par domaine fonctionnel.
OAuth hébergé et stdio local identifient la boîte aux lettres différemment. Sur le MCP HTTP hébergé, chaque schéma d'outil de messagerie comprend un mailbox_id obligatoire ; le serveur l'utilise pour générer un jeton à courte durée de vie pour cette boîte. Sur le MCP stdio local, TREKMAIL_MESSAGE_TOKEN est déjà lié à une boîte, ces mêmes outils n'acceptent donc pas mailbox_id. Une boîte de réception connectée constitue un second niveau de sélection : transmettez external_account_id en plus de mailbox_id sur le MCP hébergé, ou en plus du jeton de messages lié sur stdio.
Sept des 62 outils de messagerie gèrent les comptes connectés, et cinq gèrent les identités d'expéditeur et la politique de réponse. Utilisez les deux familles pour un flux de travail de type Gmail où un agent lit une boîte Gmail connectée, mais envoie depuis une adresse professionnelle autorisée via une route de domaine ou un profil SMTP enregistré. Consultez Adresses d'expédition via API et MCP.
Messages principaux
| Outil | Description |
|---|---|
list_messages |
Lister les messages d'un dossier avec pagination par curseur |
read_message |
Obtenir un message avec son contenu complet et ses pièces jointes intégrées |
send_message |
Envoyer un e-mail depuis la boîte (exige les deux barrières de sécurité) |
delete_message |
Supprimer définitivement un message (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
move_message |
Déplacer un message vers un autre dossier IMAP |
update_message_flags |
Marquer un message comme lu/non lu ou suivi/non suivi |
get_raw_message |
Télécharger la source brute RFC822 complète d'un message |
Si la boîte comporte un CC par défaut ou un CCI par défaut dans Paramètres → Profil, il est ajouté aux envois de send_message et schedule_message, comme pour les messages rédigés dans l'application web ; une adresse déjà présente dans le message n'est pas ajoutée deux fois. Transmettez apply_default_recipients: false pour l'omettre d'un seul message. Cela ne concerne pas les e-mails envoyés via SMTP depuis un client de messagerie sur ordinateur ou téléphone, car ils ne passent jamais par l'API.
| report_spam | Signaler un message comme indésirable, le déplacer vers Indésirables et entraîner le filtre |
| report_ham | Marquer un message indésirable comme légitime, le déplacer vers la boîte de réception et entraîner le filtre |
| bulk_action | Appliquer une action (lire, suivre, supprimer, déplacer, signaler comme indésirable) à un maximum de 50 messages |
Dossiers
| Outil | Description |
|---|---|
list_folders |
Lister tous les dossiers IMAP de la boîte |
create_folder |
Créer un dossier |
rename_folder |
Renommer un dossier existant |
delete_folder |
Supprimer un dossier terminal et ses messages ; supprimer d'abord explicitement ses sous-dossiers (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
empty_folder |
Supprimer définitivement tous les messages de la corbeille ou des indésirables (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
Pièces jointes
| Outil | Description |
|---|---|
download_attachment |
Télécharger une pièce jointe par son index, renvoie son contenu en base64 |
download_all_attachments |
Télécharger toutes les pièces jointes d'un message sous forme d'archive ZIP en base64 |
Brouillons
| Outil | Description |
|---|---|
save_draft |
Enregistrer un brouillon et renvoyer son identité uid + uidvalidity |
update_draft |
Remplacer un brouillon à l'aide de son uid et du uidvalidity obligatoire |
Les deux outils renvoient le uid et le uidvalidity du brouillon. Conservez cette paire ensemble : update_draft exige l'époque afin qu'un ancien UID réutilisé ne puisse jamais supprimer un autre message après la recréation du dossier Brouillons. Un brouillon trouvé avec list_messages doit d'abord être ouvert avec read_message, qui renvoie son uidvalidity actuel. Une mise à jour renvoie une nouvelle paire et l'ancien UID cesse de fonctionner. Sur un serveur sans UIDPLUS, les deux valeurs peuvent être null même si un nouveau brouillon a été enregistré ; actualisez les brouillons et ouvrez le brouillon avant de le modifier.
Les deux acceptent aussi un idempotency_key facultatif. Si vous l'omettez, chaque appel est traité comme nouveau ; enregistrer deux fois le même brouillon crée donc deux brouillons. Transmettez la même clé lorsque vous répétez un appel qui a peut-être déjà abouti : vous récupérerez alors le premier résultat au lieu de créer un doublon.
Envoi planifié
| Outil | Description |
|---|---|
schedule_message |
Planifier l'envoi ultérieur d'un message (exige TREKMAIL_ALLOW_SENDING + confirm_send ; accepte un timezone IANA facultatif pour les dates et heures sans fuseau) |
list_scheduled |
Lister les messages planifiés en attente ; suivre pagination.next_cursor pour parcourir toutes les pages |
reschedule_message |
Replanifier un message en attente sur place (sans nouvel envoi ; utilise la limitation plus légère messages:read afin que les replanifications groupées n'épuisent pas la limite d'envoi) |
cancel_scheduled |
Annuler un message planifié en attente (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
Contacts
| Outil | Description |
|---|---|
list_contacts |
Lister les contacts avec un filtre de recherche facultatif |
create_contact |
Créer un contact, ou le mettre à jour si l'adresse e-mail existe déjà |
update_contact |
Modifier les champs d'un contact |
delete_contact |
Supprimer un contact (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
import_contacts |
Importer des contacts depuis un contenu CSV ou VCF encodé en base64 |
export_contacts |
Exporter tous les contacts au format CSV ou VCF, renvoie le contenu en base64 |
Groupes de contacts
| Outil | Description |
|---|---|
create_contact_group |
Créer un groupe de contacts nommé |
update_contact_group |
Renommer un groupe de contacts |
delete_contact_group |
Supprimer un groupe de contacts (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
add_contact_group_members |
Ajouter des contacts à un groupe par leur ID |
remove_contact_group_members |
Retirer des contacts d'un groupe |
Calendrier
| Outil | Description |
|---|---|
list_calendar_events |
Lister les événements du calendrier sur une période |
create_calendar_event |
Créer un événement avec titre, début/fin, lieu et notes |
update_calendar_event |
Modifier un événement existant |
delete_calendar_event |
Supprimer un événement du calendrier (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
Assistants de rédaction
Ces outils préparent les données d'une réponse ou d'un transfert. Ils n'envoient rien. Transmettez directement les données renvoyées à send_message ou save_draft.
| Outil | Description |
|---|---|
prepare_reply |
Préremplir une réponse (À, objet Re:, corps cité, en-tête In-Reply-To) |
prepare_reply_all |
Préremplir une réponse à tous (À + Cc de tous les destinataires d'origine) |
prepare_forward |
Préremplir un transfert (objet Fwd:, corps transféré, métadonnées des pièces jointes d'origine) |
Identités (adresses d'expédition)
| Outil | Description |
|---|---|
list_identities |
Lister les adresses d'expédition propres à la source, les routes d'envoi et la politique de réponse ; transmettre external_account_id pour une boîte connectée |
create_identity |
Configurer une identité gérée ou créer une identité d'expédition liée à une boîte connectée |
update_identity |
Modifier le nom, l'adresse de réponse, la signature ou la route d'envoi d'une identité |
delete_identity |
Supprimer une identité d'expédition ; les identités de boîte/d'alias gérées restent autorisées (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
set_reply_from_policy |
Répondre depuis l'adresse qui a reçu le message ou toujours utiliser celle par défaut (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
Modèles
| Outil | Description |
|---|---|
list_templates |
Lister tous les modèles de messages enregistrés |
create_template |
Créer un modèle avec un nom, un objet et un corps HTML |
update_template |
Modifier un modèle |
delete_template |
Supprimer un modèle (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
Expéditeurs bloqués
| Outil | Description |
|---|---|
list_blocked_senders |
Lister toutes les adresses e-mail et tous les domaines bloqués |
block_sender |
Bloquer une adresse e-mail précise ou un domaine entier (par exemple @spam.com) |
unblock_sender |
Retirer un blocage (contrôle stdio local auto-hébergé : TREKMAIL_ALLOW_DESTRUCTIVE) |
Outils Email Verifier (jeton d'opérations)
| Outil | Description |
|---|---|
verify_email |
Vérifier une adresse e-mail |
verify_email_bulk |
Soumettre une tâche de vérification groupée |
verify_job_status |
Consulter la progression et les résultats d'une tâche |
verify_job_download |
Télécharger les résultats d'une tâche au format CSV |
verify_credits |
Consulter le solde de crédits restant |
verify_list_jobs |
Lister toutes les tâches de vérification |
verify_cancel_job |
Annuler une tâche en cours et rembourser les crédits non utilisés |
verify_delete_job |
Supprimer définitivement une tâche et tous ses résultats (RGPD) |
Les outils Email Verifier sont disponibles avec tous les forfaits, y compris Nano. Votre solde de crédits constitue la seule limite.
Outils Cloudflare (jeton d'opérations)
| Outil | Description |
|---|---|
validate_cloudflare_token |
Valider un jeton API Cloudflare |
list_cloudflare_zones |
Lister les zones DNS accessibles à un jeton Cloudflare |
connect_cloudflare_domains |
Connecter des domaines à un compte Cloudflare |
preview_cloudflare_dns |
Prévisualiser les modifications DNS qui seraient appliquées via Cloudflare. Transmettre une liste d'autorisation included_records facultative ({ domain_id: [record_ids] }) pour ne prévisualiser que certains enregistrements |
apply_cloudflare_dns |
Appliquer les modifications DNS aux zones gérées par Cloudflare. Utiliser included_records pour écrire uniquement les enregistrements choisis et ignorer les autres (par exemple MX maintenant, DKIM plus tard) ; l'omettre pour tout appliquer. Utiliser confirmed_conflicts pour autoriser le remplacement des enregistrements signalés comme conflictuels dans la prévisualisation |
list_cloudflare_tokens |
Lister les jetons Cloudflare enregistrés |
delete_cloudflare_token |
Supprimer un jeton Cloudflare enregistré (contrôle stdio local auto-hébergé : exige TREKMAIL_ALLOW_DESTRUCTIVE) |
Les outils Cloudflare sont disponibles avec les forfaits Pro et Agency.
Contrôles de sécurité pour stdio auto-hébergé
Lorsque vous exécutez vous-même le serveur MCP stdio, TREKMAIL_ALLOW_DESTRUCTIVE détermine si ce processus local autorise les suppressions et les autres actions d'écriture. Définissez-le sur true uniquement si vous faites confiance à l'agent pour gérer la suppression dans les boîtes. Ce paramètre ne modifie pas la disponibilité des fonctionnalités dans TrekMail hébergé.
Même lorsque les opérations destructives sont activées, une suppression exige toujours deux étapes et l'agent doit explicitement définir confirm: true. Consultez Barrières de sécurité et intentions de suppression pour en savoir plus.
Barrières de sécurité pour l'envoi
Les outils send_message et schedule_message disposent de deux barrières de sécurité indépendantes qui doivent toutes deux être franchies :
- Barrière d'environnement :
TREKMAIL_ALLOW_SENDING=truedoit être défini au démarrage du serveur MCP. - Barrière par appel : l'agent doit transmettre
confirm_send=truecomme paramètre à chaque appel.
Ce système à deux barrières empêche l'envoi accidentel d'e-mails depuis un processus auto-hébergé. Définissez TREKMAIL_ALLOW_SENDING=false lorsque votre agent doit uniquement lire les messages. list_scheduled fonctionne sans ce contrôle ; il ne s'applique qu'à la création ou à l'envoi de messages planifiés.
Barrières de sécurité pour les migrations
Les outils d'écriture de migration (start_migration, retry_migration, delete_migration, delete_bulk_migration, update_bulk_migration_job_password, test_migration_connection, preview_bulk_migration, start_bulk_migration, retry_bulk_migration) disposent de deux barrières de sécurité indépendantes :
- Barrière d'environnement :
TREKMAIL_ALLOW_MIGRATION=truedoit être défini au démarrage du serveur MCP. - Barrière par appel : chaque outil exige son propre paramètre de confirmation (
confirm_start=true,confirm_retry=trueouconfirm_delete=true).
cancel_migration, cancel_bulk_migration et resume_bulk_migration sont toujours disponibles, quel que soit le contrôle d'environnement auto-hébergé, car il s'agit d'opérations de sécurité ou de reprise. Ils exigent tout de même des paramètres de confirmation par appel.
Les outils de migration en lecture seule (list_migrations, get_migration, list_bulk_migrations, get_bulk_migration) fonctionnent sans aucune barrière.
Solutions rapides
- L'agent ne peut pas se connecter : vérifiez que le chemin
build/index.jsest correct et que vous avez exécuténpm run buildaprès le clonage. - Erreurs « Missing bearer token » : vérifiez qu'au moins l'un des jetons
TREKMAIL_API_TOKENouTREKMAIL_MESSAGE_TOKENest défini. - Les outils en lecture seule fonctionnent, mais les écritures échouent : votre jeton correspond au forfait Starter. Les écritures Drive fonctionnent avec Starter (interface Drive complète). Pour les autres écritures, le provisionnement de boîtes, le démarrage de migrations ou les réponses aux tickets, passez à Pro ou utilisez le tableau de bord.
- Les outils de suppression renvoient des erreurs sur stdio auto-hébergé : définissez
TREKMAIL_ALLOW_DESTRUCTIVE=truedans l'environnement de ce processus MCP. Cela s'applique aux suppressions et autres actions d'écriture, notamment pour les messages, dossiers, contacts, calendriers, identités, modèles, expéditeurs bloqués et messages planifiés. - Un outil d'envoi stdio auto-hébergé renvoie « Sending is disabled » : définissez
TREKMAIL_ALLOW_SENDING=truedans l'environnement de ce processus MCP. - L'outil d'envoi renvoie « Send not confirmed » : l'agent doit transmettre
confirm_send=trueà chaque appel desend_messageouschedule_message. - Aucun outil de messagerie n'apparaît : vérifiez que
TREKMAIL_MESSAGE_TOKENest défini avec un jetontm_msg_valide. - Les outils d'écriture de migration stdio auto-hébergés renvoient des erreurs : définissez
TREKMAIL_ALLOW_MIGRATION=truedans l'environnement de ce processus MCP. - Erreur 503 au démarrage d'une migration : le serveur a atteint sa capacité de migration. Réessayez dans quelques minutes.
- Le téléchargement d'une pièce jointe échoue : les pièces jointes sont renvoyées en base64. Les pièces jointes volumineuses (jusqu'à 25 MB) peuvent prendre quelques secondes.
download_all_attachmentsrenvoie une archive ZIP de toutes les pièces jointes encodée en base64. - Le brouillon a disparu après sa mise à jour :
update_draftsupprime l'ancien brouillon et ajoute son remplacement, qui reçoit donc une nouvelle identité UID. Utilisez à la fois leuidet leuidvalidityde la réponse pour toute opération suivante ; la paire transmise n'identifie plus le remplacement. - Une copie de chaque message arrive à un endroit que vous n'avez pas indiqué : la boîte comporte un CC par défaut ou un CCI par défaut dans Paramètres → Profil. Il s'applique aux envois de cette boîte, y compris via l'API. Effacez-le à cet endroit, ou transmettez
apply_default_recipients: falsepour l'omettre d'un seul message. - Événement de calendrier introuvable : les événements sont limités à la boîte concernée. Vérifiez que le jeton de messages a été émis pour la bonne boîte.
Articles connexes
Articles similaires
Accédez aux guides voisins qui prolongent votre démarche.