CLI

npm install -g spacepost        # or run without installing: npx spacepost <command>, bunx spacepost <command>
spacepost login
spacepost send --from "Acme <hi@acme.com>" --to you@example.com --subject Hello --text "It works"

Execute spacepost --help para ver todos os comandos e spacepost <command> --help para ver as opções de um comando.

Autenticação

O spacepost login pede a sua chave de API, valida-a na API e a armazena em ~/.config/spacepost/config.json (modo 0600, respeita XDG_CONFIG_HOME). Entrada por pipe também funciona: echo $KEY | spacepost login. Em CI ou em scripts, defina a variável de ambiente:

export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"
spacepost whoami

A chave vem de --api-key, depois de SPACEPOST_API_KEY e, por fim, do login armazenado. A URL base da API vem de --base-url, depois de SPACEPOST_BASE_URL, depois do login armazenado e, por fim, de https://api.spacepost.dev.

Comandos

Comando	O que faz
`login`, `logout`, `whoami`	Gerenciam as credenciais. `whoami` mostra a chave mascarada, a URL base e o número de domínios
`send`	Envia um e-mail
`emails list`, `emails get <id>`, `emails cancel <id>`	Inspecionam e-mails e cancelam os agendados
`domains add <name>`, `list`, `get <id\|name>`, `verify <id\|name>`, `doctor <id\|name>`, `rm <id\|name>`	Gerenciam domínios por id ou nome
`keys create`, `keys list`, `keys rm <id>`	Chaves de API
`webhooks list`, `webhooks create`, `webhooks rm <id>`	Endpoints de webhook
`tenants list`, `create`, `get <ref>`, `pause <ref>`, `unpause <ref>`, `rm <ref>`	Tenants do modo plataforma
`open`	Imprime (e abre) a URL do painel

Flags globais: --api-key, --base-url, --json, -y/--yes (ignora as confirmações), -h/--help, -v/--version. As cores respeitam NO_COLOR.

Enviar

spacepost send \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "Hello from the CLI" \
  --html "<p>It works.</p>"

spacepost send --from hello@acme.com --to a@example.com --to b@example.com --subject "Newsletter" --html-file ./email.html
spacepost send --from hello@acme.com --to user@example.com --subject "Reminder" --text "Call at 3" --schedule "in 1 hour"
echo "body from stdin" | spacepost send --from hello@acme.com --to user@example.com --subject Hi --text -

Flag	Descrição
`--from`	Remetente em um domínio verificado (obrigatório)
`--to`	Destinatário (obrigatório; repita a flag para vários)
`--subject`	Assunto (obrigatório)
`--text`, `--html`, `--html-file`	Corpo: texto simples (`-` lê da entrada padrão), HTML inline ou um arquivo HTML. Pelo menos um é obrigatório; `--html` e `--html-file` não podem ser combinados
`--cc`, `--bcc`, `--reply-to`	Repetíveis
`--tag name=value`	Tag repetível
`--schedule "in 1 hour"`	Horário ISO 8601 ou linguagem natural
`--attach <file>`	Anexo de arquivo repetível
`--tenant <id\|external-id>`	Envia em nome de um tenant

Em caso de sucesso, imprime ✓ Queued: <id> (com --json, a resposta da API { "id": "..." }).

E-mails

spacepost emails list [--limit 20] [--after <id>] [--before <id>]
spacepost emails get <id>
spacepost emails cancel <id>      # scheduled emails only

Domínios

spacepost domains add acme.com [--region eu-central-1] [--tenant cust_123]
spacepost domains list [--limit 20]
spacepost domains get acme.com          # id or name, includes DNS records
spacepost domains verify acme.com
spacepost domains rm acme.com [--yes]

domains add imprime os registros DNS a criar. --tenant torna o domínio pertencente a um tenant (veja Modo plataforma).

domains doctor

spacepost domains doctor <id|name> consulta cada registro DNS esperado (CNAME, TXT, MX) no DNS público, compara com o que o SpacePost espera e imprime o que está faltando ou errado, com uma correção para cada caso. Ele detecta o nome do domínio acrescentado duas vezes por um provedor de DNS, vários registros SPF, uma prioridade de MX errada e o proxy do Cloudflare.

$ spacepost domains doctor acme.com
acme.com  API status: pending

   RECORD  TYPE   HOST                              RESULT
✓  DKIM    CNAME  abc._domainkey.acme.com           matches
✗  SPF     MX     send.acme.com                     not found
✗  SPF     TXT    send.acme.com                     found v=spf1 include:_spf.google.com ~all
!  DMARC   TXT    _dmarc.acme.com                   not found (recommended)

How to fix
  ✗ MX send.acme.com
      Add a MX record: name "send", value "feedback-smtp.eu-central-1.amazonses.com", priority 10.
  ✗ TXT send.acme.com
      Your SPF record lacks the SpacePost include. ...

Use --dns-server 1.1.1.1 para ignorar o cache desatualizado do resolvedor local. O código de saída é 1 quando um registro obrigatório está ausente ou errado, então ele serve como verificação em CI.

Chaves de API e webhooks

spacepost keys create --name worker-prod --permission sending_access --domain <domain-id>
spacepost keys list
spacepost keys rm <id> [--yes]

spacepost webhooks list
spacepost webhooks create --endpoint https://acme.com/webhooks/spacepost --event email.delivered --event email.bounced
spacepost webhooks rm <id> [--yes]

keys create imprime o token uma única vez. webhooks create imprime o signing_secret. --event é repetível (não existe uma forma separada por vírgulas), e --domain exige --permission sending_access.

Tenants (modo plataforma)

spacepost tenants create --name "Acme Inc" --external-id cust_123 --daily-limit 500
spacepost tenants list [--limit 20]
spacepost tenants get cust_123                 # <ref> is our id or your external id
spacepost tenants pause cust_123 --reason "Investigating spam reports"
spacepost tenants unpause cust_123             # 403 for reputation pauses unless your team is trusted
spacepost tenants rm cust_123 [--yes]          # 422 while the tenant still has domains

Veja Modo plataforma (tenants) para saber o que os tenants isolam e como domínios e webhooks se encaixam.

Scripts

spacepost emails list --json | jq -r '.data[] | select(.last_event=="bounced") | .to[]'
id=$(spacepost send --from hello@acme.com --to delivered@test.spacepost.dev --subject Test --text hi --json | jq -r .id)
spacepost emails get "$id" --json | jq .last_event

Os comandos destrutivos (domains rm, keys rm, webhooks rm, tenants rm) pedem confirmação; em scripts e com --json, passe --yes.

Códigos de saída e erros

Código	Significado
`0`	Sucesso
`1`	Erro da API ou de execução (também `domains doctor` quando um registro obrigatório está ausente)
`2`	Erro de uso: comando ou flag desconhecido, opção obrigatória ausente

Os erros vão para o stderr com uma dica, quando há uma. Com --json, são impressos como JSON no stderr: { "error": { "name", "message", "statusCode", "hint" } }.

Variáveis de ambiente

Variável	Finalidade
`SPACEPOST_API_KEY`	Chave de API (substitui o login armazenado)
`SPACEPOST_BASE_URL`	URL base alternativa da API
`SPACEPOST_APP_URL`	URL do painel impressa por `spacepost open`
`XDG_CONFIG_HOME`	Onde o login é armazenado (`$XDG_CONFIG_HOME/spacepost/config.json`)
`NO_COLOR`	Desativa as cores