client.Roles

Cada método de este espacio de nombres: su firma, sus parámetros, lo que devuelve y un ejemplo.

Métodos

What a member or an API key may do, drawn from one permission vocabulary.

`Roles.ListAsync`

List every role in the workspace

roles:readRecorre los resultados por páginas

Firma

Task<Page> ListAsync(    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of the roles the workspace defines. Roles.ListAllAsync collects every page and Roles.IterateAsync walks them lazily. The seeded roles come first in ladder order (Owner, Admin, Member, Viewer, Developer, Billing) and custom roles follow alphabetically. The order is read from builtin, so a renamed seeded role keeps its place.

A workspace older than roles has no role rows, and the first read seeds them instead of returning an empty list. Seeding runs once per workspace, and afterwards only the owner role is ever restored, so a seeded role you delete stays deleted. Each row carries members and apiKeys counts computed at read time.

A role is a ceiling for the keys issued under it. What a key may do is its own scopes intersected with its role's permissions, resolved on every request, so a key holding emails:send under a role without it cannot send. A key with no role has no ceiling.

Parámetros

limitint?: Page size, from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor of the previous page. Leave it out for the first page.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

A Page of role objects, with items, hasMore and nextCursor. Each item has id, name, description, permissions, builtin, editable, deletable, members, apiKeys, createdAt and updatedAt.

Ejemplo

var page = await client.Roles.ListAsync(); foreach (var role in page){    Console.WriteLine($"{role["name"]}: {role["members"]} members, {role["apiKeys"]} keys{((bool?)role["deletable"] == true ? "" : ", cannot be deleted")}");} if (page.HasMore){    Console.WriteLine($"More roles after {page.NextCursor}");}

Notas

Branch on editable and deletable rather than on builtin. Both are false only for the owner role.
members counts people with an explicit membership, so implied members from Members.ListAsync are not counted. apiKeys counts unrevoked keys only.
A workspace holds at most 24 custom roles. Seeded roles do not count toward that.
The cursor is opaque and holds where the last row sat in this order, so a row deleted or edited between pages never breaks the walk: the next page starts at the first row that sorts after it. A cursor this list did not hand out is a 400 invalid_cursor.

También disponible en

API: GET /roles
TypeScript: roles.list()
Python: roles.list()
Ruby: roles.list
PHP: roles->list
Go: Roles.List
Java: roles().list
CLI: openemail roles list

`Roles.ListAllAsync`

Collect every role into one object

roles:readRecorre los resultados por páginas

Firma

Task<IReadOnlyList<JsonObject>> ListAllAsync(    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Walks every page of Roles.ListAsync and returns all roles in one object, seeded roles first in ladder order, then custom roles alphabetically. One request per page.

Parámetros

limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

A list of role objects holding every role, each with the fields Roles.ListAsync returns.

Ejemplo

var roles = await client.Roles.ListAllAsync(limit: 100); Console.WriteLine(roles.Count);

Notas

If any page fails, the exception is thrown and the roles already fetched are discarded.

También disponible en

API: GET /roles
TypeScript: roles.listAll()
Python: roles.list_all()
Ruby: roles.list_all
PHP: roles->listAll
Go: Roles.ListAll
Java: roles().listAll

`Roles.IterateAsync`

Stream the roles one at a time

roles:readRecorre los resultados por páginas

Firma

IAsyncEnumerable<JsonObject> IterateAsync(    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> that yields roles one at a time, seeded roles first in ladder order, then custom roles alphabetically, and requests the next page only once the current one is used up. Nothing is fetched until the loop starts, and breaking out of the await foreach stops the requests.

Parámetros

limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

An IAsyncEnumerable<JsonObject> that yields one role per step.

Ejemplo

await foreach (var role in client.Roles.IterateAsync()){    Console.WriteLine(role["id"]);}

Notas

The generator is lazy, so an abandoned loop costs only the pages you consumed.

También disponible en

API: GET /roles
TypeScript: roles.iterate()
Python: roles.iterate()
Ruby: roles.iterate
PHP: roles->iterate
Go: Roles.Iterate
Java: roles().iterate

`Roles.GetAsync`

Read one role with its usage counts

roles:read

Firma

Task<JsonObject> GetAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns a single role by id. There is no lookup by name, because every role's name except the owner's can be edited.

members and apiKeys are counted when you call rather than stored, so they describe what a deletion would have to move right now. permissions is the stored list with implied permissions already expanded, in canonical order, so it can be longer than what was sent when the role was written.

Parámetros

idstringObligatorio: Role id, role_ followed by 24 hex characters. Roles have no lookup by name.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

A JsonObject with permissions, builtin, the editable and deletable flags, and live members and apiKeys counts.

Ejemplo

var role = await client.Roles.GetAsync("role_8b1f4c2e9a7d3b60e5f1a2c4"); Console.WriteLine($"{role["name"]} grants {string.Join(", ", role["permissions"]?.AsArray() ?? [])}");Console.WriteLine($"Deleting it would move {role["members"]} members and {role["apiKeys"]} keys");

Notas

An unknown id, or one from another workspace, is 404 role_not_found with param set to roleId. The two answer the same way on purpose, so a 404 does not tell you whether the role exists somewhere else.
builtin records which template a row was seeded from and survives a rename. It is provenance and sort order, not protection.

También disponible en

API: GET /roles/{id}
TypeScript: roles.get()
Python: roles.get()
Ruby: roles.get
PHP: roles->get
Go: Roles.Get
Java: roles().get
CLI: openemail roles get

`Roles.CreateAsync`

Create a custom role

roles:write

Firma

Task<JsonObject> CreateAsync(    IReadOnlyDictionary<string, object?> body,    string? apiKey = null,    CancellationToken cancellationToken = default)

Writes a role the workspace defines for itself. builtin comes back null and both usage counts are zero. Only roles like this count toward the ceiling of 24 custom roles, past which the call is 422 role_limit_reached.

Implied permissions are expanded as the role is stored, so templates:write alone comes back holding templates:read too, and roles:write brings roles:read and members:read. Read the final list off the result rather than the request. A string that is not in the vocabulary is refused with 422 invalid_parameter rather than dropped.

Be careful with roles:write. Authority is resolved per request, so a key holding it can edit the very role that caps it and widen itself on the next call. Keep it off keys that only need to read.

Parámetros

namestringObligatorio: At most 48 characters after trimming, unique per workspace ignoring case. Blank is a 422.
permissionslistObligatorio: What the role grants, drawn from Roles.ListPermissionsAsync. The key scopes are also in OpenEmail\Constants\ApiScopes. An empty dictionary is accepted and makes a role that can do nothing.
descriptionstring: One sentence about who the role is for, at most 240 characters. Blank is stored as null.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

A JsonObject for the role with the expanded permissions, builtin null, editable and deletable true, and members and apiKeys at 0.

Ejemplo

using OpenEmail.Constants; var support = await client.Roles.CreateAsync(new Body{    ["name"] = "Support",    ["description"] = "Answers help@ and nothing else.",    ["permissions"] = new[] { ApiScopes.ThreadsWrite, ApiScopes.EmailsSend, ApiScopes.TemplatesRead },}); Console.WriteLine($"{support["id"]}: {string.Join(", ", support["permissions"]?.AsArray() ?? [])}");

Notas

A name that matches an existing role ignoring case, seeded roles included, is 409 role_name_taken with param set to name.
A permission the calling key or access token does not hold is refused with 403 insufficient_authority. None of them can hold a console-only permission, the ones Roles.ListPermissionsAsync returns with scope false, so a role with addresses:all, billing:write or workspace:manage in it is written in the app, never through the API.
Not retried automatically. After a network failure the role may already exist, and creating it again is role_name_taken.

También disponible en

API: POST /roles
TypeScript: roles.create()
Python: roles.create()
Ruby: roles.create
PHP: roles->create
Go: Roles.Create
Java: roles().create
CLI: openemail roles create

`Roles.UpdateAsync`

Rename a role or replace what it grants

roles:write

Firma

Task<JsonObject> UpdateAsync(    string id,    IReadOnlyDictionary<string, object?> patch,    string? apiKey = null,    CancellationToken cancellationToken = default)

Patches the name, description or permission list of a role. Every seeded role except Owner takes all three, so renaming Billing to Finance and rewriting what it grants is an ordinary update. The owner role refuses any edit with 409 role_immutable.

permissions replaces the whole list and is expanded with implied permissions on the way in. There is no way to add or remove one entry, so read the role, change the object and send all of it. Leave a field out to keep it, and send ["description"] = null to clear the note.

The change is live. Authority is resolved on every request, so narrowing a role takes effect for its members and keys on their next call without rotating anything, and widening it takes effect just as fast.

Parámetros

idstringObligatorio: Role id, role_ followed by 24 hex characters. Roles have no lookup by name.
namestring: New name, at most 48 characters after trimming and unique per workspace ignoring case. Blank is a 422.
descriptionstring: New note of at most 240 characters. Null or blank clears it.
permissionslist: Complete replacement list, expanded with implied permissions before it is stored.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

A JsonObject for the role as saved, with live members and apiKeys counts.

Ejemplo

using OpenEmail.Constants; var role = await client.Roles.GetAsync("role_8b1f4c2e9a7d3b60e5f1a2c4");var permissions = new List<object?>(role["permissions"]?.AsArray() ?? []) { ApiScopes.DomainsRead }; var updated = await client.Roles.UpdateAsync(role["id"]!.GetValue<string>(), new Body { ["name"] = "Finance", ["permissions"] = permissions }); Console.WriteLine($"{updated["name"]}: {string.Join(", ", updated["permissions"]?.AsArray() ?? [])}");

Notas

A new name that clashes with another role ignoring case is 409 role_name_taken. builtin does not change with the name, which keeps a renamed seeded role in its place in Roles.ListAsync.
An empty patch is accepted and only moves updatedAt.
Adding a permission the calling key or access token does not hold is 403 insufficient_authority, and none of them holds a console-only one such as addresses:all. One the role already holds stays only if you send it back, and a console-only one cannot be added back through the API, so send back every entry you read.
Retried automatically on network failure and retryable statuses, since the same patch lands on the same row.

También disponible en

API: PATCH /roles/{id}
TypeScript: roles.update()
Python: roles.update()
Ruby: roles.update
PHP: roles->update
Go: Roles.Update
Java: roles().update
CLI: openemail roles update

`Roles.DeleteAsync`

Delete a role and move whoever holds it

roles:write

Firma

Task<JsonObject> DeleteAsync(    string id,    string? reassignTo = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Deletes a role. Every role except Owner can go, seeded ones included, and deleting a seeded role is permanent because seeding never runs twice. The owner role is refused with 409 role_undeletable.

While any member, API key or unanswered invitation still points at the role, the call needs reassignTo: and is refused with 409 role_in_use without it. The server will not guess, because a key whose role vanished would fall back to no ceiling at all, which is wider than the role being removed. Members, keys and pending invitations move to the named role in one transaction. A role nobody holds deletes without it.

The tombstone reports reassigned people and keysReassigned keys separately. Log the second: those programs keep running under a new ceiling and nobody is told.

Parámetros

idstringObligatorio: Role id, role_ followed by 24 hex characters. Roles have no lookup by name.
reassignTostring?: Id of the role that inherits the members, keys and pending invitations. Required whenever the role is held. Sent as a query parameter.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

A JsonObject with object set to role, the id, deleted set to true, reassigned and keysReassigned.

Ejemplo

var roles = await client.Roles.ListAllAsync();var viewer = roles.FirstOrDefault(role => (string?)role["builtin"] == "viewer"); var deleted = await client.Roles.DeleteAsync("role_8b1f4c2e9a7d3b60e5f1a2c4", reassignTo: (string?)viewer?["id"]); Console.WriteLine($"{deleted["reassigned"]} people and {deleted["keysReassigned"]} keys moved");

Notas

Naming the owner role in reassignTo: is 409 role_immutable, naming the role being deleted is 409 role_in_use, and an id that names no role on this workspace is 404 role_not_found with param set to roleId, whether it was the id being deleted or the one in reassignTo:.
Revoked API keys still point at their role. A role whose apiKeys count is 0 can therefore still need reassignTo:, and those keys are included in keysReassigned.
Pending invitations are moved as well but are not counted in the response.
Not retried automatically. A retry after a lost response is a 404, since the role is already gone.

También disponible en

API: DELETE /roles/{id}
TypeScript: roles.delete()
Python: roles.delete()
Ruby: roles.delete
PHP: roles->delete
Go: Roles.Delete
Java: roles().delete
CLI: openemail roles delete

`Roles.ListPermissionsAsync`

List the permission vocabulary roles are written in

roles:read

Firma

Task<IReadOnlyList<JsonObject>> ListPermissionsAsync(    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns every permission as a plain list, in the canonical order a stored role's permissions also uses. Each entry carries the label to show beside a checkbox and the group heading it belongs under, so a permission matrix can be rendered from this rather than from a list copied into your code.

scope is the field to branch on. Permissions and API key scopes share one alphabet, which is what lets a role cap a key, but they are not the same set. Six are console-only. addresses:all lets a role reach every address on every domain of the workspace, including ones added later, with no grant, billing:read and billing:write say who may see or change the plan, and workspace:manage who may manage the workspace. api-keys:read and api-keys:write are listed too, but API keys stay with the workspace owner whatever a role holds. No key or access token can ever hold any of the six, so they come back with scope false. Filter on scope for a key scope picker and ignore it for a role editor.

Parámetros

apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Devuelve

A list of JsonObject items, each with id, label, group and scope.

Ejemplo

var permissions = await client.Roles.ListPermissionsAsync(); foreach (var group in permissions.GroupBy(permission => (string?)permission["group"])){    var ids = group.Select(permission => permission["id"] + ((bool?)permission["scope"] == true ? string.Empty : " (console only)"));     Console.WriteLine($"{group.Key}: {string.Join(", ", ids)}");}

Notas

group is one of addresses, mail, organising, writing, workspace, people or developer, with other as the fallback for a permission not yet placed in a group.
The list is the same for every workspace, yet the call still requires roles:read.

También disponible en

API: GET /roles/permissions
TypeScript: roles.listPermissions()
Python: roles.list_permissions()
Ruby: roles.list_permissions
PHP: roles->listPermissions
Go: Roles.ListPermissions
Java: roles().listPermissions
CLI: openemail roles list-permissions

client.Roles

Métodos

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Parámetros

Devuelve

Ejemplo

Notas

También disponible en

Tu bandeja de entrada,en tus propios términos.

Tu bandeja de entrada,
en tus propios términos.