Para agentes de IA

openemail agents mostra um guia curto em Markdown para um agente de IA como o Claude Code ou o Codex, ou para um script em CI: como iniciar sessão sem uma pessoa, ler a saída, encontrar comandos, alterar coisas com segurança e percorrer listas, o que fazer quando falta um código de verificação ou um scope, e cinco receitas para copiar. openemail agent é o mesmo comando.

openemail agentsopenemail agents --json | jq -r '.recipes[].commands[]'

Com --json o guia é um único documento com schemaVersion, title, intro, sections de { id, title, points }, exitCodes e recipes de { id, title, commands }. Em vez de colar estas regras em cada prompt, diga ao agente uma vez, no ficheiro de instruções que o seu projeto já lhe dá, que execute openemail agents antes de usar a CLI.

• —Use uma chave de API. Defina OPENEMAIL_API_KEY, ou passe --api-key a um único comando. Crie-a em Definições → Chaves API (openemail open api-keys) só com os scopes de que o agente precisa. Uma chave nunca abre um navegador e nunca precisa de um código de verificação.
• —Ou reutilize um início de sessão no navegador que uma pessoa fez uma vez nesta máquina com openemail login, e escolha-o com --profile <name>. A CLI renova os seus tokens sozinha.
• —Sem um terminal nada pede entrada. Com --json, --no-input ou CI, ou sem um terminal ligado, um valor que a CLI teria pedido para com o código de saída 2 e indica a opção a passar.
• —Um início de sessão no navegador precisa de uma pessoa que o aprove, por isso um openemail login sem supervisão para com o código de saída 2 e o código unattended antes de registar o que quer que seja, e remete para openemail login --with-token.
• —openemail whoami --json mostra o espaço de trabalho, o tipo de início de sessão e os seus scopes.

Passe --json a cada comando. O stdout contém então exatamente um documento JSON, ou um objeto por linha com --ndjson, e o progresso fica em stderr. Uma falha mostra uma linha {"error":{...}} em stderr: decida pelo código de saída e pelo seu code, mostre next a uma pessoa e nunca analise message, cuja redação pode mudar. A página Scripts lista cada campo e cada código de saída.

--help --json mostra a ajuda como um único documento JSON, construído a partir do mesmo registo de comandos com que a CLI analisa, por isso corresponde sempre à versão instalada. Funciona na raiz, num grupo ou num comando, e openemail help <command> --json mostra o mesmo.

openemail send --help --jsonopenemail domains delete --help --json | jq '.commands[0] | {scopes, destructive}'openemail help domains --json | jq -r '.commands[0].subcommands[].command'openemail --help --json | jq -r '.commands[].command'

A árvore completa tem cerca de um megabyte, quase tudo os 198 comandos de recursos, por isso peça o comando de que precisa ou filtre a árvore com jq. O texto mantém os acentos graves e não traz códigos de cor, e os comandos ocultos como security estão incluídos com hidden a true.

--dry-run funciona em todos os comandos exceto mcp serve. As leituras correm como de costume, depois o primeiro pedido que alteraria alguma coisa é mostrado em vez de enviado, e o comando termina com o código 0 sem fazer mais nada. As confirmações são saltadas, já que nada é enviado, por isso um agente pode ver o que um comando destrutivo faria sem passar --yes.

openemail domains delete <domain-id> --dry-runopenemail send --from [email protected] --to [email protected] --subject "Hi" --text "Hello" --dry-run --json

{  "dryRun": true,  "request": {    "method": "POST",    "url": "https://api.openemail.uk/emails",    "headers": {      "accept": "application/json",      "authorization": "Bearer [redacted]",      "content-type": "application/json",      "idempotency-key": "58e6fb61-ad2e-401e-b141-7a0546c7c749",      "user-agent": "openemail-cli/0.0.1 openemail-sdk/0.0.5"    },    "body": {      "from": "[email protected]",      "to": [        "[email protected]"      ],      "subject": "Hi",      "text": "Hello"    },    "raw": null  }}

• —Uma alteração é qualquer pedido exceto GET e HEAD, uma chamada a uma ferramenta MCP, e os pedidos de início e fim de sessão de login e logout. A renovação de tokens e docs ask continuam a correr.
• —O plano mostra o método, o URL completo, os cabeçalhos com o valor de Authorization reduzido a Bearer [redacted], e o corpo JSON com os campos secretos, como uma chave do Resend, ocultados. Um carregamento mostra só o seu tamanho e o tipo de conteúdo.
• —Uma alteração que fica nesta máquina, como profile use, login --with-token ou esquecer uma chave de API guardada, mostra {"dryRun":true,"local":{"action","profile"}} e não guarda nada.
• —Um comando que mostra o que leu antes da sua primeira alteração mostra-o primeiro: read mostra a conversa e depois o pedido que a marcaria como lida. Passe --no-mark-read para omitir o segundo.
• —mcp serve recusa --dry-run com o código de saída 2, porque o seu cliente decide o que enviar. Em vez disso, pré-visualize uma chamada a uma ferramenta com openemail mcp call <tool> --dry-run.

Cada comando conhece os scopes de API de que precisa sempre, e a sua ajuda lista-os. Quando falta um a um início de sessão guardado, o comando pede uma vez à API a lista atual, por isso o acesso dado no site depois do início de sessão conta de imediato. Se o scope continuar em falta, para com o código de saída 4 e o código insufficient_scope antes de perguntar alguma coisa ou enviar um pedido:

{"error":{"type":"cli_error","code":"insufficient_scope","message":"This sign-in does not have the emails:send permission, which openemail send needs.","hint":null,"next":"Give this app more access in Account settings, Connected apps (openemail open apps, then Edit access), or run openemail login --force and choose more access.","status":null,"requestId":null,"param":null,"docUrl":null,"exitCode":4}}

• —Para um início de sessão no navegador, next diz para dar mais acesso à aplicação em Conta → Linha de comandos (openemail open cli, depois Editar acesso), ou para executar openemail login --force e escolher mais acesso. Um início de sessão no navegador nunca recebe keys:write nem keys:manage, por isso para esses remete para uma chave de API.
• —Para uma chave de API, next diz para usar uma chave que tenha o scope.
• —Uma chave de --api-key ou de OPENEMAIL_API_KEY não é verificada antecipadamente, e é a API que decide. Quando a API recusa uma chamada por falta de um scope, o erro traz o mesmo next.

Uma chave de API nunca precisa de um código de verificação. Um início de sessão no navegador precisa de um antes de uma alteração sensível, como adicionar um webhook, criar uma regra, alterar um membro ou remover um domínio, e um agente não o consegue escrever. Por isso, antes de o agente correr, uma pessoa executa openemail verify num terminal com o mesmo perfil, ou escolhe Permitir alterações durante 60 minutos para esse início de sessão em Conta → Linha de comandos. Qualquer um dos dois cobre os 60 minutos seguintes.

openemail verifyopenemail verify --status --json

verify --status --json diz ao agente se o perfil está verificado, em elevated, e até quando, em elevatedUntil. Sem verificação, a alteração para com o código de saída 4 e o código step_up_required, e nada é alterado:

{"error":{"type":"cli_error","code":"step_up_required","message":"This action needs a verification code, and there is no interactive terminal to ask for one.","hint":null,"next":"Run openemail verify in an interactive terminal first, then run this again within 60 minutes. An API key never needs a code.","status":403,"requestId":"req_9Qm4tV","param":null,"docUrl":"https://openemail.uk/docs/api/errors#step_up_required","exitCode":4}}

Um agente que fala MCP pode usar o servidor MCP do OpenEmail em vez disso. openemail mcp config --client claude-code, ou codex, cursor e os outros clientes que lista, mostra a configuração, e openemail mcp serve é uma ponte local que reutiliza o início de sessão no navegador desta CLI. As chaves de API não chegam ao servidor MCP. A página IA e MCP tem os detalhes.