Mots de passe d’application par API et MCP

L’API REST et MCP permettent de lister, créer, remplacer et révoquer les mots de passe d’application d’une boîte normale, de changer son mode de connexion des applications de messagerie et de définir le réglage par défaut du compte pour les futures boîtes. Cette page est la référence pour les intégrations. Pour les instructions du tableau de bord et du webmail, consultez Mots de passe d’application pour vos appareils.

Un mot de passe d’application donne accès à IMAP, SMTP sur les ports 465 et 587, ManageSieve et CalDAV/CardDAV. Il n’ouvre jamais le nouveau webmail ni le tableau de bord. Le webmail classique se connecte par IMAP et accepte les mots de passe d’application. La 2FA de la boîte protège uniquement la connexion au nouveau webmail ; les applications de messagerie et le webmail classique ne demandent jamais son code.

La fonctionnalité n’impose aucune restriction supplémentaire liée à l’offre de boîtes mail. Les permissions existantes des offres API et MCP s’appliquent toujours ; consultez Autorisations et portées de l’API.

Authentification, portées API et permissions des membres

Utilisez un jeton Bearer pour les requêtes REST sous /api/v1. Les écritures JSON utilisent Content-Type: application/json et un en-tête Idempotency-Key.

La permission de définir des mots de passe est vérifiée sur le rôle du membre, en plus de la portée API du jeton. Cela s’applique aux jetons de membres et aux connecteurs autorisés par des membres. Le jeton d’un propriétaire ne nécessite pas de portée supplémentaire pour définir les mots de passe. Une permission de membre manquante renvoie 403 scope_blocked_by_membership.

Les connecteurs OAuth hébergés peuvent utiliser les portées REST correspondant aux capacités. Avec les anciens ensembles de portées, mail:read fournit mailboxes:read et account:read ; mail:write fournit aussi mailboxes:write. L’expansion des portées ne remplace jamais les règles de permissions des membres ni celles réservées au propriétaire.

Les contraintes domain_ids et mailbox_ids du jeton s’appliquent, y compris aux sélections groupées. Les endpoints de mots de passe d’application et les deux endpoints de mode renvoient 404 not_found lorsque la fonctionnalité est désactivée, après les contrôles d’authentification et du middleware. Une boîte inaccessible ou absente renvoie aussi 404 : n’interprétez donc pas chaque 404 comme un indicateur de l’état de la fonctionnalité.

Vue d’ensemble des endpoints

Les chemins ci-dessous incluent le préfixe /api/v1. {mailbox} est l’ID de la boîte normale ; {id} est l’ID d’une entrée de mot de passe d’application appartenant à cette boîte.

Toutes les écritures de cette table nécessitent Idempotency-Key. L’endpoint de mot de passe est une opération existante de réinitialisation administrative, distincte du remplacement d’un mot de passe d’application.

Lister les mots de passe d’application et comprendre les champs

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

La réponse contient mailbox_id, client_auth_mode, limit, active_count et data au niveau supérieur ; data est un tableau d’entrées. limit est de 25 mots de passe actifs par boîte. Les entrées actives apparaissent d’abord, de la plus récente à la plus ancienne ; les entrées révoquées restent visibles pendant 90 jours. Aucune réponse de liste ne contient de secret.

Chaque entrée contient :

Les motifs publics de révocation sont revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared et mailbox_trashed. La liste exclut les identifiants générés en interne par la plateforme.

Créer un mot de passe d’application

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name est obligatoire : de 1 à 64 caractères imprimables. Les suites d’espaces blancs sont réduites à un seul espace. La boîte doit être normale et active, sans suspension de connexion, avec moins de 25 mots de passe d’application actifs.

La réponse 201 contient l’entrée complète sous data, ajoute data.password et inclut message. Par exemple, voici les champs d’identifiants de cette réponse :

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

Cet exemple omet les autres champs de l’enregistrement décrits ci-dessus. Le secret de l’exemple est illustratif. Un vrai secret comporte 16 lettres minuscules générées, renvoyées sans espaces. Les applications acceptent aussi les espaces et les majuscules ; affichez-le en quatre groupes de quatre si vous le présentez à un utilisateur.

Le mot de passe est renvoyé une seule fois. Gardez-le hors des journaux de l’application. L’utilisateur le saisit directement dans l’application de messagerie avec l’adresse complète de sa boîte comme nom d’utilisateur. La création et le remplacement envoient un avis indiquant le nom du mot de passe d’application à la boîte et à son adresse de récupération, si elle est définie, sans le secret. Le premier mot de passe d’application émis avec une nouvelle boîte fait exception (voir ci-dessous).

Utilisez l’API de configuration du client de messagerie pour les paramètres de connexion. Un profil Apple téléchargé ne contient aucun mot de passe ; l’utilisateur fournit le mot de passe d’application lorsque macOS ou iOS le demande pendant l’installation.

Obtenir le premier mot de passe d’application avec une nouvelle boîte

POST /api/v1/mailboxes et POST /api/v1/mailboxes:bulk acceptent un booléen facultatif create_app_password. Avec true, chaque boîte créée reçoit aussi son premier mot de passe d’application, renvoyé une seule fois sous app_password : les champs de l’enregistrement décrits ci-dessus plus password. Il est nommé Created with the mailbox, et aucun e-mail d’avis n’est envoyé pour lui, car la boîte est nouvelle et l’appelant vient de recevoir son mot de passe. Sans ce champ (par défaut false), la réponse ne change pas. Il est ignoré tant que les mots de passe d’application ne sont pas activés.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

La réponse 201 contient alors one_time_password, le mot de passe de la boîte pour le webmail, et app_password.password pour les applications de messagerie. Dans une réponse groupée, chaque ligne créée a son propre app_password. S’il n’a pas pu être émis, app_password vaut null (la création unitaire ajoute aussi _app_password_warning) ; la boîte est tout de même créée, et vous pouvez en créer un avec l’endpoint ci-dessus. Une répétition exacte d’une création unitaire avec la même Idempotency-Key renvoie la même réponse, les deux secrets compris, sans émettre de second mot de passe d’application. Une répétition groupée omet les secrets, comme pour one_time_password.

Remplacer ou révoquer un mot de passe

Le remplacement ne nécessite aucun corps JSON :

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

La réponse 200 contient la nouvelle entrée complète sous data, son data.password affiché une fois, replaced_id au niveau supérieur identifiant l’ancienne entrée, et message. Le remplacement possède un nouveau data.id et le même nom. L’ancienne entrée est révoquée avec revoked_reason: "rotated", son secret cesse de fonctionner immédiatement et les applications qui l’utilisaient sont déconnectées. Mettez à jour l’appareil avec le nouveau mot de passe.

Pour révoquer sans émettre de remplacement :

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

Aucun corps n’est requis. La réponse 200 contient status: "revoked" et l’entrée révoquée complète sous data. L’application perd l’accès ; les autres appareils avec des mots de passe d’application valides se reconnectent seuls. La révocation est irréversible. Tenter de remplacer ou révoquer une entrée déjà révoquée avec une nouvelle requête renvoie 409 conflict.

Changer le mode de connexion des applications de messagerie d’une boîte

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode est obligatoire et accepte :

• app_password_only : les applications de messagerie exigent un mot de passe d’application. Les connexions utilisant le mot de passe de la boîte sont déconnectées ; les applications avec un mot de passe d’application valide se reconnectent seules.
• password_or_app_password : les applications de messagerie acceptent le mot de passe de la boîte ou un mot de passe d’application.

La réponse 200 contient mailbox_id, client_auth_mode et message. Définir à nouveau le mode actuel renvoie 200 et ne change rien. Changer de mode ne révoque pas les mots de passe d’application existants.

Créez les mots de passe des appareils avant de les exiger. Une connexion refusée avec le mot de passe de la boîte peut afficher "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (Échec de la connexion. Cette boîte accepte uniquement les mots de passe d’application : créez-en un dans le webmail sous Paramètres > Mots de passe d’application). Certaines applications affichent seulement une erreur de mot de passe générique.

Les boîtes partagées n’ont pas de connexion directe et renvoient 422 mailbox_not_eligible sur cet endpoint. Les boîtes système de la plateforme ne peuvent pas passer à app_password_only ; cela renvoie 422 system_mailbox_protected.

Aucun mode ne change la connexion au nouveau webmail, Toutes les boîtes de réception, les jetons de l’API de messages, les migrations vers la boîte, les règles de messagerie ou le transfert. Les membres des boîtes partagées utilisent les identifiants et le mode de leur propre boîte normale.

Changer les modes en groupe

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

Fournissez mode et exactement un sélecteur :

Les contraintes du compte et du jeton limitent chaque sélection. Un ID explicite hors des accès autorisés, ou un ID inconnu, renvoie 404 au lieu d’appliquer une sélection partielle. Un domaine inconnu ou appartenant à un autre compte renvoie 422 validation_error. Zéro ou plusieurs sélecteurs renvoient 422 invalid_selection.

Au maximum 1000 boîtes peuvent correspondre. Une sélection plus grande renvoie 422 selection_too_large avant tout changement. Réduisez le domaine ou envoyez des lots explicites.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched compte les boîtes sélectionnées ; updated compte les changements de mode réels ; skipped compte les boîtes partagées, dans la corbeille ou en cours de suppression, ainsi que les boîtes système de la plateforme lorsque les mots de passe d’application sont exigés. Les boîtes en pause ou dont la connexion est suspendue peuvent recevoir un nouveau mode pour le rétablissement de l’accès. Les boîtes déjà dans le mode demandé comptent dans matched, mais pas dans updated ni skipped : l’opération peut donc être répétée sans risque. Les comptes suspendus sont refusés avec 403.

Lire l’état de la boîte et définir le réglage par défaut du compte

Lorsque les mots de passe d’application sont activés, GET /api/v1/mailboxes et GET /api/v1/mailboxes/{mailbox} incluent ces champs dans les ressources de boîte :

• client_auth_mode : app_password_only ou password_or_app_password.
• app_passwords_count : nombre entier de mots de passe d’application actifs et visibles, hors identifiants internes de la plateforme.

Les deux champs sont omis lorsque la fonctionnalité est désactivée. Les boîtes partagées n’ont ni mode de connexion directe utilisable ni mots de passe d’application ; demandez plutôt les identifiants d’une boîte normale de membre.

GET /api/v1/account nécessite account:read. Ses champs habituels au niveau supérieur restent disponibles : id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits et created_at. Il ajoute new_mailbox_client_auth_mode uniquement lorsque les mots de passe d’application sont activés et que la plateforme applique le réglage par défaut du compte aux nouvelles boîtes. Sinon, GET reste disponible et omet ce champ.

Seul le propriétaire du compte peut changer le réglage par défaut :

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

Le champ obligatoire accepte les deux mêmes modes. C’est le seul champ de compte modifiable ici. La réponse contient id, new_mailbox_client_auth_mode et message au niveau supérieur. PATCH renvoie 404 sauf si les deux conditions d’exposition du champ sont remplies, et 403 scope_blocked_by_membership pour tout jeton de membre ou connecteur autorisé par un membre.

Un jeton du propriétaire limité par domain_ids ou mailbox_ids renvoie 403 token_resource_constrained. Utilisez un jeton du propriétaire sans restriction de ressources ou changez le réglage par défaut dans les paramètres du compte.

Le réglage par défaut affecte les futures boîtes créées dans le tableau de bord, en masse, sur invitation, par API et agents. Il ne change jamais les boîtes existantes. Une création individuelle par API peut fournir explicitement client_auth_mode dans POST /api/v1/mailboxes ; l’omettre applique le réglage par défaut du compte. Les boîtes existantes conservent password_or_app_password lors du lancement. Le réglage des nouvelles boîtes est app_password_only, sauf si le propriétaire du compte le change.

Une réinitialisation du mot de passe de boîte révoque automatiquement les mots de passe d’application

POST /api/v1/mailboxes/{mailbox}/password nécessite mailboxes:write, la même permission de membre pour définir les mots de passe, et Idempotency-Key. Son corps exige password, le nouveau mot de passe de la boîte, respectant la politique de mots de passe de boîte. Ce n’est pas un endpoint de création de mot de passe d’application.

Toute réinitialisation administrative réussie via cet endpoint, y compris le changement de mot de passe d’un agent MCP, révoque tous les mots de passe d’application avec le motif mailbox_password_reset. Aucune option ne permet de l’éviter. Lorsque la fonctionnalité est activée, la réponse inclut app_passwords_revoked, un nombre entier, avec status, sync_pending et message :

• 200, status: "updated", sync_pending: false lorsque la synchronisation avec le serveur de messagerie est terminée.
• 202, status: "update_pending", sync_pending: true lorsque le mot de passe a été enregistré et que la synchronisation est en attente. Les mots de passe d’application sont déjà révoqués à ce stade.

La réinitialisation révoque aussi les jetons de messages existants de la boîte. C’est une conséquence de la réinitialisation du mot de passe de la boîte, pas du remplacement d’un mot de passe d’application individuel ni du changement du mode des applications de messagerie.

Les changements de mot de passe en libre-service dans le webmail révoquent les mots de passe d’application uniquement si l’utilisateur coche Révoquer aussi tous les mots de passe d’application. La récupération de mot de passe, la suspension de connexion, la conversion en boîte partagée et le déplacement vers Supprimés récemment les révoquent tous. Restaurer l’accès ou la boîte ne rétablit pas les secrets révoqués. Consultez Suspendre la connexion par API.

Idempotence et secrets affichés une seule fois

Utilisez une nouvelle Idempotency-Key pour chaque écriture voulue et réutilisez-la uniquement pour retenter le transport avec les mêmes méthode, chemin et corps. Les clés sont obligatoires et limitées à 255 caractères. Les réponses réussies sont mises en cache pendant la fenêtre par défaut de 24 heures ; réutiliser une clé pour une requête différente renvoie 409 idempotency_mismatch.

La répétition d’une création ou d’un remplacement de mot de passe d’application renvoie les mêmes identifiants sûrs, mais omet data.password. Elle inclut _idempotency_replay_warning et l’en-tête de réponse X-Idempotency-Replayed: true. Une répétition ne permet pas de récupérer un secret perdu. Utilisez le data.id renvoyé pour remplacer l’entrée active avec une nouvelle clé et obtenir un mot de passe utilisable. Conservez le nouvel ID après le remplacement.

Répéter une révocation réussie avec la même clé renvoie son résultat enregistré. Une nouvelle requête de révocation sur cette entrée révoquée renvoie 409 conflict. Les changements de mode sont naturellement répétables, mais attribuez une nouvelle clé à chaque changement voulu : réutiliser une ancienne clé après un changement de mode peut rejouer une ancienne réponse au lieu d’appliquer votre nouvelle intention.

Limites de requêtes et erreurs

La création est limitée à 60 par heure et par compte, et le remplacement à 30 par heure et par compte. Ces limites de compte sont partagées entre les appels API et MCP, sans quota distinct par jeton. Les changements de mode groupés ont une limite supplémentaire de 10 requêtes par minute. Le limiteur habituel de l’API s’applique aussi à ces routes ; sa valeur par défaut est de 60 requêtes par minute et par identifiant d’authentification. Une requête limitée renvoie 429 rate_limited ; respectez l’en-tête Retry-After avant de réessayer.

Les erreurs utilisent l’objet error standard avec code, message, hint, request_id et retryable. Traitez le code lisible par machine plutôt que de comparer le texte.

Outils MCP et contrôle des actions destructives

MCP utilise la même autorisation REST et les mêmes champs de réponse. Les outils directs sont :

Les outils de création de boîtes create_mailbox_generated_password et bulk_create_mailboxes acceptent la même entrée facultative create_app_password que REST.

Les outils d’écriture acceptent aussi idempotency_key facultatif. REST utilise le champ de corps mode pour changer le mode des boîtes ; l’outil MCP appelle cette entrée client_auth_mode. Ses sélecteurs groupés ont les mêmes règles d’accès et le plafond de 1000 boîtes que REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

Dans le serveur auto-hébergé, toutes les écritures ci-dessus nécessitent TREKMAIL_ALLOW_DESTRUCTIVE=true. La création d’un identifiant est aussi soumise à ce contrôle, car elle donne accès à la boîte. Les listes et lectures du compte ne nécessitent pas cette variable. Demandez à l’utilisateur d’approuver le changement d’identifiant ou d’accès prévu avant d’exécuter une écriture. Les outils directs qui renvoient des secrets demandent à l’agent d’afficher le mot de passe une fois, de le faire coller dans l’application par l’utilisateur et de ne jamais le stocker dans des fichiers ou en mémoire, ni le répéter dans des messages ou appels d’outils ultérieurs.

Profils des annuaires ChatGPT/OpenAI et Claude

Ces profils fournissent un lien sécurisé de configuration dans le tableau de bord pour la création et le remplacement, au lieu de générer un secret dans le chat. La création de boîtes y passe aussi par un lien vers le tableau de bord ; le premier mot de passe d’application vient donc de la carte Boîte créée du tableau de bord, et non de create_app_password. La destination est /app/mailboxes/{mailbox_id}/security#app-passwords ; l’utilisateur se connecte et termine l’action à cet endroit.

Le profil OpenAI expose get_mailbox_app_password_setup_link et get_mailbox_app_password_replacement_setup_link. Le profil Claude conserve les noms create_mailbox_app_password et rotate_mailbox_app_password, mais renvoie le lien sécurisé de configuration au lieu de data.password. Ne promettez pas de secret de ces outils d’annuaire et ne demandez pas à l’utilisateur d’en coller un dans la conversation.

Pour les paramètres de connexion, utilisez get_mail_client_setup. Pour la configuration générale des connecteurs, consultez Connecter des agents IA. Les boîtes White Label utilisent la même fonctionnalité API et les hôtes de webmail et de messagerie de la marque ; appelez l’identifiant mot de passe d’application dans les instructions destinées aux utilisateurs.