Listar funções
Todas as funções do espaço de trabalho, as integradas primeiro, com quantas pessoas e chaves têm cada uma.
Executa a chamada real contra o seu espaço de trabalho, com a sua própria chave.
GET /roles
Todas as funções do espaço de trabalho, as integradas primeiro, com quantas pessoas e chaves têm cada uma.
Dois eixos, e não são a mesma pergunta
export OE=https://api.openemail.ukexport AUTH="Authorization: Bearer $OPENEMAIL_API_KEY"Uma FUNÇÃO diz o que alguém PODE FAZER neste espaço de trabalho: ler correio, enviá-lo, editar modelos, adicionar um domínio. Uma CONCESSÃO diz a que ENDEREÇOS o pode fazer, e vive ao lado em /members/{userId}/addresses como member (lê o endereço e envia como ele) ou viewer (apenas o lê). Ambas têm de concordar antes de uma mensagem sair: uma função com emails:send e sem concessões pode enviar a partir de nada, e todos os endereços do espaço de trabalho sob uma concessão de viewer também podem enviar a partir de nada.
Todos os espaços de trabalho são pré-criados com as mesmas seis funções. Owner, Admin, Member e Viewer formam uma escada. Cada uma tem tudo o que a seguinte tem, por isso despromover alguém estreita o seu acesso em vez de o trocar por uma fatia diferente. Developer e Billing não são degraus dela: Developer constrói integrações (chaves, webhooks, modelos, envio) e não lê nada do correio do espaço de trabalho, e Billing vê o plano e as faturas e mais nada. Ambas ficam estritamente dentro de Admin. São criadas na primeira leitura e não na criação do espaço de trabalho, por isso um espaço de trabalho feito antes de esta funcionalidade existir ganha-as no momento em que alguma coisa as pedir. builtin nomeia de que modelo veio uma linha, e é só isso que nomeia: as seis são um ponto de partida que um espaço de trabalho deve moldar, e todas elas menos Owner podem ser renomeadas, repermissionadas e eliminadas. Decida com base em editable e deletable e não no nome: uma função que alguém renomeou continua a responder corretamente a esses dois, e o seu nome já não lhe diz nada.
Owner é a única exceção, e é uma exceção em todas as direções: editable: false, deletable: false, e recusada como destino em PATCH /members/{userId}. Descreve a conta em que o espaço de trabalho está ancorado e tem todas as permissões, incluindo as que forem acrescentadas numa versão futura, e é por isso que a sua lista é calculada em vez de guardada. Tornar outra pessoa proprietária é uma transferência de espaço de trabalho; não há aqui endpoint que a execute.
As outras cinco aceitam tudo: uma nova lista de permissões, uma nova descrição, um novo nome, um DELETE. São predefinições pré-criadas e não peças fixas: um espaço de trabalho que nunca constrói uma integração deve poder livrar-se de Developer, e um onde "Member" significa algo mais estreito deve poder dizê-lo por palavras suas. Só o proprietário recusa, e recusa tudo sob um único código: role_immutable, um 409 com param: "roleId", quer o PATCH trouxesse um nome quer uma lista de permissões. Já não há nenhuma mudança de nome recusada por si só, por isso não há nenhuma imutabilidade com param: "name" a tratar; o único 409 que um nome ainda pode levantar é role_name_taken, quando outra função do espaço de trabalho já responde por ele.
Para além das seis, um espaço de trabalho escreve até 24 funções próprias. O tecto conta apenas essas, por isso eliminar uma função pré-criada não compra espaço debaixo dele. As permissões são EXPANDIDAS à entrada em vez de tomadas à letra (templates:write sozinha fica guardada como templates:read e templates:write), por isso leia a lista de volta na resposta em vez de assumir que é a que enviou.
Uma função é também o tecto de uma chave de API. Uma chave emitida contra uma delas pode fazer key.scopes ∩ role.permissions e mais nada, resolvido por pedido na fronteira, por isso editar uma função muda o que as suas chaves podem fazer logo na chamada seguinte, e uma chave sem função não tem tecto nenhum. A página Âmbitos tem isso tudo.
Exemplo
Requer roles:read. Sem cursor. O envelope traz hasMore e nextCursor para que um cliente o possa entregar ao mesmo código de listagem de todas as outras coleções, e nunca há segunda página.
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}Ordenadas pela posição das integradas e depois por nome (owner, admin, member, viewer, developer, billing, e depois as restantes por ordem alfabética) e não das mais recentes primeiro como o resto da API. Uma matriz de permissões lê-se como uma escada, e ordená-la por createdAt põe a função mais ampla numa linha diferente todas as semanas.
Ler esta lista é o que PRÉ-CRIA as seis num espaço de trabalho que nunca teve nenhuma. A pré-criação entra em conflito num índice único e não faz nada à segunda vez, por isso a chamada é idempotente e só a primeira escreve, que é também a razão pela qual POST /members pode sempre nomear um roleId existente.
Pré-cria UMA vez. O espaço de trabalho regista que já foi pré-criado, por isso esta leitura preenche um espaço de trabalho mais antigo do que a funcionalidade e depois nunca mais escreve, que é o que torna permanente a eliminação de uma função pré-criada. Uma versão anterior voltava a inserir a linha modelo que faltasse em cada leitura, e por isso um Billing eliminado voltava com um id novo no carregamento de página seguinte; já não é assim.
members e apiKeys são o que teria de ser movido antes de a função poder desaparecer, que é o que permite a um cliente avisar antes de oferecer a eliminação em vez de depois do 409. A linha do proprietário costuma dizer members: 0: o proprietário não é membro do seu próprio espaço de trabalho, é a conta em que ele está ancorado.
Há um tecto rígido de 24 funções personalizadas precisamente para que isto possa ser uma só resposta. Um espaço de trabalho com quarenta funções não consegue responder a "quem pode enviar como billing@" olhando para a lista, que é a única pergunta que a funcionalidade existe para tornar respondível.