Autenticação

Execute openemail login num terminal e ele pergunta qual quer. Em ambos os casos, o início de sessão é guardado como perfil, e cada comando seguinte usa o ativo.

• —Só um início de sessão no navegador pode usar ai compose, ai summarize e os comandos MCP.
• —Um início de sessão no navegador dura até expirar a aprovação que escolheu, ou até terminar a sessão. Uma chave funciona até ser revogada.

1. 1openemail login regista uma nova aplicação para este início de sessão, chamada OpenEmail CLI on <your computer>, e abre a página de aprovação do OpenEmail no seu navegador. Se o navegador não abrir, use a ligação que mostra.
2. 2Inicie sessão se for preciso e depois escolha o espaço de trabalho, o acesso que a CLI recebe (leitura, leitura e envio, total, ou o seu próprio conjunto de permissões), os domínios ou endereços que alcança e quanto tempo dura a aprovação.
3. 3Aprove. O navegador devolve a aprovação ao terminal sozinho e pode fechar o separador. A CLI mostra com quem iniciou sessão, o espaço de trabalho e quando expira a aprovação.

openemail loginopenemail login --scopes emails:send,threads:readopenemail login --profile work

• —A CLI espera 10 minutos pela sua aprovação. Escolher Agora não na página de aprovação cancela o início de sessão, com o código de saída 10.
• —--scopes pré-seleciona permissões na página de aprovação, e ainda as pode alterar lá.
• —Quando o perfil já tem um início de sessão, um terminal pergunta antes de o substituir. Sem supervisão, recusa, a menos que passe --force ou --yes. Substituir um início de sessão no navegador revoga o antigo.

Por baixo está o fluxo OAuth que o servidor MCP usa: um cliente público com PKCE, um código de uso único e um token de acesso que dura uma hora e é renovado por si. O navegador regressa a 127.0.0.1 numa porta aleatória, e aí só é aceite o código deste início de sessão.

Quando a CLI não consegue abrir um navegador nesta máquina, mostra a ligação em vez disso: por SSH, em CI, em Linux sem ecrã, ou quando passa --no-browser. Abra a ligação num navegador em qualquer dispositivo e aprove. A página mostra então um código de início de sessão, que cola no terminal.

$ openemail login --no-browserOpen this link in a browser on any device to sign in:  https://api.openemail.uk/auth/mcp/authorize?response_type=code&client_id=…Paste the code from your browser

• —Um código só serve para o início de sessão que mostrou a ligação, por isso um código de outro separador é recusado.
• —Colar o endereço completo onde o navegador terminou também funciona.
• —Sem terminal, envie o código por stdin.

Uma chave de API inicia a sessão de um script sem navegador, e nunca lhe é pedido um código. Crie uma em Definições → Chaves API (openemail open api-keys) só com os scopes de que o script precisa. A CLI verifica a chave com GET /keys/self antes de a guardar, e aceita chaves oe_live_ e oe_test_. O correio enviado com uma chave de teste nunca é entregue.

openemail login --with-token < ~/.config/openemail/keyecho "$OPENEMAIL_KEY" | openemail login --with-token --profile ciopenemail login --token oe_live_…

--token também funciona, mas a chave fica no histórico da sua shell, por isso a CLI avisa e sugere --with-token. Há duas formas de usar uma chave sem a guardar:

• —OPENEMAIL_API_KEY no ambiente é usada por cada comando que a vê, à frente de qualquer perfil guardado.
• —--api-key <key> é usada para esse único comando.

Quando há mais de uma credencial, ganha a primeira destas: --api-key, OPENEMAIL_API_KEY, o perfil indicado por --profile, o perfil indicado por OPENEMAIL_PROFILE, e depois o perfil ativo.

Um perfil é um início de sessão guardado, de qualquer dos dois tipos. O primeiro chama-se default. Inicie sessão em mais com --profile e alterne entre eles:

openemail login --profile workopenemail profile listopenemail profile use workopenemail inbox --profile defaultOPENEMAIL_PROFILE=work openemail statusopenemail profile currentopenemail profile remove work

• —profile list mostra cada perfil com o tipo, o espaço de trabalho e o utilizador ou a chave, e marca o ativo. O seu JSON nunca inclui um token nem uma chave.
• —profile current mostra só o nome em stdout, por isso $(openemail profile current) funciona num script.
• —profile remove <name> é o mesmo que openemail logout --profile <name>.
• —Um nome de perfil tem até 64 letras, dígitos, pontos, hífenes e sublinhados.
• —profile use também se chama profile switch. Remover o perfil ativo, ou terminar a sua sessão, não deixa nenhum perfil ativo, e o próximo comando que precise de sessão indica openemail profile use <name>.

Um perfil guardado lembra-se da API em que iniciou sessão, e a sua credencial só é enviada para lá. Um --base-url ou OPENEMAIL_BASE_URL que indique outra origem para o comando com o código de saída 2 antes de enviar alguma coisa, e explica como iniciar sessão nessa origem com um perfil próprio.

openemail login --profile other --base-url https://api.example.comopenemail inbox --profile other

• —Uma chave de OPENEMAIL_API_KEY ou --api-key não é um perfil guardado, por isso vai para a origem em --base-url ou OPENEMAIL_BASE_URL, ou para https://api.openemail.uk quando nenhum está definido.
• —Os comandos que não enviam credenciais seguem --base-url e OPENEMAIL_BASE_URL, seja qual for o perfil ativo: caixas de entrada descartáveis, métodos que não precisam de chave, docs e open.
• —O http simples é recusado para qualquer origem exceto localhost, 127.0.0.1 e ::1, com o código de saída 2: a API, a aplicação web, os pedidos de início de sessão, de token e de revogação, e o servidor MCP. Use https para tudo o resto.
• —Um caminho de pedido que sairia da origem da API, como openemail api //example.com/x, para com o código de saída 2 e invalid_path antes de enviar alguma coisa.

Um início de sessão no navegador age como você, mas algumas coisas nunca são aprovadas para uma aplicação, seja qual for o acesso que escolher:

• —Gerir chaves de API. keys:write e keys:manage nunca são concedidos, por isso criar, rodar e revogar chaves exige uma chave de API que tenha keys:manage, ou a aplicação web. openemail me rotate roda a chave com que está a chamar, por isso precisa de uma chave de API.
• —A faturação, e os próprios espaços de trabalho. Os planos, as faturas, e criar, mudar ou eliminar um espaço de trabalho ficam na aplicação web.
• —O seu endereço gratuito. Uma aplicação é aprovada para um espaço de trabalho empresarial, e o espaço pessoal que tem o endereço gratuito nunca é oferecido, a mesma regra que a API segue.
• —Membros e funções, a menos que a aprovação cubra todo o espaço de trabalho. members:write e roles:write são retirados de uma aprovação limitada a alguns domínios ou endereços.

Uma chave de API tem um limite próprio. ai compose, ai summarize e cada comando openemail mcp exceto config passam pelo servidor MCP, que exige um início de sessão no navegador, por isso com uma chave param com o código de saída 4 e dizem porquê.

Com um início de sessão no navegador, algumas alterações pedem primeiro um código de verificação, como na aplicação web. A CLI pede-o quando precisa: envia-lhe por email um código de seis dígitos ou, se o início de sessão em dois passos estiver ativo, pede um código da sua aplicação de autenticação ou um dos seus códigos de recuperação. Quando o código está certo, o comando é executado, e a esse início de sessão não volta a ser pedido durante 60 minutos. A uma chave de API nunca é pedido.

$ openemail webhooks create --url https://acme.com/hooks/openemailWe emailed a code to a•••@acme.com.Verification code: 482913Verified. You will not be asked again for 60 minutes.

• —Escreva r no pedido para receber o email outra vez. Um código errado diz quantas tentativas restam.
• —Depois de o código ser aceite, o comando é executado mais uma vez, nunca duas.
• —--yes confirma uma eliminação, mas nunca salta um código.
• —Sem supervisão (com --json ou --no-input, em CI ou sem terminal) ninguém pode escrever o código, por isso o comando para com o código de saída 4 e não altera nada.
• —Um código permite 5 tentativas, e depois da quinta errada a CLI oferece um código novo. Cada início de sessão pode pedir 5 códigos por hora e 20 por dia.
• —Dez códigos errados para um início de sessão em 24 horas põem a sua verificação em pausa. A CLI diz então quando é retomada e para com o código de saída 4 e step_up_paused, sem oferecer outro código, e o email que o explica nomeia a aplicação.

Execute openemail verify antes de um script ou um cliente de IA fazer algo sensível. Pede o código agora, e durante os 60 minutos seguintes cada comando desse perfil corre sem ele, incluindo openemail mcp call e a ponte MCP local.

openemail verifyopenemail verify --statusopenemail verify --status --jsonopenemail verify --force

• —O token de acesso de um início de sessão no navegador dura uma hora. A CLI renova-o antes de expirar e guarda o novo, por isso nunca dá por isso.
• —Cada token de atualização funciona uma única vez. Um antigo usado mais de 30 segundos depois de a CLI o ter substituído, por exemplo a partir de uma cópia de config.json noutra máquina, faz o servidor revogar esse início de sessão por completo, por isso inicie sessão em cada máquina em vez de copiar o ficheiro.
• —A aprovação dura o tempo que escolheu na página de aprovação. Quando termina, ou quando a aplicação é removida em Conta → Aplicações ligadas, a CLI deixa de poder agir por si e pede-lhe que volte a executar openemail login.
• —openemail logout revoga um início de sessão no navegador no servidor, o que o retira das aplicações ligadas, e depois esquece-o neste dispositivo, mesmo quando não é possível contactar o servidor. --all termina a sessão de cada perfil.
• —Terminar a sessão de uma chave de API só a esquece aqui. A chave continua a funcionar até a revogar, com openemail keys revoke <id> ou na aplicação web.

Tudo fica em ~/.openemail, ou na pasta que OPENEMAIL_CONFIG_DIR indicar. A pasta só pode ser lida por si (0700), tal como cada ficheiro que contém (0600). Cada ficheiro é escrito num ficheiro temporário e renomeado para o seu lugar, para que uma falha nunca deixe um a meio, e cada alteração é feita sob um ficheiro de bloqueio, para que comandos a correr lado a lado nunca percam um perfil.