Schlüssel, Mitglieder und Rollen

Diese Befehle entscheiden, wer und was den Workspace erreichen kann. openemail keys verwaltet API-Schlüssel und liest, was jeder getan hat, openemail members verwaltet die Personen im Workspace und ihre Einladungen, und openemail roles legt fest, was ein Mitglied oder ein Schlüssel tun darf. openemail me beschreibt den Schlüssel oder die Anmeldung, mit der Sie aufrufen, und openemail languages listet die Sprachen, die ein übersetzter Versand annimmt. Wegwerf-Postfächer brauchen überhaupt keine Anmeldung: openemail temp ist der alltägliche Weg, eines zu nutzen, und openemail temp-mail ist jeder Aufruf der API dahinter. openemail api erreicht jeden Endpunkt, den die anderen Befehle nicht erreichen.

• —Ein Schlüsselbefehl nimmt die Schlüssel-ID, die 24 Hexzeichen nach oe_live_, so wie keys list sie zeigt. Ein Mitgliedsbefehl nimmt die Konto-ID, userId in members list, nie eine E-Mail-Adresse. Ein Rollenbefehl nimmt eine role_-ID aus roles list, weil sich Rollen nicht nach Namen nachschlagen lassen.
• —Die Namespaces hören auch auf key, member, role, language und tempMail. Die üblichen Verb-Aliasse funktionieren, etwa ls, show, new, edit und rm. In members, dessen Verben add und remove heißen, führen new und create zu add, und rm, del und delete zu remove.
• —openemail <command> --help listet jedes Argument und Flag mit seinem Typ, dem Scope, den der Aufruf braucht, Methode und Pfad und dem, was zurückkommt. Fügen Sie --json hinzu, um dieselbe Seite als Daten zu erhalten.

Schlüssel zu lesen braucht keys:read, und jede Änderung braucht keys:manage. Eine Browser-Anmeldung bekommt nie keys:write oder keys:manage, daher braucht das Anlegen, Ändern, Rotieren, Widerrufen und Löschen von Schlüsseln einen API-Schlüssel mit keys:manage oder die Web-App (openemail open api-keys). Eine Browser-Anmeldung mit keys:read liest Schlüssel nur für den Eigentümer des Workspace, und die Anmeldung eines Mitglieds wird mit 403 owner_only abgelehnt.

• —keys create, keys rotate und me rotate geben das Geheimnis des Schlüssels einmal in token aus, und die CLI warnt dann, dass es nie wieder angezeigt wird. Jeder Lesezugriff zeigt stattdessen maskedKey.
• —Ohne Angaben hat ein neuer Schlüssel nur emails:send und übernimmt Rolle, Sendebereich und Ablauf des Schlüssels, der ihn anlegt. --domain-allowlist und --address-allowlist legen fest, als wen er senden darf, und --expires-in-minutes nimmt 5 bis 5.256.000, also zehn Jahre.
• —Ein Schlüssel erzeugt oder erreicht nie einen Schlüssel, der weiter reicht als er selbst. Scopes, Rolle, Ablauf, Modus und Sendebereich müssen alle innerhalb des aufrufenden Schlüssels liegen, sonst wird der Aufruf mit 403 beyond_caller_authority abgelehnt, und param nennt, was zu weit war. Ein Schlüssel, der auf einige Domains oder Adressen beschränkt ist, sieht nur die Schlüssel innerhalb seines eigenen Sendebereichs, und jeder andere ist ein 404.
• —keys update ersetzt, was Sie senden: --scopes, --address-allowlist und --domain-allowlist nehmen jeweils die ganze neue Liste, und ein weggelassenes Flag bleibt, wie es war. --no-enabled schaltet einen Schlüssel aus, sodass jeder Aufruf damit mit inactive_api_key abgelehnt wird, und --enabled stellt ihn genau wieder her. So stoppen Sie einen Schlüssel auf eine Weise, die sich rückgängig machen lässt.
• —keys revoke ist endgültig: Der Schlüssel lässt sich nie wieder einschalten, rotieren oder ändern. keys delete entfernt nur einen widerrufenen Schlüssel, und jeder andere wird mit 409 not_revoked abgelehnt. Anfrageprotokoll und Aktivität eines gelöschten Schlüssels bleiben, unter Deleted key.
• —keys rotate hat kein Überlappungsfenster, das alte Geheimnis funktioniert also in dem Moment nicht mehr, in dem das neue zurückkommt. Ist der Schlüssel der, den Ihr gespeichertes Profil nutzt, speichert die CLI das neue Geheimnis in diesem Profil, sodass es weiter funktioniert. Ein Schlüssel aus OPENEMAIL_API_KEY oder --api-key lässt sich nicht speichern, daher sagt Ihnen die CLI, dass Sie das neue Token dort ablegen sollen, wo der alte Schlüssel lag.

Das Anfrageprotokoll hält jeden Aufruf fest, den ein Schlüssel gemacht hat: Methode, Pfad, Status, Fehlercode, Dauer, IP und User-Agent, nie einen Body oder einen Query-String. Nichts wird bereinigt, es reicht also bis zum ersten Aufruf eines Schlüssels zurück, und Aufrufe mit einer Browser-Anmeldung stehen nicht darin. Das Aktivitätsprotokoll hält jede Änderung an einem Schlüssel fest und jeden Aufruf, der den Schlüssel vorgelegt hat und abgelehnt wurde, als auth_failed, mit dem Urheber jeder Änderung in actor.

• —list-requests und list-activity lesen einen Schlüssel. list-workspace-requests und list-workspace-activity lesen jeden Schlüssel, den Sie sehen können, oder bis zu 50, die --key-ids nennt, gelöschte Schlüssel eingeschlossen.
• —--since und --until behalten einen Zeitraum und nehmen eine ISO-8601-Zeit wie 2026-09-01T00:00:00Z. --failed-only behält die Aufrufe, die mit einem Status von 400 oder mehr beantwortet wurden.

openemail me get ist der erste Befehl, den Sie ausführen, wenn ein Aufruf abgelehnt wird. Er braucht keinen Scope, daher kann sich jeder gültige Schlüssel und jede gültige Anmeldung selbst beschreiben.

• —scopes ist das, was die Anmeldedaten gerade tun dürfen: die Scopes, mit denen sie angelegt wurden, beschnitten durch die Rolle, unter der sie ausgestellt wurden, bei jeder Anfrage neu berechnet. grantedScopes ist das, womit sie angelegt wurden, und roleId nennt die Rolle. Ein Scope, der in grantedScopes steht und in scopes fehlt, wurde von der Rolle entfernt. Das ist der übliche Grund für ein 403 insufficient_scope bei einem Schlüssel, der den Scope zu haben scheint, und die Lösung ist, die Rolle zu ändern, statt einen weiteren Schlüssel zu erzeugen.
• —domainAllowlist und addressAllowlist sagen, als wen sie senden dürfen. Sind beide null, ist es jede Adresse, die dem Workspace gehört.
• —Mit einer Browser-Anmeldung beschreibt er die Anmeldung: object ist oauth_token, clientId nennt die verbundene App dieser CLI, und expiresAt ist der Zeitpunkt, an dem Ihre Freigabe endet, oder null, wenn sie nie endet.
• —me ping antwortet mit ok: true und denselben Scope-Angaben, aber ohne die Allowlists, was zu einem Health-Check passt. Ein widerrufener, abgelaufener, ausgeschalteter oder falsch getippter Schlüssel scheitert mit einem 401 und Exit-Code 3.
• —me rotate gibt dem Schlüssel, mit dem Sie aufrufen, ein neues Geheimnis. Es braucht keys:write, das eine Browser-Anmeldung nie hat, also braucht es einen API-Schlüssel. Alles andere am Schlüssel bleibt, das alte Geheimnis funktioniert sofort nicht mehr, und ein gespeichertes Profil bekommt das neue, wie bei keys rotate. Eine verlorene Antwort kann den Schlüssel mit einem Geheimnis zurücklassen, das niemand gesehen hat, und er braucht dann ein neues aus der Web-App.
• —openemail whoami zeigt dieselbe Antwort, für Menschen formatiert.

openemail languages list gibt die ganze Sprachtabelle in einer Antwort aus, rund zweihundert Zeilen, mit Code, englischem Namen, Eigennamen, Flagge jeder Sprache und ob sie von rechts nach links geschrieben wird. Code, englischer Name und Eigenname funktionieren alle als Ziel eines übersetzten Versands. Es braucht eine Anmeldung, aber keinen Scope. openemail ai languages gibt dieselbe Tabelle mit einem --search-Flag aus und abgemeldet die Tabelle, die mit der CLI gebündelt ist.

Ein Mitglied hat zwei Dinge, die nie zusammengeführt werden. Seine Rolle sagt, was es tun darf, und seine Adress- und Domain-Freigaben sagen, mit welcher Mail es das tun darf, jede Freigabe mit eigenem Zugriff: member liest und sendet, und viewer liest nur. Ein Versand braucht beides, eine Rolle mit emails:send und eine viewer-Freigabe für eine Adresse können also trotzdem nicht von ihr senden. Eine ganze Domain deckt jede Adresse darauf ab, auch später angelegte.

• —members list setzt den Eigentümer des Workspace an erste Stelle, markiert mit isOwner, lassen Sie diese Zeile beim Zählen der Plätze also weg. Der Eigentümer hat jede Berechtigung und kann nicht eingeladen, geändert oder entfernt werden, und ebenso wenig kann jemand, der schon im Workspace ist, erneut eingeladen werden: Beides ist 422 member_is_owner.
• —Personen, die Adressfreigaben haben, denen aber nie eine Rolle gegeben wurde, kommen mit implied: true zurück, und ihre Rolle wird aus ihren Freigaben abgeleitet. members update gibt ihnen eine echte.
• —members add sendet eine Einladung, auch an jemanden, der schon ein Konto hat. Nichts wird gewährt, bis die Person annimmt, und dann genau die Rolle, die Adressen und die Domains, die die Einladung trägt. Dieselbe Adresse innerhalb von zehn Minuten erneut einzuladen ist 409 invitation_too_soon, und danach frischt es die wartende Einladung auf, statt eine zweite zu senden.
• —resend-invitation sendet einen neuen Link, der 14 weitere Tage gilt, und zieht den alten zurück, was auch eine abgelaufene Einladung erneuert. revoke-invitation zieht eine zurück, und eine bereits angenommene Einladung ist 409 invitation_accepted, entfernen Sie also stattdessen das Mitglied.
• —members update ändert die Rolle und sonst nichts. grant-address gibt eine Adresse oder ändert den Zugriff darauf, ein erneuter Aufruf mit einem anderen --access ändert also die Freigabe, statt eine zweite hinzuzufügen. revoke-address nimmt eine Adresse zurück und lässt den Rest. Wird die letzte Freigabe eines abgeleiteten Mitglieds widerrufen, wird es aus dem Workspace entfernt.
• —members remove beendet den Zugriff einer Person auf den Workspace, ihre Mitgliedschaft und jede Freigabe, und meldet in addressesRevoked, wie viele Adressfreigaben entfielen. Ihr Konto und die Mail, die sie gesendet hat, bleiben unberührt.

Eine Rolle ist auch eine Obergrenze für die API-Schlüssel, die unter ihr ausgestellt werden. Was ein Schlüssel tun darf, sind seine eigenen Scopes, beschnitten durch die Berechtigungen seiner Rolle, bei jeder Anfrage neu berechnet.

• —roles list zeigt zuerst die vorbelegten Rollen in der Reihenfolge Owner, Admin, Member, Viewer, Developer und Billing, dann eigene Rollen nach Namen. Ein Workspace fasst bis zu 24 eigene Rollen, und darüber hinaus ist roles create 422 role_limit_reached.
• —Eine Rolle speichert die Berechtigungen, die ihre Berechtigungen einschließen, templates:write speichert also auch templates:read, und roles:write bringt roles:read und members:read mit. Lesen Sie die Liste aus der Antwort zurück, statt sie anzunehmen.
• —roles update --permissions ersetzt die ganze Liste, lesen Sie also die Rolle, ändern Sie die Liste und senden Sie sie vollständig. --description null löscht die Notiz. Eine Änderung gilt beim nächsten Aufruf jedes Mitglieds und Schlüssels, das die Rolle innehat.
• —Jede Rolle außer Owner lässt sich umbenennen, neu schreiben und löschen, vorbelegte eingeschlossen, und eine gelöschte vorbelegte Rolle kommt nicht zurück. Die Owner-Rolle beantwortet eine Bearbeitung mit 409 role_immutable und ein Löschen mit 409 role_undeletable.
• —Solange ein Mitglied, ein API-Schlüssel oder eine wartende Einladung eine Rolle innehat, braucht roles delete --reassign-to mit der Rolle, die sie übernimmt, sonst wird es mit 409 role_in_use abgelehnt. Widerrufene Schlüssel verweisen weiter auf ihre Rolle, daher kann eine Rolle, deren apiKeys-Zahl 0 ist, es trotzdem brauchen. Die Antwort meldet reassigned Personen und keysReassigned Schlüssel.
• —roles list-permissions listet das ganze Vokabular mit Bezeichnung und Gruppe für jeden Eintrag. Einige, etwa billing:write und workspace:manage, kommen mit scope: false zurück: Eine Rolle kann sie haben, aber kein Schlüssel.

Ein Wegwerf-Postfach braucht kein Konto und keine Anmeldung. Es wird mit seinem eigenen Postfach-Token erreicht, das mit oe_inbox_ beginnt und einmal zurückkommt, wenn das Postfach angelegt wird. Nutzen Sie im Alltag openemail temp und openemail temp-mail, wenn Sie ein Feld oder einen Schritt brauchen, den temp nicht zeigt, etwa die verbleibenden Verlängerungen, eine Verlängerung oder die Bytes eines Anhangs.

• —Beide halten das Token in ~/.openemail/temp-mail.json, nur für Sie lesbar. temp new und temp-mail create speichern es, temp list zeigt Postfächer, die auf beiden Wegen angelegt wurden, und beide Löschbefehle vergessen es. Ein gespeichertes Postfach lässt sich überall, wo ein Befehl nach seiner ID fragt, mit seiner Adresse benennen.
• —Für ein Postfach, das diese CLI nicht angelegt hat, übergeben Sie das Token mit --inbox-token. Ohne gespeichertes oder übergebenes Token bricht der Befehl mit Exit-Code 3 ab, bevor etwas gesendet wird.
• —Die beiden Befehle zum Anlegen benennen ihre Flags unterschiedlich: temp new nimmt --name, --domain und --ttl, und temp-mail create nimmt --local-part, --domain und --ttl-minutes. Ein Local-Part hat 3 bis 32 Buchstaben, Ziffern, Punkte, Bindestriche oder Unterstriche, beginnt und endet mit einem Buchstaben oder einer Ziffer, und Namen wie postmaster werden abgelehnt. Die Laufzeit beträgt 1 bis 1440 Minuten, standardmäßig 60.
• —Jede IP-Adresse kann 6 Postfächer pro Stunde und 30 pro Tag anlegen, und das nächste ist 429 too_many_inboxes, Exit-Code 8. Das Verlängern eines Postfachs, das Sie schon haben, zählt nicht, daher ist temp-mail extend die Antwort auf dieses Limit.
• —temp-mail extend fügt bis zu eine Stunde hinzu, nie über 24 Stunden nach dem Anlegen des Postfachs hinaus, und höchstens 23 Mal. Lesen Sie extensionsLeft aus der Antwort. Bei 0 ist es endgültig 409 extension_limit.
• —temp-mail list-messages liest 1 bis 50 Nachrichten pro Seite, standardmäßig 50, jede mit einem Klartext-snippet von bis zu 400 Zeichen, das oft einen Einmalcode enthält. Nichts jenseits einer Seite geht verloren, und --all geht jede Seite durch.
• —Eine Nachricht mit temp read, temp-mail get-message oder temp-mail list-attachments zu lesen, markiert sie als gesehen. Ein Body über 2 MB wird gekürzt, was truncated angibt, und ein Anhang über 8 MB wurde nie aufbewahrt, sein content ist also null.
• —Das Löschen eines Postfachs löscht seine Mail sofort, aber die Adresse bleibt bis 7 Tage nach dem Ende ihrer Laufzeit reserviert, und wer sie vorher erneut anfordert, bekommt 409 address_taken.

openemail api <method> <path> sendet eine Anfrage über denselben Transport wie jeder andere Befehl, daher gelten Ihr Profil oder Schlüssel, die Token-Erneuerung, Bestätigungscodes und Bestätigungen. Ein Pfad allein ist ein GET, und eine JSON-Antwort wird formatiert ausgegeben. openemail api /keys/self ist der Aufruf hinter me get.

• —-d, --data nimmt den Body als Inline-JSON, aus einer Datei mit @path oder von stdin mit -. -q, --query und -H, --header nehmen key=value und lassen sich wiederholen, und -o, --out speichert die Antwort unverändert in einer Datei.
• —Ein DELETE und jeder Aufruf, den ein Ressourcenbefehl bestätigen ließe, etwa das Widerrufen oder Rotieren eines Schlüssels, fragt zuerst nach einer Bestätigung, und unbeaufsichtigt braucht er --yes.
• —Eine gescheiterte Anfrage gibt den API-Fehler aus und endet mit dem passenden Code.

Der Namespace security steht nicht in openemail --help, weil openemail verify ihn steuert. Seine Verben step-up-status, begin-step-up und verify-step-up sind die Aufrufe, die verify macht: verify --status liest den Status, und verify fordert einen Code an, fragt Sie danach und prüft ihn. Sie existieren für eine Browser-Anmeldung. Mit einem API-Schlüssel wird jeder mit 400 step_up_not_applicable abgelehnt, und openemail verify sagt, dass ein Schlüssel nie einen Code braucht.

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

Führen Sie es mit einem API-Schlüssel aus, der keys:manage hat, zum Beispiel über OPENEMAIL_API_KEY. Das Geheimnis geht aus der Antwort direkt in ein neues Profil, sodass es nie auf dem Bildschirm oder in einer Datei landet. Der Schlüssel kann nur von billing.acme.com senden und läuft in 90 Tagen ab.

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

Den Schlüssel zuerst auszuschalten lässt sich mit --enabled rückgängig machen. Jeder Aufruf, der ihn noch vorlegt, wird abgelehnt und erscheint in seiner Aktivität als auth_failed, was Ihnen zeigt, was noch von ihm abhängt. Widerrufen lässt sich nicht rückgängig machen, und nur ein widerrufener Schlüssel lässt sich löschen.

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

Die Rolle kommt zusätzlich mit threads:read und emails:read zurück, weil die Berechtigungen, die sie nennt, diese einschließen. Sam bekommt die Rolle und die ganze Domain erst, sobald die Einladung angenommen ist. Mit einer Browser-Anmeldung fragt members add zuerst nach einem Bestätigungscode.

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 und apiKeys werden bei der Abfrage gezählt, sie zeigen also, was das Löschen verschieben wird. Der Probelauf gibt das DELETE mit reassignTo in seiner Query aus, ohne es zu senden. Mit einer Browser-Anmeldung fragen das Update und das Löschen jeweils nach einem Bestätigungscode, führen Sie also zuerst openemail verify aus, wenn ein Skript das tut.

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 gibt nur die Adresse aus, sie passt also in eine Shell-Variable, und temp watch --first hört bei der ersten Nachricht auf. Richten Sie statt openemail send ein Anmeldeformular auf die Adresse, um dessen Bestätigungscode auf dieselbe Weise abzufangen.

• —Eine Anmeldung oder ein Schlüssel ohne den Scope bricht mit Exit-Code 4 ab, nennt den fehlenden Scope und sagt, wie Sie ihn bekommen.
• —Diese bitten um Bestätigung: keys delete, rotate und revoke, me rotate, roles delete, members remove, revoke-address und revoke-invitation, temp delete sowie temp-mail delete und delete-message. Eine Antwort mit Nein endet mit Exit-Code 10 und ändert nichts. Unbeaufsichtigt und ohne --yes brechen sie mit Exit-Code 2 ab, bevor etwas gesendet wird.
• —Mit einer Browser-Anmeldung fragen roles update und roles delete sowie members add, update, remove, grant-address und revoke-address außerdem nach einem Bestätigungscode, sofern diese Anmeldung nicht in den letzten 60 Minuten einen bestätigt hat. --yes überspringt ihn nie, und unbeaufsichtigt kann ihn niemand eingeben, daher bricht der Befehl mit Exit-Code 4 ab. Führen Sie zuerst openemail verify aus. Ein API-Schlüssel wird nie gefragt.
• —--dry-run gibt die Anfrage aus, die eine Änderung senden würde, mit ihrem Body, und endet mit Exit-Code 0, ohne sie zu senden oder um Bestätigung zu bitten.
• —Eine Liste liest eine Seite. --limit nimmt 1 bis 100, und der Server sendet 25, wenn es fehlt, außer bei temp-mail list-messages, das 1 bis 50 nimmt und 50 sendet. --cursor nimmt den nextCursor der vorigen Seite. --all liest jede Seite, --max <n> hört nach so vielen Einträgen auf, und --ndjson oder --all in einer Pipe gibt ein JSON-Objekt pro Zeile aus. Mit --json gibt eine Liste ein einziges { items, hasMore, nextCursor }-Dokument aus.
• —roles list-permissions, languages list, temp-mail list-domains und temp-mail list-attachments geben alles auf einmal zurück, als einfaches Array, ohne Seiten.
• —Eine Ablehnung endet mit dem Code ihres Status: 3 für ein 401, etwa bei einem widerrufenen Schlüssel, 4 für ein 403, etwa beyond_caller_authority oder owner_only, 5 für ein 404, 6 für ein 409, etwa not_revoked, role_in_use oder invitation_too_soon, 7 für ein 400 oder ein 422, etwa member_is_owner oder role_limit_reached, und 8 für ein 429, etwa too_many_inboxes.
• —Eine Änderung, die zweimal ausgeführt etwas doppelt täte, wird nach einem Netzwerkfehler nie wiederholt: keys create und rotate, me rotate, roles create und delete, members add, remove, revoke-address und resend-invitation sowie temp-mail create, extend, delete und delete-message. Prüfen Sie, bevor Sie einen davon erneut ausführen. Lesezugriffe und Änderungen, die zweimal ausgeführt dasselbe Ergebnis haben, etwa keys update, keys revoke, roles update, members update und grant-address, werden von selbst wiederholt.