Список ролей

Все роли рабочего пространства, встроенные первыми, с числом людей и ключей на каждой.

export OE=https://api.openemail.ukexport AUTH="Authorization: Bearer $OPENEMAIL_API_KEY"

РОЛЬ говорит, что человеку МОЖНО ДЕЛАТЬ в этом рабочем пространстве: читать почту, отправлять её, редактировать шаблоны, добавить домен. ВЫДАННЫЙ ДОСТУП говорит, к каким АДРЕСАМ он может это применять, и живёт по соседству на /members/{userId}/addresses как member (читает адрес и отправляет от его имени) или viewer (только читает). Обе стороны должны согласиться, прежде чем письмо уйдёт: роль с emails:send и без выданных адресов может отправлять ниоткуда, и все адреса рабочего пространства под доступом viewer тоже позволяют отправлять ниоткуда.

Каждое рабочее пространство создаётся с одними и теми же шестью ролями. Owner, Admin, Member и Viewer образуют лестницу. Каждая содержит всё, что содержит следующая, поэтому понижение сужает доступ человека, а не меняет его на другой набор. Developer и Billing не ступени этой лестницы: Developer строит интеграции (ключи, вебхуки, шаблоны, отправку) и не читает почту рабочего пространства вовсе, а Billing видит тариф и счета и больше ничего. Обе строго внутри Admin. Они создаются при первом чтении, а не при создании рабочего пространства, поэтому пространство, созданное до появления этой возможности, обзаводится ими в момент первого запроса. builtin называет, из какого шаблона получилась строка, и это всё, что он называет: шесть ролей — это отправная точка, которую рабочее пространство должно подогнать под себя, и любую из них, кроме Owner, можно переименовать, перенастроить по разрешениям и удалить. Ветвитесь по editable и deletable, а не по имени: переименованная кем-то роль по-прежнему отвечает на эти два поля верно, а её имя уже ни о чём не говорит.

Owner — единственное исключение, и исключение во всех направлениях: editable: false, deletable: false и отказ в качестве цели в PATCH /members/{userId}. Он описывает аккаунт, к которому привязано рабочее пространство, и содержит каждое разрешение, включая добавленные в более поздних релизах, — поэтому его список вычисляется, а не хранится. Сделать владельцем кого-то другого — это передача рабочего пространства; эндпоинта, который её выполняет, здесь нет.

Остальные пять принимают всё: новый список разрешений, новое описание, новое имя, DELETE. Это созданные по умолчанию заготовки, а не неизменяемые фикстуры: рабочее пространство, которое никогда не строит интеграции, должно иметь возможность избавиться от Developer, а то, где «Member» означает нечто более узкое, должно иметь возможность сказать это своими словами. Отказывает только владелец, и отказывает во всём под одним кодом: role_immutable, 409 с param: "roleId", независимо от того, было ли в PATCH имя или список разрешений. Переименование само по себе больше нигде не отклоняется, поэтому неизменяемости с param: "name" обрабатывать не нужно; единственный 409, который ещё может вызвать имя, — это role_name_taken, когда на него уже откликается другая роль в рабочем пространстве.

Сверх этих шести рабочее пространство может завести до 24 собственных ролей. Потолок считает только их, поэтому удаление созданной при заполнении роли не освобождает места под ним. Разрешения при записи РАСКРЫВАЮТСЯ, а не берутся буквально (templates:write сам по себе сохраняется как templates:read и templates:write), поэтому читайте список из ответа, а не считайте, что он совпадает с отправленным.

Требует roles:read. Без курсора. Обёртка несёт hasMore и nextCursor, чтобы клиент мог передать её в тот же код списка, что и для любой другой коллекции, и второй страницы не бывает никогда.

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}