키, 멤버, 역할

이 명령들은 누가, 무엇이 워크스페이스에 닿을 수 있는지 정합니다. openemail keys는 API 키를 관리하고 각 키가 한 일을 읽으며, openemail members는 워크스페이스의 사람들과 그 초대를 관리하고, openemail roles는 멤버나 키가 할 수 있는 일을 정의합니다. openemail me는 호출에 쓰는 키나 로그인을 설명하고, openemail languages는 번역 보내기가 받는 언어를 나열합니다. 일회용 받은편지함에는 로그인이 전혀 필요 없습니다. openemail temp는 그것을 일상적으로 쓰는 방법이고, openemail temp-mail은 그 뒤에 있는 API의 모든 호출입니다. openemail api는 다른 명령이 닿지 않는 모든 엔드포인트에 닿습니다.

• —키 명령은 keys list에 나오는 대로 oe_live_ 뒤의 16진수 문자 24개인 키 ID를 받습니다. 멤버 명령은 이메일 주소가 아니라 members list의 userId인 계정 ID를 받습니다. 역할 명령은 roles list의 role_ ID를 받는데, 역할은 이름으로 찾을 수 없기 때문입니다.
• —네임스페이스는 key, member, role, language, tempMail로도 응답합니다. ls, show, new, edit, rm 같은 흔한 동사 별칭이 동작합니다. 동사가 add와 remove인 members에서는 new와 create가 add로, rm, del, delete가 remove로 이어집니다.
• —openemail <command> --help는 모든 인수와 플래그를 타입, 호출에 필요한 범위, 메서드와 경로, 반환값과 함께 나열합니다. --json을 붙이면 같은 페이지를 데이터로 받습니다.

키를 읽으려면 keys:read가, 모든 변경에는 keys:manage가 필요합니다. 브라우저 로그인에는 keys:write나 keys:manage가 절대 부여되지 않으므로, 키를 만들고, 바꾸고, 교체하고, 폐기하고, 삭제하려면 keys:manage를 가진 API 키나 웹 앱(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, 즉 10년까지 받습니다.
• —키는 자신보다 넓은 키를 만들거나 그런 키에 닿지 않습니다. 범위, 역할, 만료, 모드, 발송 범위가 모두 호출하는 키 안에 있어야 하며, 그렇지 않으면 호출은 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, 사용자 에이전트이며, 본문이나 쿼리 문자열은 절대 기록하지 않습니다. 아무것도 정리되지 않으므로 키의 첫 호출까지 거슬러 올라가며, 브라우저 로그인으로 한 호출은 들어 있지 않습니다. 활동 로그는 키에 대한 모든 변경과, 키를 제시했다가 거부된 모든 호출을 auth_failed로 기록하며, 각 변경을 누가 했는지는 actor에 있습니다.

• —list-requests와 list-activity는 키 하나를 읽습니다. list-workspace-requests와 list-workspace-activity는 볼 수 있는 모든 키, 또는 --key-ids가 지정한 최대 50개의 키를 삭제된 키까지 포함해 읽습니다.
• —--since와 --until은 기간을 정하며 2026-09-01T00:00:00Z 같은 ISO 8601 시각을 받습니다. --failed-only는 400 이상의 상태로 응답한 호출만 남깁니다.

호출이 거부되면 가장 먼저 실행할 명령은 openemail me get입니다. 범위가 필요 없으므로 유효한 키나 로그인이라면 무엇이든 자신을 설명할 수 있습니다.

• —scopes는 자격 증명이 지금 할 수 있는 것입니다. 만들 때의 범위를 발급 기준 역할로 깎은 것이며, 요청마다 계산됩니다. grantedScopes는 만들 때의 범위이고, roleId가 역할을 알려 줍니다. grantedScopes에는 있는데 scopes에는 없는 범위는 역할이 걷어낸 것입니다. 범위를 가진 것처럼 보이는 키에서 403 insufficient_scope가 나는 흔한 이유이며, 해결책은 키를 새로 발급하는 것이 아니라 역할을 바꾸는 것입니다.
• —domainAllowlist와 addressAllowlist는 어떤 주소로 보낼 수 있는지 알려 줍니다. 둘 다 null이면 워크스페이스가 소유한 어떤 주소든 됩니다.
• —브라우저 로그인에서는 로그인을 설명합니다. object는 oauth_token이고, clientId는 이 CLI의 연결된 앱을 가리키며, expiresAt은 승인이 끝나는 시점이고 끝나지 않으면 null입니다.
• —me ping은 같은 범위 정보를 담되 허용 목록 없이 ok: true로 응답하므로 상태 점검에 알맞습니다. 폐기되었거나, 만료되었거나, 꺼졌거나, 잘못 입력한 키는 401과 종료 코드 3으로 실패합니다.
• —me rotate는 호출에 쓰는 키에 새 시크릿을 줍니다. 브라우저 로그인은 절대 갖지 못하는 keys:write가 필요하므로 API 키가 있어야 합니다. 키의 나머지는 모두 그대로이고, 이전 시크릿은 즉시 멈추며, keys rotate처럼 저장된 프로필은 새 시크릿을 받습니다. 응답을 잃으면 아무도 보지 못한 시크릿이 키에 남을 수 있으며, 그러면 웹 앱에서 새 시크릿을 받아야 합니다.
• —openemail whoami는 같은 응답을 사람이 보기 좋게 보여 줍니다.

openemail languages list는 약 200행에 이르는 언어 표 전체를 응답 하나로 출력하며, 각 언어의 코드, 영어 이름, 자국어 이름, 국기, 오른쪽에서 왼쪽으로 쓰는지 여부가 나옵니다. 코드, 영어 이름, 자국어 이름 모두 번역 보내기의 대상으로 쓸 수 있습니다. 로그인은 필요하지만 범위는 필요 없습니다. openemail ai languages는 같은 표를 --search 플래그와 함께 출력하며, 로그아웃 상태에서는 CLI에 들어 있는 표를 출력합니다.

멤버는 절대 합쳐지지 않는 두 가지를 가집니다. 역할은 무엇을 할 수 있는지를, 주소와 도메인 부여는 어떤 메일에 할 수 있는지를 정하며, 각 부여에는 자체 접근 권한이 있습니다. member는 읽고 보내며, viewer는 읽기만 합니다. 보내기에는 둘 다 필요하므로, emails:send가 있는 역할이라도 주소에 viewer 부여만 있으면 그 주소에서 보낼 수 없습니다. 도메인 전체는 나중에 만든 주소를 포함해 그 도메인의 모든 주소를 다룹니다.

• —members list는 워크스페이스 소유자를 isOwner로 표시해 맨 앞에 두므로, 좌석을 셀 때는 그 행을 빼세요. 소유자는 모든 권한을 가지며 초대하거나 바꾸거나 제거할 수 없고, 이미 워크스페이스에 있는 사람도 다시 초대할 수 없습니다. 둘 다 422 member_is_owner입니다.
• —주소 부여는 있지만 역할을 받은 적 없는 사람은 implied: true로 돌아오며, 역할은 부여에서 추론됩니다. members update로 실제 역할을 주세요.
• —members add는 이미 계정이 있는 사람에게도 초대를 보냅니다. 수락하기 전까지는 아무것도 부여되지 않으며, 수락하면 초대에 담긴 역할, 주소, 도메인이 정확히 부여됩니다. 10분 안에 같은 주소를 다시 초대하면 409 invitation_too_soon이고, 그 뒤에는 두 번째 초대를 보내는 대신 대기 중인 초대를 새로 고칩니다.
• —resend-invitation은 14일 더 유효한 새 링크를 보내고 이전 링크를 폐기하며, 만료된 초대도 이렇게 갱신됩니다. revoke-invitation은 초대를 철회하며, 이미 수락된 초대는 409 invitation_accepted이므로 대신 멤버를 제거하세요.
• —members update는 역할만 바꿉니다. grant-address는 주소 하나를 주거나 그 접근 권한을 바꾸므로, 다른 --access로 다시 실행하면 두 번째 부여를 더하는 대신 부여를 바꿉니다. revoke-address는 주소 하나를 회수하고 나머지는 둡니다. 추론된 멤버의 마지막 부여를 회수하면 그 멤버는 워크스페이스에서 빠집니다.
• —members remove는 누군가의 워크스페이스 접근, 멤버 자격, 모든 부여를 끝내며, 회수된 주소 부여 수를 addressesRevoked에 보고합니다. 그 사람의 계정과 보낸 메일은 건드리지 않습니다.

역할은 그 역할로 발급된 API 키의 상한이기도 합니다. 키가 할 수 있는 일은 자신의 범위를 역할의 권한으로 깎은 것이며, 요청마다 계산됩니다.

• —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를 쓰고, 남은 연장 횟수, 연장, 첨부 파일의 바이트처럼 temp가 보여 주지 않는 필드나 단계가 필요하면 openemail temp-mail을 쓰세요.

• —둘 다 본인만 읽을 수 있는 ~/.openemail/temp-mail.json에 토큰을 보관합니다. temp new와 temp-mail create가 저장하고, temp list는 어느 방식으로 만든 받은편지함이든 보여 주며, 두 삭제 명령 모두 토큰을 잊습니다. 저장된 받은편지함은 명령이 ID를 요구하는 곳 어디서든 주소로 지정할 수 있습니다.
• —이 CLI가 만들지 않은 받은편지함에는 --inbox-token으로 토큰을 넘기세요. 저장되거나 넘긴 토큰이 없으면 명령은 아무것도 보내기 전에 종료 코드 3으로 멈춥니다.
• —두 생성 명령은 플래그 이름이 다릅니다. temp new는 --name, --domain, --ttl을, temp-mail create는 --local-part, --domain, --ttl-minutes를 받습니다. local part는 영문자, 숫자, 점, 대시, 밑줄로 된 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개) 읽으며, 각각 최대 400자의 일반 텍스트 snippet이 있고 여기에 일회용 코드가 들어 있는 경우가 많습니다. 페이지를 넘는 것도 버리지 않으며, --all은 모든 페이지를 훑습니다.
• —temp read, temp-mail get-message, temp-mail list-attachments로 메시지를 읽으면 읽음으로 표시됩니다. 2 MB를 넘는 본문은 잘리며 truncated가 이를 알려 주고, 8 MB를 넘는 첨부 파일은 애초에 보관되지 않았으므로 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 verify가 다루기 때문에 openemail --help에 나오지 않습니다. 그 동사 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

OPENEMAIL_API_KEY를 통하는 식으로 keys:manage를 가진 API 키로 실행하세요. 시크릿은 응답에서 곧장 새 프로필로 들어가므로 화면이나 파일에 남지 않습니다. 이 키는 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는 요청할 때 세므로, 삭제가 무엇을 옮길지 보여 줍니다. 드라이 런은 쿼리에 reassignTo가 있는 DELETE를 보내지 않고 출력합니다. 브라우저 로그인에서는 업데이트와 삭제가 각각 인증 코드를 요구하므로, 스크립트로 할 때는 먼저 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 대신 가입 양식에 이 주소를 넣으면 같은 방식으로 확인 코드를 잡을 수 있습니다.

• —범위가 없는 로그인이나 키는 종료 코드 4로 멈추고, 빠진 범위와 그것을 얻는 방법을 알려 줍니다.
• —다음 명령은 확인을 요청합니다. 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는 페이지 없이 모든 것을 일반 배열로 한 번에 반환합니다.
• —거부는 상태에 맞는 코드로 종료합니다. 401이면 3이며 폐기된 키가 그 예입니다. 403이면 4이며 beyond_caller_authority나 owner_only가 그 예입니다. 404면 5, 409면 6이며 not_revoked, role_in_use, invitation_too_soon이 그 예입니다. 400이나 422면 7이며 member_is_owner나 role_limit_reached가 그 예입니다. 429면 8이며 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처럼 두 번 해도 결과가 같은 변경은 알아서 재시도합니다.