Clés, membres et rôles

Ces commandes décident qui et quoi peut atteindre l'espace de travail. openemail keys gère les clés API et lit ce que chacune a fait, openemail members gère les personnes de l'espace de travail et leurs invitations, et openemail roles définit ce qu'un membre ou une clé peut faire. openemail me décrit la clé ou la connexion avec laquelle vous appelez, et openemail languages liste les langues qu'accepte un envoi traduit. Les boîtes jetables n'ont besoin d'aucune connexion : openemail temp est la façon courante d'en utiliser une, et openemail temp-mail couvre chaque appel de l'API qui se trouve derrière. openemail api atteint tout point de terminaison que les autres commandes n'atteignent pas.

• —Une commande de clé prend l'identifiant de la clé, les 24 caractères hexadécimaux après oe_live_, tel que keys list l'affiche. Une commande de membre prend l'identifiant du compte, userId dans members list, jamais une adresse e-mail. Une commande de rôle prend un identifiant role_ venant de roles list, car les rôles ne se recherchent pas par nom.
• —Les espaces de noms répondent aussi à key, member, role, language et tempMail. Les alias de verbe habituels fonctionnent, comme ls, show, new, edit et rm. Dans members, dont les verbes sont add et remove, new et create mènent à add, et rm, del et delete mènent à remove.
• —openemail <command> --help liste chaque argument et option avec son type, le scope dont l'appel a besoin, sa méthode et son chemin, et ce qui revient. Ajoutez --json pour obtenir la même page sous forme de données.

Lire les clés demande keys:read, et chaque changement demande keys:manage. Une connexion par navigateur ne reçoit jamais keys:write ni keys:manage, donc créer, modifier, faire tourner, révoquer et supprimer des clés exige une clé API qui détient keys:manage, ou l'application web (openemail open api-keys). Une connexion par navigateur avec keys:read ne lit les clés que pour le propriétaire de l'espace de travail, et la connexion d'un membre est refusée avec 403 owner_only.

• —keys create, keys rotate et me rotate affichent le secret de la clé, dans token, une seule fois, et la CLI avertit ensuite qu'il ne sera plus jamais montré. Chaque lecture montre maskedKey à la place.
• —Sans précision, une nouvelle clé ne détient que emails:send, et prend le rôle, la portée d'envoi et l'expiration de la clé qui la crée. --domain-allowlist et --address-allowlist fixent sous quelles adresses elle peut envoyer, et --expires-in-minutes prend de 5 à 5 256 000, soit dix ans.
• —Une clé ne crée ni n'atteint jamais une clé plus large qu'elle-même. Les scopes, le rôle, l'expiration, le mode et la portée d'envoi doivent tous tenir dans la clé appelante, sinon l'appel est refusé avec 403 beyond_caller_authority, et param nomme ce qui était trop large. Une clé restreinte à certains domaines ou adresses ne voit que les clés comprises dans sa propre portée d'envoi, et toute autre donne un 404.
• —keys update remplace ce que vous envoyez : --scopes, --address-allowlist et --domain-allowlist prennent chacune toute la nouvelle liste, et une option omise reste telle quelle. --no-enabled désactive une clé, si bien que chaque appel avec elle est refusé avec inactive_api_key, et --enabled la rétablit à l'identique. C'est ainsi qu'on arrête une clé de façon réversible.
• —keys revoke est définitif : la clé ne peut plus jamais être réactivée, tournée ni modifiée. keys delete ne retire qu'une clé révoquée, et toute autre est refusée avec 409 not_revoked. Le journal des requêtes et l'activité d'une clé supprimée restent, sous Deleted key.
• —keys rotate n'a pas de fenêtre de chevauchement, donc l'ancien secret cesse de fonctionner au moment où le nouveau revient. Quand la clé est celle qu'utilise votre profil enregistré, la CLI enregistre le nouveau secret dans ce profil, pour qu'il continue de fonctionner. Une clé venant de OPENEMAIL_API_KEY ou de --api-key ne peut pas être enregistrée, donc la CLI vous dit de stocker le nouveau jeton là où l'ancienne clé était conservée.

Le journal des requêtes enregistre chaque appel qu'une clé a fait : méthode, chemin, statut, code d'erreur, durée, IP et agent utilisateur, jamais un corps ni une chaîne de requête. Rien n'est purgé, il remonte donc jusqu'au premier appel d'une clé, et les appels faits avec une connexion par navigateur n'y figurent pas. Le journal d'activité enregistre chaque changement apporté à une clé, et chaque appel qui a présenté la clé et a été refusé, sous auth_failed, avec l'auteur de chaque changement dans actor.

• —list-requests et list-activity lisent une clé. list-workspace-requests et list-workspace-activity lisent chaque clé que vous pouvez voir, ou jusqu'à 50 que nomme --key-ids, clés supprimées comprises.
• —--since et --until gardent une période et prennent une heure ISO 8601 comme 2026-09-01T00:00:00Z. --failed-only garde les appels auxquels on a répondu avec un statut de 400 ou plus.

openemail me get est la première commande à lancer quand un appel est refusé. Elle ne demande aucun scope, donc toute clé ou connexion valide peut se décrire elle-même.

• —scopes est ce que l'identifiant peut faire en ce moment : les scopes avec lesquels il a été créé, réduits par le rôle sous lequel il a été émis, recalculés à chaque requête. grantedScopes est ce avec quoi il a été créé, et roleId nomme le rôle. Un scope présent dans grantedScopes et absent de scopes a été retiré par le rôle. C'est la raison habituelle d'un 403 insufficient_scope sur une clé qui semble détenir le scope, et la solution est de modifier le rôle plutôt que de créer une autre clé.
• —domainAllowlist et addressAllowlist indiquent sous quelles adresses il peut envoyer. Les deux à null signifient n'importe quelle adresse que possède l'espace de travail.
• —Avec une connexion par navigateur, elle décrit la connexion : object vaut oauth_token, clientId nomme l'application connectée de cette CLI, et expiresAt est la date de fin de votre approbation, ou null quand elle ne prend jamais fin.
• —me ping répond ok: true avec le même détail des scopes mais sans les listes d'autorisation, ce qui convient à un contrôle de santé. Une clé révoquée, expirée, désactivée ou mal tapée échoue avec un 401 et le code de sortie 3.
• —me rotate donne un nouveau secret à la clé avec laquelle vous appelez. Elle demande keys:write, qu'une connexion par navigateur ne détient jamais, il lui faut donc une clé API. Tout le reste de la clé demeure, l'ancien secret cesse aussitôt de fonctionner, et un profil enregistré reçoit le nouveau, comme avec keys rotate. Une réponse perdue peut laisser la clé avec un secret que personne n'a vu, et elle a alors besoin d'un nouveau secret depuis l'application web.
• —openemail whoami montre la même réponse mise en forme pour des personnes.

openemail languages list affiche toute la table des langues en une réponse, environ deux cents lignes, avec le code de chaque langue, son nom anglais, son nom propre, son drapeau et si elle s'écrit de droite à gauche. Le code, le nom anglais ou le nom propre fonctionnent tous comme cible d'un envoi traduit. Elle demande une connexion mais aucun scope. openemail ai languages affiche la même table avec une option --search, et sans connexion elle affiche la table intégrée à la CLI.

Un membre détient deux choses qui ne sont jamais fusionnées. Son rôle dit ce qu'il peut faire, et ses accès aux adresses et aux domaines disent sur quel courrier il peut le faire, chaque accès avec son propre niveau : member lit et envoie, et viewer ne fait que lire. Un envoi a besoin des deux, donc un rôle avec emails:send et un accès viewer à une adresse ne permettent toujours pas d'envoyer depuis celle-ci. Un domaine entier couvre chaque adresse qu'il porte, y compris celles créées plus tard.

• —members list place le propriétaire de l'espace de travail en premier, marqué isOwner, laissez donc cette ligne de côté pour compter les places. Le propriétaire détient toutes les permissions et ne peut être ni invité, ni modifié, ni retiré, et personne qui est déjà dans l'espace de travail ne peut non plus être invité à nouveau : les deux donnent 422 member_is_owner.
• —Les personnes qui détiennent des accès à des adresses sans avoir jamais reçu de rôle reviennent avec implied: true, et leur rôle est déduit de leurs accès. members update leur en donne un véritable.
• —members add envoie une invitation, même à quelqu'un qui a déjà un compte. Rien n'est accordé avant l'acceptation, puis exactement le rôle, les adresses et les domaines que porte l'invitation. Inviter à nouveau la même adresse dans les dix minutes donne 409 invitation_too_soon, et après cela l'invitation en attente est rafraîchie au lieu d'en envoyer une seconde.
• —resend-invitation envoie un nouveau lien valable 14 jours de plus et retire l'ancien, ce qui renouvelle aussi une invitation expirée. revoke-invitation en retire une, et une invitation déjà acceptée donne 409 invitation_accepted, retirez donc plutôt le membre.
• —members update change le rôle et rien d'autre. grant-address donne une adresse ou change l'accès à celle-ci, donc la relancer avec un autre --access modifie l'accès au lieu d'en ajouter un second. revoke-address reprend une adresse et laisse le reste. Révoquer le dernier accès d'un membre implicite le retire de l'espace de travail.
• —members remove met fin à l'accès de quelqu'un à l'espace de travail, à son appartenance et à chaque accès, et indique dans addressesRevoked combien d'accès à des adresses ont disparu. Son compte et le courrier qu'il a envoyé restent intacts.

Un rôle est aussi un plafond pour les clés API émises sous lui. Ce qu'une clé peut faire, ce sont ses propres scopes réduits par les permissions de son rôle, recalculés à chaque requête.

• —roles list montre d'abord les rôles initiaux, dans l'ordre Owner, Admin, Member, Viewer, Developer et Billing, puis les rôles personnalisés par nom. Un espace de travail contient jusqu'à 24 rôles personnalisés, et au-delà roles create donne 422 role_limit_reached.
• —Un rôle stocke les permissions qu'impliquent ses permissions, donc templates:write stocke aussi templates:read, et roles:write apporte roles:read et members:read. Relisez la liste dans la réponse plutôt que de la supposer.
• —roles update --permissions remplace toute la liste, lisez donc le rôle, modifiez la liste et envoyez-la en entier. --description null efface la note. Un changement s'applique dès le prochain appel de chaque membre et de chaque clé qui détient le rôle.
• —Tous les rôles sauf Owner peuvent être renommés, réécrits et supprimés, rôles initiaux compris, et un rôle initial supprimé ne revient pas. Le rôle Owner répond à une modification par 409 role_immutable et à une suppression par 409 role_undeletable.
• —Tant qu'un membre, une clé API ou une invitation en attente détient un rôle, roles delete exige --reassign-to avec le rôle qui les reprend, sinon elle est refusée avec 409 role_in_use. Les clés révoquées pointent toujours vers leur rôle, donc un rôle dont le décompte apiKeys vaut 0 peut quand même l'exiger. La réponse indique les personnes reassigned et les clés keysReassigned.
• —roles list-permissions liste tout le vocabulaire avec un libellé et un groupe pour chaque entrée. Quelques-unes, comme billing:write et workspace:manage, reviennent avec scope: false : un rôle peut les détenir, mais aucune clé.

Une boîte jetable n'a besoin ni de compte ni de connexion. On l'atteint avec son propre jeton de boîte, qui commence par oe_inbox_ et revient une seule fois, à la création de la boîte. Utilisez openemail temp au quotidien, et openemail temp-mail quand il vous faut un champ ou une étape que temp ne montre pas, comme les prolongations restantes, une prolongation, ou les octets d'une pièce jointe.

• —Les deux gardent le jeton dans ~/.openemail/temp-mail.json, lisible par vous seul. temp new et temp-mail create l'enregistrent, temp list montre les boîtes créées par l'une ou l'autre voie, et les deux suppressions l'oublient. Une boîte enregistrée peut être désignée par son adresse partout où une commande demande son identifiant.
• —Pour une boîte que cette CLI n'a pas créée, passez le jeton avec --inbox-token. Sans jeton enregistré ni passé, la commande s'arrête avec le code de sortie 3 avant tout envoi.
• —Les deux commandes de création nomment leurs options différemment : temp new prend --name, --domain et --ttl, et temp-mail create prend --local-part, --domain et --ttl-minutes. Une partie locale compte de 3 à 32 lettres, chiffres, points, tirets ou tirets bas, commence et finit par une lettre ou un chiffre, et des noms comme postmaster sont refusés. La durée de location va de 1 à 1440 minutes, 60 par défaut.
• —Chaque adresse IP peut créer 6 boîtes par heure et 30 par jour, et la suivante donne 429 too_many_inboxes, code de sortie 8. Prolonger une boîte que vous détenez déjà ne compte pas, donc temp-mail extend est la réponse à cette limite.
• —temp-mail extend ajoute jusqu'à une heure, jamais au-delà de 24 heures après la création de la boîte, et au plus 23 fois. Lisez extensionsLeft dans la réponse. À 0, c'est 409 extension_limit pour de bon.
• —temp-mail list-messages lit de 1 à 50 messages par page, 50 par défaut, chacun avec un snippet en texte brut de jusqu'à 400 caractères qui contient souvent un code à usage unique. Rien au-delà d'une page n'est perdu, et --all parcourt chaque page.
• —Lire un message avec temp read, temp-mail get-message ou temp-mail list-attachments le marque comme vu. Un corps de plus de 2 Mo est tronqué, ce qu'indique truncated, et une pièce jointe de plus de 8 Mo n'a jamais été conservée, son content vaut donc null.
• —Supprimer une boîte supprime aussitôt son courrier, mais l'adresse reste réservée jusqu'à 7 jours après la fin prévue de sa location, et la redemander avant donne 409 address_taken.

openemail api <method> <path> envoie une requête par le même transport que toutes les autres commandes, donc votre profil ou votre clé, le renouvellement du jeton, les codes de vérification et les confirmations s'appliquent tous. Un chemin seul est un GET, et une réponse JSON s'affiche mise en forme. openemail api /keys/self est l'appel derrière me get.

• —-d, --data prend le corps en JSON en ligne, depuis un fichier avec @path, ou depuis stdin avec -. -q, --query et -H, --header prennent key=value et peuvent être répétées, et -o, --out enregistre la réponse telle quelle dans un fichier.
• —Un DELETE, et tout appel qu'une commande de ressource ferait confirmer, comme révoquer ou faire tourner une clé, demande d'abord confirmation, et sans surveillance il exige --yes.
• —Une requête en échec affiche l'erreur de l'API et sort avec le code correspondant.

L'espace de noms security n'est pas listé dans openemail --help, parce que openemail verify le pilote. Ses verbes step-up-status, begin-step-up et verify-step-up sont les appels que fait verify : verify --status lit l'état, et verify demande un code, vous invite à le saisir et le vérifie. Ils existent pour une connexion par navigateur. Avec une clé API, chacun est refusé avec 400 step_up_not_applicable, et openemail verify indique qu'une clé n'a jamais besoin de code.

openemail keys create --name 'Billing sender' --scopes emails:send \  --domain-allowlist billing.acme.com --expires-in-minutes 129600 --json \  | jq -r .token | openemail login --with-token --profile billingopenemail whoami --profile billing

Lancez-le avec une clé API qui détient keys:manage, par exemple via OPENEMAIL_API_KEY. Le secret passe directement de la réponse à un nouveau profil, sans jamais apparaître à l'écran ni dans un fichier. La clé ne peut envoyer que depuis billing.acme.com, et elle expire dans 90 jours.

openemail keys list --all | jq -r 'select(.status != "active") | [.name, .status, .lastUsedAt] | @tsv'openemail keys list-workspace-requests --failed-only --since 2026-09-26T00:00:00Z --all \  | jq -r '[.createdAt, .keyName, .status, .errorCode, .method, .path] | @tsv'

id=4c1b257a66287fd113bd89d0openemail keys update "$id" --no-enabledopenemail keys list-activity "$id" --since 2026-09-27T00:00:00Z --all | jq -r 'select(.type == "auth_failed") | .createdAt'openemail keys revoke "$id" --reason 'Contractor offboarded' --yesopenemail keys delete "$id" --yes

Désactiver d'abord la clé peut être annulé avec --enabled. Chaque appel qui la présente encore est refusé et apparaît dans son activité sous auth_failed, ce qui vous montre ce qui dépend encore d'elle. La révocation ne peut pas être annulée, et seule une clé révoquée peut être supprimée.

openemail roles list-permissions --json | jq -r '.[] | [.group, .id, .label] | @tsv'role=$(openemail roles create --name Support --permissions threads:write,emails:send,templates:read \  --description 'Answers help@ and nothing else.' --json | jq -r .id)openemail members add --email [email protected] --role-id "$role" \  --domain-ids 93542ff8-2baa-4f2f-841d-5ceaa074ab0d --access memberopenemail members list-invitations

Le rôle revient en détenant aussi threads:read et emails:read, parce que les permissions qu'il nomme les impliquent. Sam ne reçoit le rôle et le domaine entier qu'une fois l'invitation acceptée. Avec une connexion par navigateur, members add demande d'abord un code de vérification.

old=role_8b1f4c2e9a7d3b60e5f1a2c4new=role_2c7e9a1f4b8d3e60c5a7f1b9user=$(openemail members list --all | jq -r 'select(.email == "[email protected]") | .userId')openemail members update "$user" --role-id "$new"openemail roles get "$old" --json | jq '{name, members, apiKeys}'openemail roles delete "$old" --reassign-to "$new" --dry-runopenemail roles delete "$old" --reassign-to "$new" --yes

members et apiKeys sont comptés au moment où vous le demandez, ils montrent donc ce que la suppression va déplacer. La simulation affiche le DELETE avec reassignTo dans sa requête sans l'envoyer. Avec une connexion par navigateur, la mise à jour et la suppression demandent chacune un code de vérification, lancez donc d'abord openemail verify quand un script fait cela.

address=$(openemail temp new --ttl 15)openemail send --from [email protected] --to "$address" --subject 'Delivery check' --text 'Your code is 482913' --yesopenemail temp watch "$address" --first --json | jq -r .snippet | grep -oE '[0-9]{6}'openemail temp delete "$address" --yes

temp new n'affiche que l'adresse, elle tient donc dans une variable du shell, et temp watch --first s'arrête au premier message. Pointez un formulaire d'inscription vers l'adresse au lieu de openemail send pour intercepter son code de confirmation de la même façon.

• —Une connexion ou une clé sans le scope s'arrête avec le code de sortie 4, nomme le scope manquant et explique comment l'obtenir.
• —Celles-ci demandent confirmation : keys delete, rotate et revoke, me rotate, roles delete, members remove, revoke-address et revoke-invitation, temp delete, ainsi que temp-mail delete et delete-message. Répondre non sort avec le code 10 et ne change rien. Sans surveillance et sans --yes, elles s'arrêtent avec le code de sortie 2 avant tout envoi.
• —Avec une connexion par navigateur, roles update et roles delete, ainsi que members add, update, remove, grant-address et revoke-address, demandent aussi un code de vérification, sauf si cette connexion en a vérifié un dans les 60 dernières minutes. --yes ne le saute jamais, et sans surveillance personne ne peut le taper, donc la commande s'arrête avec le code de sortie 4. Lancez d'abord openemail verify. On ne demande jamais de code à une clé API.
• —--dry-run affiche la requête qu'un changement enverrait, avec son corps, et sort avec le code 0 sans l'envoyer ni vous demander de confirmer.
• —Une liste lit une page. --limit prend de 1 à 100 et le serveur en envoie 25 quand elle est omise, sauf dans temp-mail list-messages, qui prend de 1 à 50 et en envoie 50. --cursor prend le nextCursor de la page précédente. --all lit chaque page, --max <n> s'arrête après autant d'éléments, et --ndjson, ou --all dans un pipe, affiche un objet JSON par ligne. Avec --json, une liste affiche un seul document { items, hasMore, nextCursor }.
• —roles list-permissions, languages list, temp-mail list-domains et temp-mail list-attachments renvoient tout d'un coup, sous forme de simple tableau, sans pages.
• —Un refus sort avec le code de son statut : 3 pour un 401, comme une clé révoquée, 4 pour un 403, comme beyond_caller_authority ou owner_only, 5 pour un 404, 6 pour un 409, comme not_revoked, role_in_use ou invitation_too_soon, 7 pour un 400 ou un 422, comme member_is_owner ou role_limit_reached, et 8 pour un 429, comme too_many_inboxes.
• —Un changement qui ferait quelque chose deux fois n'est jamais relancé après une panne réseau : keys create et rotate, me rotate, roles create et delete, members add, remove, revoke-address et resend-invitation, ainsi que temp-mail create, extend, delete et delete-message. Vérifiez avant d'en relancer une. Les lectures, et les changements qui aboutissent au même résultat deux fois, comme keys update, keys revoke, roles update, members update et grant-address, sont relancés d'eux-mêmes.