Création et gestion des jetons API

Ouvrez TrekMail dans Claude, choisissez Connect, connectez-vous et autorisez l’accès. Aucun jeton API à créer. Consultez les droits ou déconnectez l’application dans Agents IA et API → Jetons → Applications connectées.

Votre marque White Label : utilisez l’adresse MCP de votre tableau de bord de marque et nommez le connecteur selon votre marque. Ajoutez-le comme custom connector ; la fiche publique TrekMail utilise la connexion TrekMail et ne remplace pas celle de votre marque.

Les jetons API déterminent ce qu'une application ou un agent peut faire sur votre compte. Chaque jeton possède un nom, des autorisations, des restrictions de domaine facultatives et une date d'expiration.

Vous connectez un client MCP? S'il prend en charge l'autorisation par navigateur, ajoutez https://trekmail.net/mcp comme serveur MCP distant et approuvez l'accès dans le navigateur. En général, vous n'avez pas besoin de créer ni de coller un jeton. Les jetons tm_live_ manuels servent aux scripts, aux tâches CI, aux serveurs MCP auto-hébergés et aux clients qui ne prennent pas en charge ce flux. Consultez Connecter des agents IA (MCP).

Lire les e-mails avec une seule clé

Sur Pro et Agency, choisissez Lire les e-mails à la création d’une clé API. Le droit explicite est mailboxes:messages:read ; mailboxes:read affiche seulement les adresses et les paramètres de connexion. Choisissez toutes les boîtes pour inclure les boîtes actuelles et futures, ou limitez l’accès à certains domaines et boîtes. Les clés existantes ne reçoivent aucun nouveau droit automatiquement.

Utilisez la clé de compte avec les routes GET ci-dessous. L’envoi, la suppression et les modifications nécessitent toujours des identifiants et droits de messages distincts. Le MCP hébergé accepte OAuth, pas tm_live_ ni tm_msg_. L’erreur de type de jeton indique à l’agent la bonne route ou méthode d’autorisation.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

Choisir et modifier les droits de l’application

Ouvrez les détails d’une clé API ou d’une application connectée, choisissez Modifier l’accès, vérifiez les changements et confirmez. Le secret de la clé API reste identique. Réduire droits, ressources ou durée limite aussi les jetons existants et annule les envois non commencés. Les nouvelles connexions OAuth peuvent être restreintes immédiatement ; élargir l’accès demande une nouvelle approbation. Modifier une ancienne connexion la déconnecte et conserve les choix pour la reconnexion. Les jetons de messages peuvent seulement perdre des droits ou expirer plus tôt.

Avant de commencer

• Toutes les offres peuvent créer des jetons API, y compris Nano. Les offres Nano sont limitées aux autorisations Email Verifier (verify:read, verify:write).
• Les offres Starter permettent des autorisations d'infrastructure en lecture seule, ainsi que toutes les autorisations Drive et Email Verifier. Starter peut aussi gérer le transfert dans le tableau de bord, mais l'accès en écriture au transfert par API (mailboxes:forwarding:write) exige Pro ou Agency. Pro et Agency donnent accès à toutes les autorisations.
• Le propriétaire peut gérer tous les identifiants du compte. Un membre délégué autorisé à gérer les jetons API ne peut gérer que les identifiants qu'il a créés, et n'accorder que les autorisations et domaines déjà inclus dans son adhésion.
• Conseil: Cliquez sur Démarrer la visite sur la page Agents IA et API pour découvrir rapidement les options de connexion, les jetons, les applications connectées et le journal d'audit.

Créer un jeton d'automatisation Drive

L'API Drive et les outils MCP utilisent des jetons d'opérations (tm_live_...). Sélectionnez uniquement les autorisations Drive nécessaires au flux de travail:

• Rapports en lecture seule: drive:account:read, drive:mailbox:read ou drive:addon:read.
• Automatisation des téléversements: ajoutez drive:account:write ou drive:mailbox:write.
• Liens publics de diffusion: ajoutez drive:account:share ou drive:mailbox:share.
• Nettoyage permanent: utilisez drive:account:purge ou drive:mailbox:purge uniquement dans un jeton distinct et étroitement contrôlé.

L'achat, le redimensionnement et la résiliation du module Drive ne sont pas accessibles au moyen des jetons API. Les agents peuvent lire l'état et le prix du module avec drive:addon:read, mais les changements d'abonnement restent dans le tableau de bord.

Créer un jeton d'automatisation White Label

White Label utilise cinq autorisations de jeton d'opérations: branding:read, branding:write, members:read, members:write et activity:read. Elles apparaissent uniquement lorsque le compte dispose de White Label. members:write est marquée comme dangereuse, car elle peut supprimer un accès et révoquer les clés d'une autre personne.

Pour une intégration d'état et d'audit en lecture seule, sélectionnez branding:read, members:read et activity:read. Ajoutez branding:write uniquement pour la configuration de la marque et du DNS. Ajoutez members:write seulement lorsque l'automatisation doit inviter ou modifier des personnes.

Pendant le délai de grâce de résiliation, le propriétaire conserve les trois autorisations de lecture pour la récupération, tandis que les écritures et les identifiants White Label délégués cessent de fonctionner. La réactivation ne rétablit pas un identifiant révoqué; créez-en ou autorisez-en un nouveau.

Créer un jeton

1. Accédez à Agents IA et API → Jetons.
2. Cliquez sur Créer un jeton.
3. Remplissez le formulaire:
   • Nom: Libellé permettant d'identifier le jeton (par exemple, «Agent Claude», «Pipeline CI/CD»).
   • Expiration: Choisissez 7 jours, 30 jours, 90 jours, une date personnalisée ou aucune expiration.
   • Autorisations: Sélectionnez les opérations que le jeton peut effectuer. Toutes les autorisations permises sont cochées par défaut.
   • Restriction de domaine: Choisissez «Tous les domaines (actuels et futurs)», «Domaines sélectionnés uniquement» ou «Tous les domaines (actuels et futurs) sauf…» pour en écarter quelques-uns.
4. Cliquez sur Créer un jeton.

Après la création, le jeton en texte brut est affiché une seule fois. Copiez-le immédiatement ou utilisez le bouton Télécharger pour l'enregistrer dans un fichier .txt.

Le jeton ne pourra plus être affiché. Enregistrez-le en lieu sûr avant de fermer la confirmation.

Créer un jeton de message

Les jetons de message permettent aux agents de lire et d'envoyer des e-mails depuis une boîte précise. Ils sont distincts des jetons d'opérations et sont créés par programmation au moyen de l'API avec votre jeton d'opérations.

Pour créer un jeton de message, votre agent appelle:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Choisissez les autorisations minimales nécessaires au flux de travail:

Le jeton en texte brut (tm_msg_...) est renvoyé une seule fois. Ajoutez-le à votre configuration MCP sous le nom TREKMAIL_MESSAGE_TOKEN.

Les jetons de message sont disponibles avec les offres Pro et Agency. Le jeton d'opérations doit disposer de l'autorisation mailboxes:message-tokens:manage.

Pour une boîte Gmail connectée ou une autre boîte externe, utilisez external_account_id. Pour que les destinataires voient plutôt une adresse professionnelle autorisée, utilisez également un identity_id renvoyé par l'endpoint des identités. Consultez Adresses d'envoi via API et MCP.

Format des jetons

TrekMail utilise deux préfixes pour distinguer les types de jetons:

Les 8 premiers caractères après le préfixe sont conservés sous la forme d'un préfixe visible dans le tableau de bord afin de faciliter l'identification.

Autorisations

Les autorisations déterminent ce que le jeton peut faire. Les options disponibles dépendent de votre offre:

• Nano: Email Verifier uniquement (verify:read, verify:write). L'ajout de Drive Storage donne également au compte les fonctions API Drive et MCP auxquelles il a droit.
• Starter: Accès complet à Drive et Email Verifier, et accès en lecture seule à tout le reste (domaines, boîtes, transfert, filtres de courrier, réponse automatique, migrations, tickets, SMTP, Cloudflare). Utilisez le tableau de bord pour les actions d'écriture que Starter ne propose pas par API, comme créer des migrations, répondre aux tickets ou modifier la réponse automatique.
• Pro et Agency: Accès complet. Lecture, écriture, création et suppression pour toutes les familles, ainsi que jetons de message pour lire et envoyer des e-mails par API.

Les autorisations White Label correspondent au droit du module complémentaire et ne permettent pas de contourner le tableau des offres. Elles sont proposées uniquement lorsque White Label est actif; le propriétaire conserve un accès de récupération en lecture seule pendant le délai de grâce de résiliation.

Consultez Autorisations API et offres pour obtenir la référence de chaque autorisation.

Restrictions de domaine

Par défaut, les jetons peuvent accéder à tous les domaines de votre compte, y compris ceux que vous ajouterez plus tard. Deux choix permettent de restreindre cet accès:

• Domaines sélectionnés uniquement: le jeton accède aux domaines cochés et à rien d'autre. Un domaine ajouté plus tard reste exclu tant que vous ne modifiez pas le jeton pour le cocher.
• Tous les domaines (actuels et futurs) sauf…: le jeton accède à tous les domaines sauf ceux que vous cochez, y compris ceux ajoutés plus tard. Pratique pour tenir vos agents à l'écart du courrier d'un client sans modifier le jeton à chaque nouveau domaine.

Un jeton restreint reçoit des réponses 404 lorsqu'il tente d'accéder aux ressources d'autres domaines; l'API se comporte comme si ces domaines n'existaient pas. Dans les deux cas, le jeton ne peut pas non plus modifier les réglages de tout le compte qui toucheraient des domaines hors de sa portée, comme le réglage par défaut des nouvelles boîtes.

Pour un membre de l'équipe limité à certains domaines, «sauf…» désigne ses propres domaines moins ceux qui sont cochés; les domaines ajoutés ensuite au compte ne sont pas inclus. Si vous supprimez un domaine exclu puis l'ajoutez à nouveau, il compte comme un nouveau domaine: excluez-le de nouveau.

Régénérer un jeton

Régénérez un jeton lorsque vous avez de nouveau besoin de son secret ou que ce secret a pu fuiter. Le jeton conserve son nom, ses autorisations, ses domaines, ses boîtes aux lettres, sa date d'expiration et son historique d'audit. Seul le secret change.

1. Accédez à Agents IA et API → Jetons et ouvrez les Détails du jeton.
2. Cliquez sur Régénérer.
3. Choisissez quand l'ancien secret cesse de fonctionner : Maintenant, Dans 1 heure, Dans 24 heures, Dans 3 jours ou Dans 7 jours. L'ancien secret ne fonctionne jamais au-delà de l'expiration du jeton lui-même.
4. Cliquez sur Régénérer et copiez le nouveau secret. Comme pour un nouveau jeton, il n'est affiché qu'une seule fois.

Tant que l'ancien secret fonctionne, les détails du jeton indiquent jusqu'à quand et proposent Désactiver maintenant. Remplacez le secret dans chaque application d'ici là : les requêtes qui utilisent encore l'ancien secret reçoivent ensuite 401 Unauthorized.

Les jetons de message (tm_msg_...) créés avec l'ancien secret cessent de fonctionner en même temps. Une application qui crée elle-même ses jetons de message peut en créer de nouveaux avec le nouveau secret. Si le secret a pu fuiter, choisissez Maintenant.

Révoquer un jeton

1. Accédez à Agents IA et API → Jetons.
2. Repérez le jeton dans la liste.
3. Cliquez sur Révoquer.
4. Confirmez la révocation.

Les jetons révoqués cessent immédiatement de fonctionner. Toute requête API utilisant un jeton révoqué reçoit 401 Unauthorized.

La révocation est définitive et ne peut pas être annulée. Créez un nouveau jeton si vous devez rétablir l'accès.

État du jeton

Les jetons ont trois états:

Utilisez le filtre d'état de la page Jetons pour afficher les jetons par état.

Journal d'audit

Chaque création, régénération et révocation de jeton apparaît dans l'onglet Journal d'audit. Les événements incluent le nom du jeton, l'action et l'heure.

Solutions rapides

• «Autorisations indisponibles avec votre offre»: Votre offre ne comprend pas ces autorisations. Nano reste limité à verify:read et verify:write (ajoutez le module Drive Storage pour obtenir également les autorisations drive:*). Starter ajoute l'accès en lecture à toutes les familles d'infrastructure, ainsi que Drive et Email Verifier complets. Pro et Agency permettent l'écriture partout.
• Jeton en texte brut perdu: Le jeton ne peut pas être récupéré, mais vous pouvez le régénérer : ouvrez ses Détails, cliquez sur Régénérer et copiez le nouveau secret. Le jeton conserve ses réglages.
• Le jeton fonctionne, mais renvoie 404 pour certains domaines: Il possède probablement une restriction de domaine. Ouvrez Détails sur le jeton, choisissez Modifier l’accès et ajoutez les domaines manquants, ou passez à «Tous les domaines (actuels et futurs)» ou à «Tous les domaines (actuels et futurs) sauf…».
• Une autorisation White Label renvoie scope_blocked_by_entitlement: Réactivez White Label, puis créez ou autorisez un identifiant avec l'autorisation requise.
• Un jeton délégué s'est arrêté après un changement de rôle: La réduction, la suspension ou la suppression de l'accès d'un membre révoque immédiatement les identifiants concernés. Créez un nouveau jeton une fois que le propriétaire a restauré l'accès approprié.

Articles associés

• Présentation de l'API Drive
• Présentation de l'API
• Autorisations API et offres
• Connecter des agents IA (MCP)
• Gérer les équipes White Label avec API et MCP