CLI postal

#Instalar

La CLI postal viene en el paquete postal-so y requiere Node 18 o superior:

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

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

Sirve para probar una clave, enviar un correo de prueba, disparar un evento o revisar dominios sin escribir código, y para scripts y agentes de IA (con --json).

#Autenticación

postal login pide la clave (lo que escribes no aparece en pantalla), la comprueba con la API y la guarda en ~/.config/postal/config.json con permiso 0600 (solo tu usuario puede leerla). Fuera de una terminal, lee la clave de la entrada estándar. postal whoami muestra la cuenta y la clave en uso, y postal logout borra la clave guardada.

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

La variable de entorno POSTAL_API_KEY tiene prioridad sobre el archivo: en CI y en servidores, usa solo la variable. Una clave solo de envío basta para emails send, events send y emails get (solo de los correos que ella envió); los demás comandos requieren acceso total.

#Comandos

postal --help lista los comandos y postal <comando> --help muestra las opciones y ejemplos de cada uno, en portugués.

#Enviar un correo electrónico

Los valores de --html y --text aceptan @arquivo para leer el contenido de un archivo. Repite --to, --cc y --bcc (o sepáralos con comas) para varias direcciones. Con --idempotency-key, repetir el comando no duplica el envío.

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 y contactos

events send acepta --email o --external-id para indicar quién lo hizo, --props con los datos del evento y --contact-props para actualizar el contacto antes de las automatizaciones. contacts upsert busca por --external-id y después por --email; indica el correo para crear un contacto nuevo.

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

#Salida para scripts y agentes

Añade --json para imprimir la respuesta de la API como JSON. En caso de error, el JSON {"error": {"statusCode", "name", "message"}} sale por stderr.

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"}

POSTAL_API_URL cambia la URL de la API (por defecto https://api.postal.so), útil para pruebas.