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.

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.

  1. Ouvrez les réglages MCP, intégrations ou connecteurs de votre client.
  2. Choisissez Ajouter un serveur MCP distant ou Ajouter un connecteur personnalisé. Le libellé exact dépend du client.
  3. Saisissez :
    • Nom : TrekMail
    • URL du serveur MCP distant : https://trekmail.net/mcp
  4. Confirmez la connexion. Votre navigateur ouvre la page d'autorisation TrekMail.
  5. 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 :

  1. Les portées de votre jeton. Un outil dont votre jeton ne possède pas la capacité n'est jamais enregistré.
  2. 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.
  3. 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 :

  1. Barrière d'environnement : TREKMAIL_ALLOW_SENDING=true doit être défini au démarrage du serveur MCP.
  2. Barrière par appel : l'agent doit transmettre confirm_send=true comme 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 :

  1. Barrière d'environnement : TREKMAIL_ALLOW_MIGRATION=true doit être défini au démarrage du serveur MCP.
  2. Barrière par appel : chaque outil exige son propre paramètre de confirmation (confirm_start=true, confirm_retry=true ou confirm_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.js est correct et que vous avez exécuté npm run build après le clonage.
  • Erreurs « Missing bearer token » : vérifiez qu'au moins l'un des jetons TREKMAIL_API_TOKEN ou TREKMAIL_MESSAGE_TOKEN est 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=true dans 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=true dans l'environnement de ce processus MCP.
  • L'outil d'envoi renvoie « Send not confirmed » : l'agent doit transmettre confirm_send=true à chaque appel de send_message ou schedule_message.
  • Aucun outil de messagerie n'apparaît : vérifiez que TREKMAIL_MESSAGE_TOKEN est défini avec un jeton tm_msg_ valide.
  • Les outils d'écriture de migration stdio auto-hébergés renvoient des erreurs : définissez TREKMAIL_ALLOW_MIGRATION=true dans 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_attachments renvoie une archive ZIP de toutes les pièces jointes encodée en base64.
  • Le brouillon a disparu après sa mise à jour : update_draft supprime l'ancien brouillon et ajoute son remplacement, qui reçoit donc une nouvelle identité UID. Utilisez à la fois le uid et le uidvalidity de 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: false pour 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.

Nous utilisons les technologies nécessaires au fonctionnement et à la sécurité de TrekMail. En confirmant, vous autorisez aussi des analyses limitées et la mesure publicitaire décrites dans notre Politique relative aux cookies.

Se connecter à TrekMail

Accédez à votre tableau de bord, vos boîtes et vos DNS.

ou

12 caractères les mots de passe correspondent

ou

E-mail de réinitialisation envoyé

Si un compte existe pour cette adresse, nous venons d’envoyer les instructions de réinitialisation du mot de passe.

En continuant, vous acceptez les Conditions d’utilisation et la Politique de confidentialité de TrekMail.