Envio e rastreio de email

O espaço de nomes emails é a API de envio sob a forma de comandos, um para cada método de openemail.emails no SDK. Cada um chama um endpoint e mostra o que devolve. O espaço de nomes tracking lê as aberturas e os cliques no correio que enviou. openemail email funciona em vez de openemail emails.

Cada comando desta página precisa de um início de sessão, no navegador ou com uma chave de API, e de um de dois scopes: emails:send para enviar, traduzir, cancelar e reagendar, e emails:read para tudo o que apenas lê.

openemail send é o comando escrito à mão da página Correio, e envia através de emails send. Foi feito para uma pessoa num terminal: escolhe o endereço de envio quando omite --from, lê o corpo de um ficheiro, de stdin ou do seu editor, anexa ficheiros pelo caminho e mostra um resumo para confirmar antes de sair alguma coisa. openemail emails send recebe o corpo do pedido como opções, uma por campo, e não pergunta nada, o que serve a um script que sabe exatamente o que envia.

Só emails send tem --tracking para desligar as aberturas ou os cliques num envio, --signature, --headers para cabeçalhos personalizados, --attachment-delivery para escolher entre anexar ficheiros ou ligar para eles, e --data para o corpo inteiro como JSON, em linha, de um ficheiro com @path ou de stdin com -.

send, send-batch, translate, cancel e reschedule precisam de emails:send. list, get, list-events e get-tracking precisam de emails:read. Um id de email é msg_ seguido de 24 caracteres hexadecimais, tal como um envio o devolve.

Os cinco precisam de emails:read. tracking get, list-opens e list-clicks aceitam qualquer um dos dois ids que uma mensagem tem: o id msg_ que o seu envio devolveu, ou o id de rastreio tmsg_ que tracking list e os payloads dos webhooks trazem.

tracking list e get-stats cobrem cada mensagem rastreada que a caixa de correio enviou, incluindo o correio escrito na aplicação web e o enviado pelas ferramentas MCP ou pelo assistente, enquanto emails list contém os registos de envio que a API fez. Um relatório sem registo de envio tem sendId definido como null.

Envie a partir de um script com uma chave de idempotência sua. Voltar a executá-lo com a mesma --idempotency-key mostra o primeiro email com replayed: true em vez de enviar um segundo.

openemail emails send \  --from 'Acme Billing <[email protected]>' \  --to [email protected] \  --subject 'Your September invoice' \  --html '<p>The invoice is attached. Tell me if anything on it looks wrong.</p>' \  --attachments '[{"fileId":"file_6bb640f5b99e47deb758f1f5"}]' \  --tracking '{"opens":false}' \  --idempotency-key invoice:inv_2026_09_4192 \  --json | jq -r '.id + " " + .status'

Peça a uma pessoa que leia uma tradução antes de sair. Envie o texto aprovado como --subject e --html simples, sem --translate, ou será traduzido uma segunda vez. O html traduzido já contém o seu original por baixo, a menos que passe --no-include-original.

openemail emails translate --to de \  --subject 'Your September invoice' \  --html "$(cat invoice.html)" \  --json > preview.jsonjq -r .html preview.jsonopenemail emails send --from [email protected] --to [email protected] \  --subject "$(jq -r .subject preview.json)" \  --html "$(jq -r .html preview.json)"

Envie um lote a partir de um ficheiro. O comando sai com o código 0 sempre que o lote foi processado, mesmo quando alguns itens falharam, por isso leia failed e o status de cada item. Voltar a executá-lo com a mesma chave reproduz os itens que saíram e envia só os restantes, desde que o array mantenha a ordem.

[  { "from": "[email protected]", "to": "[email protected]", "subject": "Receipt 4192", "text": "Thanks for your order." },  { "from": "[email protected]", "to": "[email protected]", "subject": "Receipt 4193", "text": "Thanks for your order." }]

openemail emails send-batch receipts.json --idempotency-key receipts:2026-09-27 --json > result.jsonjq '{ sent, failed }' result.jsonjq -r '.items[] | select(.status == "error") | "\(.index) \(.error.code)"' result.json

Agende um email, mova-o e cancele-o. --yes responde à confirmação que cancel pede, o que um script não consegue fazer.

ID=$(openemail send --from [email protected] --to [email protected] --subject "Standup notes" \  --body-file notes.md --at 2026-10-01T09:00:00Z --json | jq -r .id)openemail emails reschedule "$ID" 2026-10-01T13:00:00Zopenemail emails get "$ID" --json | jq -r '.status + " " + .scheduledAt'openemail emails cancel "$ID" --yes

Encontre os envios que falharam e leia o que aconteceu a um deles. Encaminhado sem --json, --all mostra um objeto JSON por linha.

openemail emails list --status failed,partial --from [email protected] --all | jq -r .idopenemail emails get msg_3f9a1c07d2b84e6a9c5b1f20openemail emails list-events msg_3f9a1c07d2b84e6a9c5b1f20 --all --json | jq -r '.items[] | .createdAt + " " + .type'

Leia uma semana de interação em dias que mudam à meia-noite UTC+2, liste o que ninguém abriu e conte os cliques em cada ligação de uma mensagem.

openemail tracking get-stats --days 7 --offset-minutes 120 --json | jq '{ tracked, openRate, clickRate }'openemail tracking list --no-opened --days 7 --all | jq -r .subjectopenemail tracking list-clicks msg_3f9a1c07d2b84e6a9c5b1f20 --all | jq -r .url | sort | uniq -c

• —Um início de sessão no navegador pede os scopes na página de aprovação, e openemail login --scopes emails:send,emails:read pré-seleciona os dois. Um comando a que falta o scope para com o código de saída 4 e insufficient_scope, e indica o scope.
• —send --attach com mais de 5 MB de ficheiros carrega-os primeiro para Ficheiros, o que também precisa de files:write.
• —Nenhum destes comandos pede um código de verificação, por isso um início de sessão no navegador executa-os tal como uma chave de API.
• —emails cancel pergunta antes de cancelar, e --yes responde por si. Sem supervisão e sem --yes, para com Refusing to run unattended. Pass --yes to confirm. e o código de saída 2.
• —emails send, send-batch e reschedule nunca perguntam. send mostra um resumo e só pergunta num terminal, e --yes também salta isso.
• —--dry-run mostra o pedido que um comando enviaria, não envia nada e sai com o código 0. Em emails translate não gasta nenhuma ação de IA, e em emails cancel não pergunta nada.

emails list, emails list-events, tracking list, list-opens e list-clicks leem uma página. --limit define o seu tamanho, de 1 a 100 com 25 por predefinição para as duas listas de emails, e de 1 a 200 com 50 por predefinição para as três listas de tracking. --cursor continua a partir do cursor que uma página mostrou.

• —--all lê todas as páginas e transmite os itens: uma tabela num terminal, e um objeto JSON por linha quando encaminhado ou com --ndjson.
• —--max <n> para depois desse número de itens, e implica --all.
• —--json mostra um único documento { items, hasMore, nextCursor }, também com --all.
• —A paginação é por cursor, não por deslocamento, por isso o correio enviado enquanto pagina nunca desloca nem repete uma linha.

• —Cada execução cria a sua própria chave de idempotência, que cobre as repetições dentro dessa execução. Executar um envio duas vezes envia duas vezes, a menos que as duas execuções passem a mesma --idempotency-key. A mesma chave com um corpo diferente é recusada com idempotency_key_reuse e o código de saída 7.
• —Só o correio queued e scheduled pode ser cancelado ou movido. Um envio imediato sem janela para anular sai dentro do próprio pedido, por isso quando tem o seu id normalmente já é tarde, e a chamada termina com email_not_cancellable e o código de saída 6.
• —Um email cancelado continua cancelado. Reagendar altera só a hora, contada a partir do momento em que o servidor recebe o pedido no caso de uma duração, por isso para alterar o texto, cancele e envie de novo.
• —Uma tradução que não pode ser produzida recusa o envio inteiro, e nada sai sem tradução. Um lote traduzido contém no máximo 10 mensagens que levam translate.
• —Uma quota de envio esgotada para um envio com send_quota_exceeded até ao primeiro dia do mês, e uma quota de IA esgotada para uma tradução com ai_quota_exceeded até à meia-noite UTC, ambas com o código de saída 8.
• —O correio enviado com uma chave oe_test_ nunca é entregue. Aparece como sent, com transport definido como test, e nunca é rastreado.
• —emails get-tracking e tracking get respondem 404, código de saída 5, para uma mensagem que não levava píxel nem ligações reescritas, porque não rastreado não é o mesmo que não aberto. O rastreio segue a definição com que a mensagem foi enviada, por isso ativá-lo mais tarde não chega ao correio anterior.
• —Cada contagem é um mínimo. Um leitor cujo cliente de email bloqueia imagens nunca conta como abertura, e um clique é uma prova de leitura mais forte do que uma abertura.
• —list-opens e list-clicks respondem 404 para um id msg_ sem nada rastreado, mas aceitam um id tmsg_ tal como é dado, por isso um desconhecido volta como uma lista vazia.
• —Uma chave limitada a alguns endereços só vê o correio enviado a partir desses endereços, e uma que tem um domínio inteiro cobre todos os endereços dele.

Esta página indica as opções mais importantes. openemail <command> --help lista cada argumento e opção que um comando aceita, com o tipo, o scope de que precisa, o método e o caminho, o que devolve e as notas da referência da API. Acrescente --json para ter a mesma ajuda como um único documento JSON.

openemail emails --helpopenemail emails send --helpopenemail tracking list-opens --help --json