Ключи, участники и роли

Эти команды решают, кто и что может достучаться до рабочего пространства. openemail keys управляет API-ключами и читает, что сделал каждый, openemail members управляет людьми в рабочем пространстве и их приглашениями, а openemail roles определяет, что может делать участник или ключ. openemail me описывает ключ или вход, которым вы вызываете, а openemail languages перечисляет языки, которые принимает отправка с переводом. Одноразовым ящикам вход не нужен вовсе: openemail temp это обычный способ ими пользоваться, а openemail temp-mail это каждый вызов API, который за ним стоит. openemail api достаёт до любого эндпоинта, до которого не достают другие команды.

• —Команда ключа принимает идентификатор ключа, 24 шестнадцатеричных символа после oe_live_, как его показывает keys list. Команда участника принимает идентификатор аккаунта, userId в members list, и никогда не адрес почты. Команда роли принимает идентификатор role_ из roles list, потому что роли нельзя найти по имени.
• —Пространства имён откликаются также на key, member, role, language и tempMail. Работают обычные псевдонимы глаголов, такие как ls, show, new, edit и rm. В members, где глаголы называются add и remove, new и create ведут к add, а rm, del и delete ведут к remove.
• —openemail <command> --help перечисляет каждый аргумент и флаг с типом, scope, который нужен вызову, методом и путём и тем, что возвращается. Добавьте --json, чтобы получить ту же страницу как данные.

Для чтения ключей нужен keys:read, а для каждого изменения keys:manage. Входу через браузер никогда не выдаются keys:write и keys:manage, поэтому создание, изменение, ротация, отзыв и удаление ключей требуют API-ключа с keys:manage или веб-приложения (openemail open api-keys). Вход через браузер с keys:read читает ключи только у владельца рабочего пространства, а вход участника отклоняется с 403 owner_only.

• —keys create, keys rotate и me rotate один раз выводят секрет ключа в token, и CLI затем предупреждает, что больше его не покажут. Каждое чтение вместо этого показывает maskedKey.
• —Если их не указать, новый ключ получает только emails:send и берёт роль, область отправки и срок действия ключа, который его создаёт. --domain-allowlist и --address-allowlist задают, от имени кого он может отправлять, а --expires-in-minutes принимает от 5 до 5 256 000, то есть десять лет.
• —Ключ никогда не создаёт и не достаёт ключ шире себя. Scope, роль, срок действия, режим и область отправки должны лежать внутри вызывающего ключа, иначе вызов отклоняется с 403 beyond_caller_authority, а param называет то, что оказалось слишком широким. Ключ, суженный до некоторых доменов или адресов, видит только ключи внутри своей области отправки, а любой другой даёт 404.
• —keys update заменяет то, что вы отправили: --scopes, --address-allowlist и --domain-allowlist каждый принимают весь новый список, а флаг, который вы не указали, остаётся как был. --no-enabled выключает ключ, так что каждый вызов с ним отклоняется с inactive_api_key, а --enabled в точности его восстанавливает. Так ключ останавливают обратимо.
• —keys revoke действует навсегда: ключ больше никогда нельзя включить, ротировать или изменить. keys delete убирает только отозванный ключ, а любой другой отклоняется с 409 not_revoked. Журнал запросов и активность удалённого ключа остаются, под пометкой «Удалённый ключ».
• —У keys rotate нет окна перекрытия, поэтому старый секрет перестаёт работать в тот момент, когда возвращается новый. Если это ключ, которым пользуется ваш сохранённый профиль, CLI сохраняет новый секрет в этот профиль, и он продолжает работать. Ключ из OPENEMAIL_API_KEY или --api-key сохранить нельзя, поэтому CLI просит положить новый токен туда, где хранился старый ключ.

Журнал запросов записывает каждый вызов ключа: метод, путь, статус, код ошибки, длительность, IP и user agent, но никогда не тело и не строку запроса. Ничего не удаляется, поэтому он уходит назад до первого вызова ключа, а вызовов со входом через браузер в нём нет. Журнал активности записывает каждое изменение ключа и каждый вызов, который предъявил ключ и был отклонён, как auth_failed, а кто сделал каждое изменение, указано в actor.

• —list-requests и list-activity читают один ключ. list-workspace-requests и list-workspace-activity читают все ключи, которые вам видны, или до 50, названных в --key-ids, включая удалённые.
• —--since и --until задают период и принимают время ISO 8601, например 2026-09-01T00:00:00Z. --failed-only оставляет вызовы, на которые ответили статусом 400 или выше.

openemail me get это первая команда, которую стоит запустить, когда вызов отклонён. Ей не нужен scope, поэтому любой действующий ключ или вход может описать себя.

• —scopes это то, что учётные данные могут делать прямо сейчас: scope, с которыми они созданы, урезанные ролью, под которой они выпущены, и вычисляемые при каждом запросе. grantedScopes это то, с чем они созданы, а roleId называет роль. Scope, который есть в grantedScopes и отсутствует в scopes, убрала роль. Это обычная причина 403 insufficient_scope у ключа, у которого scope вроде бы есть, и исправлять нужно роль, а не выпускать ещё один ключ.
• —domainAllowlist и addressAllowlist говорят, от имени кого можно отправлять. Если оба null, это любой адрес, которым владеет рабочее пространство.
• —При входе через браузер она описывает вход: object равен oauth_token, clientId называет подключённое приложение этой CLI, а expiresAt это момент, когда заканчивается ваше одобрение, или null, если оно не заканчивается никогда.
• —me ping отвечает ok: true с теми же сведениями о scope, но без списков разрешённых, что подходит для проверки работоспособности. Отозванный, истёкший, выключенный или набранный с ошибкой ключ не проходит с 401 и кодом выхода 3.
• —me rotate даёт ключу, которым вы вызываете, новый секрет. Ему нужен keys:write, которого у входа через браузер никогда не бывает, поэтому нужен API-ключ. Всё остальное в ключе сохраняется, старый секрет сразу перестаёт работать, а сохранённый профиль получает новый, как с keys rotate. Потерянный ответ может оставить ключ с секретом, который никто не видел, и тогда ему нужен новый из веб-приложения.
• —openemail whoami показывает тот же ответ, отформатированный для людей.

openemail languages list выводит всю таблицу языков одним ответом, около двухсот строк, с кодом каждого языка, английским названием, собственным названием, флагом и тем, пишется ли он справа налево. Код, английское название и собственное название одинаково работают как цель отправки с переводом. Ей нужен вход, но не scope. openemail ai languages выводит ту же таблицу с флагом --search, а без входа выводит таблицу, встроенную в CLI.

У участника есть две вещи, которые никогда не смешиваются. Роль говорит, что он может делать, а выданные адреса и домены говорят, с какой почтой, причём у каждой выдачи свой доступ: member читает и отправляет, а viewer только читает. Отправке нужно и то и другое, поэтому роль с emails:send и выдача viewer на адрес всё равно не позволяют отправлять с него. Целый домен охватывает каждый адрес на нём, включая созданные позже.

• —members list ставит владельца рабочего пространства первым с пометкой isOwner, поэтому не учитывайте эту строку при подсчёте мест. У владельца есть все разрешения, и его нельзя пригласить, изменить или удалить, как нельзя и снова пригласить того, кто уже в рабочем пространстве: в обоих случаях 422 member_is_owner.
• —Люди, у которых есть выданные адреса, но которым никогда не давали роль, возвращаются с implied: true, и их роль выводится из выданного. members update даёт им настоящую.
• —members add отправляет приглашение, даже тому, у кого уже есть аккаунт. Ничего не выдаётся, пока он не примет, а затем выдаются ровно те роль, адреса и домены, которые несёт приглашение. Повторное приглашение того же адреса в течение десяти минут даёт 409 invitation_too_soon, а после этого обновляет ожидающее приглашение вместо отправки второго.
• —resend-invitation отправляет новую ссылку, действующую ещё 14 дней, и выводит из строя старую, что также продлевает истёкшее приглашение. revoke-invitation отзывает приглашение, а уже принятое приглашение даёт 409 invitation_accepted, так что вместо этого удалите участника.
• —members update меняет роль и ничего больше. grant-address выдаёт один адрес или меняет доступ к нему, поэтому повторный запуск с другим --access меняет выдачу, а не добавляет вторую. revoke-address забирает один адрес и оставляет остальные. Отзыв последней выдачи у участника с выведенной ролью убирает его из рабочего пространства.
• —members remove прекращает доступ человека к рабочему пространству, его членство и каждую выдачу и сообщает в addressesRevoked, сколько выданных адресов ушло. Его аккаунт и отправленная им почта не затрагиваются.

Роль также служит потолком для API-ключей, выпущенных под ней. То, что может ключ, это его собственные scope, урезанные разрешениями его роли и вычисляемые при каждом запросе.

• —roles list показывает сначала встроенные роли в порядке Owner, Admin, Member, Viewer, Developer и Billing, затем собственные роли по имени. В рабочем пространстве может быть до 24 собственных ролей, а сверх этого roles create даёт 422 role_limit_reached.
• —Роль хранит и те разрешения, которые подразумевают её разрешения, поэтому templates:write сохраняет ещё и templates:read, а roles:write приносит roles:read и members:read. Читайте список из ответа, а не предполагайте его.
• —roles update --permissions заменяет весь список, поэтому прочитайте роль, измените список и отправьте его целиком. --description null очищает описание. Изменение действует со следующего вызова каждого участника и ключа, у которых есть эта роль.
• —Каждую роль, кроме Owner, можно переименовать, переписать и удалить, включая встроенные, и удалённая встроенная роль не возвращается. Роль владельца отвечает на правку 409 role_immutable, а на удаление 409 role_undeletable.
• —Пока роль есть у какого-либо участника, API-ключа или ожидающего приглашения, roles delete нужен --reassign-to с ролью, которая их примет, иначе вызов отклоняется с 409 role_in_use. Отозванные ключи по-прежнему указывают на свою роль, поэтому он может понадобиться и роли, у которой счётчик apiKeys равен 0. Ответ сообщает о переведённых людях в reassigned и о ключах в keysReassigned.
• —roles list-permissions перечисляет весь словарь с подписью и группой для каждого. Несколько, такие как billing:write и workspace:manage, возвращаются с scope: false: роль может их иметь, а ключ нет.

Одноразовому ящику не нужны ни аккаунт, ни вход. К нему обращаются по его собственному токену ящика, который начинается с oe_inbox_ и возвращается один раз, при создании ящика. Пользуйтесь openemail temp каждый день, а openemail temp-mail, когда нужно поле или шаг, которых temp не показывает, например оставшиеся продления, продление или байты вложения.

• —Обе хранят токен в ~/.openemail/temp-mail.json, который можете читать только вы. temp new и temp-mail create сохраняют его, temp list показывает ящики, созданные любым из способов, а обе команды удаления его забывают. Сохранённый ящик можно назвать его адресом везде, где команда просит идентификатор.
• —Для ящика, который создавала не эта CLI, передайте токен через --inbox-token. Если нет ни сохранённого, ни переданного токена, команда останавливается с кодом выхода 3 до любой отправки.
• —Две команды создания называют флаги по-разному: temp new принимает --name, --domain и --ttl, а temp-mail create принимает --local-part, --domain и --ttl-minutes. Локальная часть это от 3 до 32 букв, цифр, точек, дефисов или подчёркиваний, начинающаяся и заканчивающаяся буквой или цифрой, а такие имена, как postmaster, отклоняются. Аренда длится от 1 до 1440 минут, по умолчанию 60.
• —С каждого IP-адреса можно создать 6 ящиков в час и 30 в день, а следующий даёт 429 too_many_inboxes с кодом выхода 8. Продление ящика, который у вас уже есть, не считается, поэтому ответ на этот предел это temp-mail extend.
• —temp-mail extend добавляет до часа, никогда не дальше 24 часов после создания ящика и не больше 23 раз. Читайте extensionsLeft из ответа. При 0 это навсегда 409 extension_limit.
• —temp-mail list-messages читает от 1 до 50 писем на страницу, по умолчанию 50, каждое с текстовым snippet до 400 символов, в котором часто лежит одноразовый код. Ничего за пределами страницы не теряется, а --all проходит все страницы.
• —Чтение письма через temp read, temp-mail get-message или temp-mail list-attachments отмечает его просмотренным. Тело больше 2 МБ обрезается, о чём говорит truncated, а вложение больше 8 МБ вообще не сохранялось, поэтому его content равен null.
• —Удаление ящика сразу удаляет его почту, но адрес остаётся зарезервированным до 7 дней после того, как закончилась бы его аренда, и повторный запрос его до этого срока даёт 409 address_taken.

openemail api <method> <path> отправляет один запрос через тот же транспорт, что и любая другая команда, поэтому действуют ваш профиль или ключ, обновление токена, коды подтверждения и подтверждения. Путь сам по себе означает GET, а ответ в JSON выводится отформатированным. openemail api /keys/self это вызов, который стоит за me get.

• —-d, --data принимает тело как встроенный JSON, из файла через @path или из stdin через -. -q, --query и -H, --header принимают key=value и могут повторяться, а -o, --out сохраняет ответ в файл как есть.
• —DELETE и любой вызов, который команда ресурса попросила бы подтвердить, например отзыв или ротация ключа, сначала просит подтверждения, а без присмотра ему нужен --yes.
• —Неудачный запрос выводит ошибку API и завершается соответствующим кодом.

Пространство имён security не перечислено в openemail --help, потому что им управляет openemail verify. Его глаголы step-up-status, begin-step-up и verify-step-up это вызовы, которые делает verify: verify --status читает состояние, а verify запрашивает код, просит вас его ввести и проверяет. Они существуют для входа через браузер. С API-ключом каждый отклоняется с 400 step_up_not_applicable, а openemail verify сообщает, что ключу код никогда не нужен.

openemail keys create --name 'Billing sender' --scopes emails:send \  --domain-allowlist billing.acme.com --expires-in-minutes 129600 --json \  | jq -r .token | openemail login --with-token --profile billingopenemail whoami --profile billing

Запускайте это с API-ключом, у которого есть keys:manage, например через OPENEMAIL_API_KEY. Секрет идёт из ответа прямо в новый профиль, поэтому никогда не оказывается на экране или в файле. Ключ может отправлять только с billing.acme.com и истекает через 90 дней.

openemail keys list --all | jq -r 'select(.status != "active") | [.name, .status, .lastUsedAt] | @tsv'openemail keys list-workspace-requests --failed-only --since 2026-09-26T00:00:00Z --all \  | jq -r '[.createdAt, .keyName, .status, .errorCode, .method, .path] | @tsv'

id=4c1b257a66287fd113bd89d0openemail keys update "$id" --no-enabledopenemail keys list-activity "$id" --since 2026-09-27T00:00:00Z --all | jq -r 'select(.type == "auth_failed") | .createdAt'openemail keys revoke "$id" --reason 'Contractor offboarded' --yesopenemail keys delete "$id" --yes

Выключение ключа сначала можно отменить через --enabled. Каждый вызов, который всё ещё предъявляет его, отклоняется и появляется в его активности как auth_failed, что показывает, что от него ещё зависит. Отзыв отменить нельзя, и удалить можно только отозванный ключ.

openemail roles list-permissions --json | jq -r '.[] | [.group, .id, .label] | @tsv'role=$(openemail roles create --name Support --permissions threads:write,emails:send,templates:read \  --description 'Answers help@ and nothing else.' --json | jq -r .id)openemail members add --email [email protected] --role-id "$role" \  --domain-ids 93542ff8-2baa-4f2f-841d-5ceaa074ab0d --access memberopenemail members list-invitations

Роль возвращается ещё и с threads:read и emails:read, потому что названные в ней разрешения их подразумевают. Sam получит роль и весь домен только после того, как примет приглашение. При входе через браузер members add сначала спрашивает код подтверждения.

old=role_8b1f4c2e9a7d3b60e5f1a2c4new=role_2c7e9a1f4b8d3e60c5a7f1b9user=$(openemail members list --all | jq -r 'select(.email == "[email protected]") | .userId')openemail members update "$user" --role-id "$new"openemail roles get "$old" --json | jq '{name, members, apiKeys}'openemail roles delete "$old" --reassign-to "$new" --dry-runopenemail roles delete "$old" --reassign-to "$new" --yes

members и apiKeys считаются в момент запроса, поэтому показывают, что сдвинет удаление. Пробный запуск выводит DELETE с reassignTo в запросе, не отправляя его. При входе через браузер обновление и удаление каждое спрашивают код подтверждения, поэтому, когда это делает скрипт, сначала запустите openemail verify.

address=$(openemail temp new --ttl 15)openemail send --from [email protected] --to "$address" --subject 'Delivery check' --text 'Your code is 482913' --yesopenemail temp watch "$address" --first --json | jq -r .snippet | grep -oE '[0-9]{6}'openemail temp delete "$address" --yes

temp new выводит только адрес, поэтому он помещается в переменную оболочки, а temp watch --first останавливается на первом письме. Укажите этот адрес в форме регистрации вместо openemail send, чтобы так же поймать её код подтверждения.

• —Вход или ключ без нужного scope останавливается с кодом выхода 4, называет недостающий scope и объясняет, как его получить.
• —Подтверждения просят: keys delete, rotate и revoke, me rotate, roles delete, members remove, revoke-address и revoke-invitation, temp delete, а также temp-mail delete и delete-message. Ответ «нет» завершает их с кодом 10 и ничего не меняет. Без присмотра и без --yes они останавливаются с кодом выхода 2 до любой отправки.
• —При входе через браузер roles update и roles delete, а также members add, update, remove, grant-address и revoke-address ещё и спрашивают код подтверждения, если этот вход не подтверждал код в последние 60 минут. --yes никогда его не пропускает, а без присмотра ввести его некому, поэтому команда останавливается с кодом выхода 4. Сначала запустите openemail verify. У API-ключа код не спрашивают никогда.
• —--dry-run выводит запрос, который отправило бы изменение, с его телом и завершается с кодом 0, не отправляя его и не прося подтверждения.
• —Список читает одну страницу. --limit принимает от 1 до 100, а если его не указать, сервер отдаёт 25, кроме temp-mail list-messages, которая принимает от 1 до 50 и отдаёт 50. --cursor принимает nextCursor предыдущей страницы. --all читает все страницы, --max <n> останавливается после стольких элементов, а --ndjson или --all в конвейере выводит по одному JSON-объекту в строке. С --json список выводит один документ { items, hasMore, nextCursor }.
• —roles list-permissions, languages list, temp-mail list-domains и temp-mail list-attachments возвращают всё сразу простым массивом, без страниц.
• —Отказ завершается кодом своего статуса: 3 для 401, например у отозванного ключа, 4 для 403, например beyond_caller_authority или owner_only, 5 для 404, 6 для 409, например not_revoked, role_in_use или invitation_too_soon, 7 для 400 или 422, например member_is_owner или role_limit_reached, и 8 для 429, например too_many_inboxes.
• —Изменение, которое при повторе сделало бы что-то дважды, никогда не повторяется после сбоя сети: keys create и rotate, me rotate, roles create и delete, members add, remove, revoke-address и resend-invitation, а также temp-mail create, extend, delete и delete-message. Проверьте, прежде чем запускать такое снова. Чтения и изменения, которые дважды дают один и тот же результат, такие как keys update, keys revoke, roles update, members update и grant-address, повторяются сами.