Chaves, membros e funções

Estes comandos decidem quem e o que pode chegar ao espaço de trabalho. openemail keys gere as chaves de API e lê o que cada uma fez, openemail members gere as pessoas do espaço de trabalho e os respetivos convites, e openemail roles define o que um membro ou uma chave pode fazer. openemail me descreve a chave ou o início de sessão com que está a chamar, e openemail languages lista os idiomas que um envio traduzido aceita. As caixas de entrada descartáveis não precisam de nenhum início de sessão: openemail temp é a forma do dia a dia de usar uma, e openemail temp-mail é cada chamada da API por trás dela. openemail api chega a qualquer endpoint a que os outros comandos não cheguem.

• —Um comando de chave aceita o id da chave, os 24 caracteres hexadecimais depois de oe_live_, tal como keys list o mostra. Um comando de membro aceita o id de conta, userId em members list, nunca um endereço de email. Um comando de função aceita um id role_ de roles list, porque as funções não são procuradas pelo nome.
• —Os espaços de nomes respondem também a key, member, role, language e tempMail. Os aliases de verbo habituais funcionam, como ls, show, new, edit e rm. Em members, cujos verbos são add e remove, new e create levam a add, e rm, del e delete levam a remove.
• —openemail <command> --help lista cada argumento e opção com o tipo, o scope de que a chamada precisa, o método e o caminho, e o que devolve. Acrescente --json para ter a mesma página como dados.

Ler chaves precisa de keys:read, e cada alteração precisa de keys:manage. A um início de sessão no navegador nunca são concedidos keys:write nem keys:manage, por isso criar, alterar, rodar, revogar e eliminar chaves exige uma chave de API que tenha keys:manage, ou a aplicação web (openemail open api-keys). Um início de sessão no navegador com keys:read só lê chaves para o proprietário do espaço de trabalho, e o início de sessão de um membro é recusado com 403 owner_only.

• —keys create, keys rotate e me rotate mostram o segredo da chave, em token, uma vez, e depois a CLI avisa que nunca mais será mostrado. Cada leitura mostra maskedKey em vez dele.
• —Se forem omitidos, uma chave nova tem apenas emails:send, e fica com a função, o âmbito de envio e a expiração da chave que a cria. --domain-allowlist e --address-allowlist definem a partir de que endereços pode enviar, e --expires-in-minutes aceita de 5 a 5.256.000, que são dez anos.
• —Uma chave nunca cria nem alcança uma chave mais ampla do que ela própria. Os scopes, a função, a expiração, o modo e o âmbito de envio têm todos de caber dentro da chave que chama, ou a chamada é recusada com 403 beyond_caller_authority, e param indica o que era demasiado amplo. Uma chave limitada a alguns domínios ou endereços só vê as chaves dentro do seu próprio âmbito de envio, e qualquer outra dá 404.
• —keys update substitui o que enviar: --scopes, --address-allowlist e --domain-allowlist aceitam cada um a lista nova inteira, e uma opção que omitir fica como estava. --no-enabled desativa uma chave, por isso cada chamada com ela é recusada com inactive_api_key, e --enabled restaura-a exatamente. Assim para-se uma chave de uma forma que pode anular.
• —keys revoke é de vez: a chave nunca pode voltar a ser ativada, rodada ou alterada. keys delete só remove uma chave revogada, e qualquer outra é recusada com 409 not_revoked. O registo de pedidos e a atividade de uma chave eliminada ficam, sob Chave eliminada.
• —keys rotate não tem período de sobreposição, por isso o segredo anterior deixa de funcionar no momento em que o novo volta. Quando a chave é a que o seu perfil guardado usa, a CLI guarda o novo segredo nesse perfil, para que continue a funcionar. Uma chave de OPENEMAIL_API_KEY ou --api-key não pode ser guardada, por isso a CLI indica-lhe que guarde o novo token onde quer que a chave antiga estivesse guardada.

O registo de pedidos guarda cada chamada que uma chave fez: método, caminho, estado, código de erro, duração, IP e agente de utilizador, nunca um corpo nem uma query string. Nada é apagado, por isso chega até à primeira chamada de uma chave, e as chamadas feitas com um início de sessão no navegador não estão nele. O registo de atividade guarda cada alteração a uma chave, e cada chamada que apresentou a chave e foi recusada, como auth_failed, com quem fez cada alteração em actor.

• —list-requests e list-activity leem uma chave. list-workspace-requests e list-workspace-activity leem cada chave que pode ver, ou até 50 que --key-ids indique, incluindo as chaves eliminadas.
• —--since e --until delimitam um período e aceitam uma hora ISO 8601 como 2026-09-01T00:00:00Z. --failed-only mantém as chamadas respondidas com um estado 400 ou superior.

openemail me get é o primeiro comando a executar quando uma chamada é recusada. Não precisa de scope, por isso qualquer chave ou início de sessão válidos se podem descrever a si próprios.

• —scopes é o que a credencial pode fazer neste momento: os scopes com que foi criada, reduzidos pela função com que foi emitida, calculados em cada pedido. grantedScopes é aquilo com que foi criada, e roleId indica a função. Um scope que está em grantedScopes e falta em scopes foi retirado pela função. Essa é a razão habitual de um 403 insufficient_scope numa chave que parece ter o scope, e a solução é alterar a função em vez de criar outra chave.
• —domainAllowlist e addressAllowlist dizem a partir de que endereços pode enviar. Ambos a null significa qualquer endereço que o espaço de trabalho tenha.
• —Com um início de sessão no navegador descreve o início de sessão: object é oauth_token, clientId indica a aplicação ligada desta CLI, e expiresAt é quando termina a sua aprovação, ou null quando nunca termina.
• —me ping responde ok: true com o mesmo detalhe de scopes mas sem as listas de permissões, o que serve para uma verificação de estado. Uma chave revogada, expirada, desativada ou mal escrita falha com um 401 e o código de saída 3.
• —me rotate dá à chave com que está a chamar um segredo novo. Precisa de keys:write, que um início de sessão no navegador nunca tem, por isso exige uma chave de API. Tudo o resto da chave mantém-se, o segredo anterior deixa de funcionar de imediato, e um perfil guardado recebe o novo, como com keys rotate. Uma resposta perdida pode deixar a chave com um segredo que ninguém viu, e nesse caso precisa de um novo a partir da aplicação web.
• —openemail whoami mostra a mesma resposta formatada para pessoas.

openemail languages list mostra a tabela de idiomas inteira numa só resposta, cerca de duzentas linhas, com o código de cada idioma, o nome em inglês, o nome próprio, a bandeira e se é escrito da direita para a esquerda. O código, o nome em inglês ou o nome próprio funcionam como destino de um envio traduzido. Precisa de um início de sessão mas de nenhum scope. openemail ai languages mostra a mesma tabela com uma opção --search, e sem sessão iniciada mostra a tabela incluída na CLI.

Um membro tem duas coisas que nunca se misturam. A sua função diz o que pode fazer, e as suas concessões de endereços e domínios dizem com que correio o pode fazer, cada concessão com o seu próprio acesso: member lê e envia, e viewer só lê. Um envio precisa das duas, por isso uma função com emails:send e uma concessão viewer num endereço continua sem poder enviar a partir dele. Um domínio inteiro cobre todos os seus endereços, incluindo os criados mais tarde.

• —members list põe primeiro o proprietário do espaço de trabalho, marcado com isOwner, por isso deixe essa linha de fora ao contar lugares. O proprietário tem todas as permissões e não pode ser convidado, alterado nem removido, e ninguém que já esteja no espaço de trabalho pode ser convidado de novo: ambos os casos dão 422 member_is_owner.
• —As pessoas que têm concessões de endereços mas a quem nunca foi dada uma função voltam com implied: true, e a sua função é deduzida das concessões. members update dá-lhes uma real.
• —members add envia um convite, mesmo a alguém que já tem conta. Nada é concedido até aceitar, e depois exatamente a função, os endereços e os domínios que o convite traz. Convidar de novo o mesmo endereço em dez minutos dá 409 invitation_too_soon, e depois disso atualiza o convite pendente em vez de enviar um segundo.
• —resend-invitation envia uma ligação nova válida por mais 14 dias e retira a anterior, o que também renova um convite expirado. revoke-invitation retira um, e um convite que já foi aceite dá 409 invitation_accepted, por isso remova antes o membro.
• —members update altera a função e mais nada. grant-address dá um endereço ou altera o acesso a ele, por isso executá-lo de novo com outro --access altera a concessão em vez de acrescentar uma segunda. revoke-address retira um endereço e deixa os restantes. Revogar a última concessão de um membro deduzido remove-o do espaço de trabalho.
• —members remove termina o acesso de alguém ao espaço de trabalho, a sua pertença e cada concessão, e indica em addressesRevoked quantas concessões de endereços foram retiradas. A conta e o correio que enviou ficam intactos.

Uma função é também um teto para as chaves de API emitidas com ela. O que uma chave pode fazer são os seus próprios scopes reduzidos pelas permissões da sua função, calculados em cada pedido.

• —roles list mostra primeiro as funções predefinidas, pela ordem Owner, Admin, Member, Viewer, Developer e Billing, e depois as funções personalizadas por nome. Um espaço de trabalho tem até 24 funções personalizadas, e a partir daí roles create dá 422 role_limit_reached.
• —Uma função guarda as permissões que as suas permissões implicam, por isso templates:write guarda também templates:read, e roles:write traz roles:read e members:read. Leia a lista na resposta em vez de a presumir.
• —roles update --permissions substitui a lista inteira, por isso leia a função, altere a lista e envie-a por inteiro. --description null limpa a nota. Uma alteração aplica-se na chamada seguinte de cada membro e chave que tenha a função.
• —Todas as funções exceto Owner podem mudar de nome, ser reescritas e eliminadas, incluindo as predefinidas, e uma função predefinida eliminada não volta. A função de proprietário responde a uma edição com 409 role_immutable e a uma eliminação com 409 role_undeletable.
• —Enquanto algum membro, chave de API ou convite pendente tiver uma função, roles delete precisa de --reassign-to com a função que os recebe, ou é recusado com 409 role_in_use. As chaves revogadas continuam a apontar para a sua função, por isso uma função cuja contagem de apiKeys é 0 ainda pode precisar dele. A resposta indica as pessoas reassigned e as chaves keysReassigned.
• —roles list-permissions lista o vocabulário inteiro com uma etiqueta e um grupo para cada uma. Algumas, como billing:write e workspace:manage, voltam com scope: false: uma função pode tê-las, mas nenhuma chave.

Uma caixa de entrada descartável não precisa de conta nem de início de sessão. Acede-se a ela com o seu próprio token de caixa, que começa por oe_inbox_ e volta uma única vez, quando a caixa é criada. Use openemail temp no dia a dia, e openemail temp-mail quando precisar de um campo ou de um passo que temp não mostra, como as extensões que restam, uma extensão ou os bytes de um anexo.

• —Ambos guardam o token em ~/.openemail/temp-mail.json, que só você pode ler. temp new e temp-mail create guardam-no, temp list mostra as caixas criadas de qualquer uma das formas, e as duas eliminações esquecem-no. Uma caixa guardada pode ser indicada pelo endereço sempre que um comando pedir o seu id.
• —Para uma caixa que esta CLI não criou, passe o token com --inbox-token. Sem token guardado nem passado, o comando para com o código de saída 3 antes de enviar o que quer que seja.
• —Os dois comandos de criação dão nomes diferentes às opções: temp new aceita --name, --domain e --ttl, e temp-mail create aceita --local-part, --domain e --ttl-minutes. Uma parte local tem de 3 a 32 letras, dígitos, pontos, hífenes ou sublinhados, começa e acaba com uma letra ou um dígito, e nomes como postmaster são recusados. A concessão dura de 1 a 1440 minutos, 60 por predefinição.
• —Cada endereço IP pode criar 6 caixas por hora e 30 por dia, e a seguinte dá 429 too_many_inboxes, código de saída 8. Estender uma caixa que já tem não conta, por isso temp-mail extend é a resposta a esse limite.
• —temp-mail extend acrescenta até uma hora, nunca para além de 24 horas depois de a caixa ter sido criada, e no máximo 23 vezes. Leia extensionsLeft na resposta. Em 0, dá 409 extension_limit de vez.
• —temp-mail list-messages lê de 1 a 50 mensagens por página, 50 por predefinição, cada uma com um snippet em texto simples de até 400 caracteres que muitas vezes contém um código de uso único. Nada além de uma página se perde, e --all percorre todas as páginas.
• —Ler uma mensagem com temp read, temp-mail get-message ou temp-mail list-attachments marca-a como vista. Um corpo com mais de 2 MB é cortado, como truncated indica, e um anexo com mais de 8 MB nunca foi guardado, por isso o seu content é null.
• —Eliminar uma caixa elimina o seu correio de imediato, mas o endereço fica reservado até 7 dias depois de quando a concessão teria terminado, e pedi-lo de novo antes disso dá 409 address_taken.

openemail api <method> <path> envia um pedido através do mesmo transporte que qualquer outro comando, por isso aplicam-se o seu perfil ou a sua chave, a renovação do token, os códigos de verificação e as confirmações. Um caminho sozinho é um GET, e uma resposta JSON é mostrada formatada. openemail api /keys/self é a chamada por trás de me get.

• —-d, --data recebe o corpo como JSON em linha, de um ficheiro com @path, ou de stdin com -. -q, --query e -H, --header recebem key=value e podem repetir-se, e -o, --out guarda a resposta tal como veio num ficheiro.
• —Um DELETE, e qualquer chamada que um comando de recurso confirmaria, como revogar ou rodar uma chave, pede-lhe primeiro confirmação, e sem supervisão precisa de --yes.
• —Um pedido falhado mostra o erro da API e sai com o código correspondente.

O espaço de nomes security não aparece em openemail --help, porque é openemail verify que o conduz. Os seus verbos step-up-status, begin-step-up e verify-step-up são as chamadas que verify faz: verify --status lê o estado, e verify pede um código, solicita-lho e verifica-o. Existem para um início de sessão no navegador. Com uma chave de API cada um é recusado com 400 step_up_not_applicable, e openemail verify diz que uma chave nunca precisa de código.

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

Execute-o com uma chave de API que tenha keys:manage, por exemplo através de OPENEMAIL_API_KEY. O segredo passa da resposta diretamente para um perfil novo, por isso nunca aparece no ecrã nem num ficheiro. A chave só pode enviar a partir de billing.acme.com, e expira em 90 dias.

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

Desativar primeiro a chave pode ser anulado com --enabled. Cada chamada que ainda a apresente é recusada e aparece na sua atividade como auth_failed, o que lhe diz o que ainda depende dela. Revogar não pode ser anulado, e só uma chave revogada pode ser eliminada.

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

A função volta também com threads:read e emails:read, porque as permissões que indica as implicam. Sam recebe a função e o domínio inteiro só quando aceitar. Com um início de sessão no navegador, members add pede primeiro um código de verificação.

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 e apiKeys são contados quando os pede, por isso mostram o que a eliminação vai mover. A simulação mostra o DELETE com reassignTo na query sem o enviar. Com um início de sessão no navegador, a atualização e a eliminação pedem cada uma um código de verificação, por isso execute primeiro openemail verify quando for um script a fazê-lo.

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 mostra só o endereço, por isso cabe numa variável da shell, e temp watch --first para na primeira mensagem. Aponte um formulário de registo para o endereço em vez de openemail send para apanhar o código de confirmação da mesma forma.

• —Um início de sessão ou uma chave sem o scope para com o código de saída 4, indica o scope em falta e explica como o obter.
• —Estes pedem-lhe confirmação: keys delete, rotate e revoke, me rotate, roles delete, members remove, revoke-address e revoke-invitation, temp delete, e temp-mail delete e delete-message. Responder que não sai com o código 10 e não altera nada. Sem supervisão e sem --yes, param com o código de saída 2 antes de enviar o que quer que seja.
• —Com um início de sessão no navegador, roles update e roles delete, e members add, update, remove, grant-address e revoke-address, também pedem um código de verificação, a menos que este início de sessão tenha verificado um nos últimos 60 minutos. --yes nunca o salta, e sem supervisão ninguém o pode escrever, por isso o comando para com o código de saída 4. Execute primeiro openemail verify. A uma chave de API nunca é pedido.
• —--dry-run mostra o pedido que uma alteração enviaria, com o corpo, e sai com o código 0 sem o enviar nem lhe pedir confirmação.
• —Uma lista lê uma página. --limit aceita de 1 a 100 e o servidor envia 25 quando é omitido, exceto em temp-mail list-messages, que aceita de 1 a 50 e envia 50. --cursor aceita o nextCursor da página anterior. --all lê todas as páginas, --max <n> para depois desse número de itens, e --ndjson, ou --all num pipe, mostra um objeto JSON por linha. Com --json, uma lista mostra um único documento { items, hasMore, nextCursor }.
• —roles list-permissions, languages list, temp-mail list-domains e temp-mail list-attachments devolvem tudo de uma vez, como um array simples, sem páginas.
• —Uma recusa sai com o código do seu estado: 3 para um 401, como uma chave revogada, 4 para um 403, como beyond_caller_authority ou owner_only, 5 para um 404, 6 para um 409, como not_revoked, role_in_use ou invitation_too_soon, 7 para um 400 ou um 422, como member_is_owner ou role_limit_reached, e 8 para um 429, como too_many_inboxes.
• —Uma alteração que faria algo duas vezes nunca é repetida depois de uma falha de rede: keys create e rotate, me rotate, roles create e delete, members add, remove, revoke-address e resend-invitation, e temp-mail create, extend, delete e delete-message. Verifique antes de executar um de novo. As leituras, e as alterações que têm o mesmo efeito duas vezes, como keys update, keys revoke, roles update, members update e grant-address, são repetidas automaticamente.