Rollen auflisten
Jede Rolle im Workspace, die eingebauten zuerst, mit der Anzahl der Personen und Keys, die sie jeweils halten.
Führt den echten Aufruf gegen Ihren Workspace aus, mit Ihrem eigenen Schlüssel.
GET /roles
Jede Rolle im Workspace, die eingebauten zuerst, mit der Anzahl der Personen und Keys, die sie jeweils halten.
Zwei Achsen, und sie stellen nicht dieselbe Frage
export OE=https://api.openemail.ukexport AUTH="Authorization: Bearer $OPENEMAIL_API_KEY"Eine ROLLE sagt, was jemand in diesem Workspace TUN darf: Mail lesen, Mail senden, Templates bearbeiten, eine Domain hinzufügen. Eine ZUWEISUNG sagt, auf welche ADRESSEN sich das bezieht, und liegt nebenan unter /members/{userId}/addresses als member (liest die Adresse und sendet als sie) oder viewer (liest sie nur). Beide müssen übereinstimmen, bevor eine Nachricht rausgeht: Eine Rolle mit emails:send und ohne Zuweisungen kann von nichts aus senden, und jede Adresse im Workspace unter einer viewer-Zuweisung kann ebenfalls von nichts aus senden.
Jeder Workspace wird mit denselben sechs Rollen angelegt. Owner, Admin, Member und Viewer bilden eine Leiter. Jede hält alles, was die nächste hält, sodass eine Herabstufung den Zugriff verengt, statt ihn gegen einen anderen Ausschnitt zu tauschen. Developer und Billing sind keine Sprossen darauf: Developer baut Integrationen (Keys, Webhooks, Templates, Versand) und liest keine Mail des Workspace, und Billing sieht den Plan und die Rechnungen und sonst nichts. Beide liegen strikt innerhalb von Admin. Sie werden beim ersten Lesen angelegt und nicht bei der Erstellung des Workspace, sodass ein Workspace, der vor diesem Feature entstanden ist, sie in dem Moment erhält, in dem etwas danach fragt. builtin nennt, aus welcher Vorlage eine Zeile stammt, und mehr nennt es nicht: Die sechs sind ein Ausgangspunkt, den ein Workspace formen soll, und jede von ihnen außer Owner lässt sich umbenennen, neu berechtigen und löschen. Verzweigen Sie über editable und deletable statt über den Namen: Eine umbenannte Rolle beantwortet diese beiden weiterhin korrekt, während ihr Name nichts mehr aussagt.
Owner ist die einzige Ausnahme, und zwar eine Ausnahme in jede Richtung: editable: false, deletable: false, und als Ziel von PATCH /members/{userId} abgelehnt. Die Rolle beschreibt das Konto, auf das der Workspace ausgestellt ist, und hält jede Berechtigung, auch solche, die in einem späteren Release hinzukommen; deshalb wird ihre Liste berechnet und nicht gespeichert. Jemand anderen zum Owner zu machen ist eine Workspace-Übertragung; hier gibt es keinen Endpunkt, der das ausführt.
Die anderen fünf akzeptieren alles: eine neue Berechtigungsliste, eine neue Beschreibung, einen neuen Namen, ein DELETE. Sie sind vorbelegte Standardwerte und keine festen Vorgaben: Ein Workspace, der nie eine Integration baut, soll Developer loswerden können, und einer, in dem „Member“ etwas Engeres bedeutet, soll das mit eigenen Worten sagen können. Nur der Owner verweigert das, und er verweigert alles unter einem einzigen Code: role_immutable, ein 409 mit param: "roleId", gleich ob der PATCH einen Namen oder eine Berechtigungsliste enthielt. Eine Umbenennung allein wird nicht mehr abgelehnt, es gibt also keine param: "name"-Unveränderlichkeit mehr zu behandeln; der einzige 409, den ein Name noch auslösen kann, ist role_name_taken, wenn eine andere Rolle im Workspace bereits so heißt.
Über die sechs hinaus legt ein Workspace bis zu 24 eigene Rollen an. Die Obergrenze zählt nur diese, das Löschen einer vorbelegten Rolle schafft darunter also keinen Platz. Berechtigungen werden beim Schreiben EXPANDIERT statt wörtlich übernommen (templates:write allein wird als templates:read und templates:write gespeichert); lesen Sie die Liste daher aus der Antwort zurück, statt anzunehmen, es sei die, die Sie gesendet haben.
Eine Rolle ist außerdem die Obergrenze eines API-Keys. Ein Key, der gegen eine Rolle ausgestellt wurde, darf key.scopes ∩ role.permissions und nicht mehr, aufgelöst pro Anfrage an der Grenze; das Bearbeiten einer Rolle ändert also beim allernächsten Aufruf, was ihre Keys dürfen, und ein Key ohne Rolle hat überhaupt keine Obergrenze. Die Seite „Scopes“ hat das vollständig.
Beispiel
Benötigt roles:read. Ohne Cursor. Der Umschlag führt hasMore und nextCursor, damit ein Client ihn an denselben Listencode übergeben kann wie jede andere Collection; eine zweite Seite gibt es nie.
curl "$OE/roles" -H "$AUTH"{ "object": "list", "data": [ { "object": "role", "id": "role_1c94e05d3862c1f0a44b7f3a", "name": "Owner", "description": "The person the workspace belongs to. Holds everything, including additions.", "permissions": ["emails:send", "emails:read", "…", "workspace:manage"], "builtin": "owner", "editable": false, "deletable": false, "members": 0, "apiKeys": 2, "createdAt": "2026-08-01T09:00:00.000Z", "updatedAt": "2026-08-01T09:00:00.000Z" }, { "object": "role", "id": "role_c40a95f21cc65d31c2a89e07", "name": "Viewer", "description": "Reads the mail on the addresses they hold, and changes nothing.", "permissions": [ "emails:read", "drafts:read", "threads:read", "labels:read", "contacts:read", "calendar:read", "templates:read", "rules:read", "connections:read", "settings:read" ], "builtin": "viewer", "editable": true, "deletable": true, "members": 3, "apiKeys": 1, "createdAt": "2026-08-01T09:00:00.000Z", "updatedAt": "2026-08-01T09:00:00.000Z" } ], "hasMore": false, "nextCursor": null}Sortiert nach eingebautem Rang, dann nach Namen (owner, admin, member, viewer, developer, billing, danach der Rest alphabetisch), nicht neueste zuerst wie der Rest der API. Eine Berechtigungsmatrix wird als Leiter gelesen, und eine Sortierung nach createdAt setzt die weiteste Rolle jede Woche in eine andere Zeile.
Das Lesen dieser Liste ist es, was die sechs Rollen in einem Workspace ANLEGT, der noch keine hatte. Das Anlegen läuft auf einen Unique Index und tut beim zweiten Mal nichts, der Aufruf ist also idempotent und nur der erste schreibt; deshalb kann POST /members auch immer eine roleId nennen, die existiert.
Es wird EINMAL angelegt. Der Workspace vermerkt, dass er angelegt wurde, dieser Lesezugriff füllt also einen Workspace auf, der älter ist als das Feature, und schreibt danach nie wieder; genau das macht das Löschen einer vorbelegten Rolle dauerhaft. Ein früherer Build fügte bei jedem Lesen jede fehlende Vorlagenzeile erneut ein, sodass ein gelöschtes Billing beim nächsten Seitenaufruf unter einer neuen id zurückkam; das tut es nicht mehr.
members und apiKeys sind das, was verschoben werden müsste, bevor die Rolle gehen kann; deshalb kann ein Client warnen, bevor er das Löschen anbietet, statt erst nach dem 409. Die Owner-Zeile zeigt meist members: 0: Der Owner ist kein Mitglied des eigenen Workspace, sondern das Konto, auf das dieser ausgestellt ist.
Es gibt eine harte Obergrenze von 24 eigenen Rollen, genau damit dies eine einzige Antwort sein kann. Ein Workspace mit vierzig Rollen kann die Frage „Wer darf als billing@ senden?“ nicht durch Hinsehen beantworten, und das ist die einzige Frage, für die es das Feature überhaupt gibt.