Guias

CLI postal

Envie e-mails e eventos, atualize contatos e confira domínios pelo terminal, com saída JSON para scripts e agentes de IA.

#Instalar

A CLI postal vem no pacote postal-so e precisa de Node 18 ou mais novo:

Terminal

npm install --global postal-so
postal --version

# ou, sem instalar
npx postal-so --help

Ela serve para testar uma chave, mandar um e-mail de teste, disparar um evento ou conferir domínios sem escrever código, e para scripts e agentes de IA (com --json).

#Autenticação

postal login pede a chave (a digitação não aparece na tela), confere com a API e a grava em ~/.config/postal/config.json com permissão 0600 (só o seu usuário lê). Fora de um terminal, ele lê a chave da entrada padrão. postal whoami mostra a conta e a chave em uso, e postal logout apaga a chave guardada.

Terminal

postal login                       # pede a chave e guarda em ~/.config/postal/config.json
echo "$POSTAL_API_KEY" | postal login   # sem terminal
postal whoami                      # plano, cotas e a chave em uso (mascarada)
postal logout

A variável de ambiente POSTAL_API_KEY tem precedência sobre o arquivo: em CI e em servidores, use só a variável. Uma chave só de envio basta para emails send e events send; os outros comandos pedem acesso total.

#Comandos

Comando	O que faz
`postal login`, `logout`, `whoami`	Guarda, apaga e mostra a chave em uso.
`postal emails send`	Envia um e-mail com `--html`, `--text` ou `--template`.
`postal emails get <id>`	Mostra o status de um e-mail.
`postal events send`	Envia um evento que inicia automações.
`postal contacts upsert`	Cria ou atualiza um contato por `--external-id` ou `--email`.
`postal contacts get <contato>`	Mostra um contato pelo e-mail, ID ou `external_id:<id>`.
`postal domains list`	Lista os domínios e o status da verificação.
`postal domains verify <id>`	Pede a verificação do DNS de um domínio.

postal --help lista os comandos e postal <comando> --help mostra as opções e exemplos de cada um, em português.

#Enviar um e-mail

Os valores de --html e --text aceitam @arquivo para ler o conteúdo de um arquivo. Repita --to, --cc e --bcc (ou separe por vírgula) para vários endereços. Com --idempotency-key, repetir o comando não duplica o envio.

Terminal

postal emails send \
  --from "Minha empresa <[email protected]>" \
  --to [email protected] \
  --subject "Bem-vindo!" \
  --html "<p>Que bom ter você por aqui.</p>"

postal emails send --from [email protected] --to [email protected] \
  --subject "Seu relatório" --html @relatorio.html --text @relatorio.txt

# com um template publicado
postal emails send --to [email protected] --template boas-vindas --var NOME=Fulano

#Eventos e contatos

events send aceita --email ou --external-id para dizer quem fez, --props com os dados do evento e --contact-props para atualizar o contato antes das automações. contacts upsert procura por --external-id e depois por --email; informe o e-mail para criar um contato novo.

Terminal

postal events send --email [email protected] --name signup --props '{"plan":"free"}'

postal contacts upsert --external-id user_42 --email [email protected] \
  --first-name Fulano --props '{"plan":"pro"}'

postal domains list

#Saída para scripts e agentes

Acrescente --json para imprimir a resposta da API como JSON. Em caso de erro, o JSON {"error": {"statusCode", "name", "message"}} sai no stderr.

Terminal

postal domains list --json | jq '.data[] | select(.status != "verified") | .name'

postal emails send --from [email protected] --to [email protected] \
  --subject "Teste" --text "Funcionou" --json
# {"id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b"}

Código de saída	Significado
`0`	Deu certo.
`1`	Erro da API (como `validation_error`) ou de rede.
`2`	Uso incorreto: opção desconhecida, valor ausente ou JSON inválido.

POSTAL_API_URL troca a URL da API (padrão https://api.postal.so), útil para testes.