문서로 건너뛰기
API

역할 만들기

이름 하나와 권한 목록 하나. 돌아오는 것은 보낸 것보다 깁니다.

POSTapi.openemail.uk/roles

본인 키로 워크스페이스에 실제 호출을 실행합니다.

POST /roles

이름 하나와 권한 목록 하나. 돌아오는 것은 보낸 것보다 깁니다.

예제

roles:write가 필요합니다. 201을 반환합니다. 커스텀 역할은 builtin: null, editable: true, deletable: true이며, 누군가를 그 역할로 옮기기 전까지는 아무도 갖고 있지 않습니다.

curl
curl -X POST "$OE/roles" -H "$AUTH" -H "Content-Type: application/json" \  -d '{    "name": "Support",    "description": "Answers the shared inboxes and nothing else.",    "permissions": ["emails:send", "threads:write", "labels:write", "contacts:read"]  }'
응답
{  "object": "role",  "id": "role_2b81de079c1f0a4b7e05d386",  "name": "Support",  "description": "Answers the shared inboxes and nothing else.",  "permissions": [    "emails:send",    "emails:read",    "threads:read",    "threads:write",    "labels:read",    "labels:write",    "contacts:read"  ],  "builtin": null,  "editable": true,  "deletable": true,  "members": 0,  "apiKeys": 0,  "createdAt": "2026-08-30T10:41:02.000Z",  "updatedAt": "2026-08-30T10:41:02.000Z"}

권한 네 개를 보냈는데 일곱 개가 돌아옵니다. emails:sendemails:read를, threads:writethreads:read를, labels:writelabels:read를 함의합니다. 열어볼 수도 없는 스레드를 보관할 수 있는 역할은 누군가 잊은 체크박스이지 누구도 의도한 정책이 아니므로, 함의는 거부되지 않고 저장됩니다. 목록은 정규 순서로 돌아오기도 하는데, 덕분에 클라이언트가 두 역할을 JSON으로 비교해 저장 버튼을 활성화할지 정할 수 있습니다.

알 수 없는 권한은 여기서는 버려지지 않고 거부됩니다. templates:writinvalid_parameter, 422이며 해당 문자열을 함께 알려 줍니다. 서비스가 조용히 정규화하는 이유는 같은 코드가 시딩 경로이자 MCP 경로이기도 하기 때문이며, 거기서는 알아보지 못한 단어 하나 때문에 역할 전체를 실패시키는 편이 더 나쁩니다. 하지만 사람이 일부러 만든 호출에서는 그것이 틀린 동작입니다. 템플릿을 편집할 수 없는 역할을 담은 200은 아무것도 알려주지 않았고, 그 사람은 오후 내내 그 문제에 매달리게 됩니다.

같은 워크스페이스에서 이름이 중복되면 role_name_taken, 409입니다. 25번째 커스텀 역할은 role_limit_reached, 422입니다. 아무도 감사하지 않게 되기 전까지 매트릭스가 얼마나 커질 수 있는지를 제한하는 것이며, 플랜 경계가 아닙니다.

역할을 만든다고 누구에게 주어지지는 않습니다. 사람을 그 역할로 옮기는 것은 PATCH /members/{userId}이고, 키를 그 역할로 지정하는 것은 키를 발급하는 곳에서 합니다.