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"

Esegui spacepost --help per tutti i comandi e spacepost <command> --help per le opzioni di un singolo comando.

Autenticazione

spacepost login ti chiede la chiave API, la verifica sull’API e la salva in ~/.config/spacepost/config.json (modalità 0600, rispetta XDG_CONFIG_HOME). Funziona anche l’input da pipe: echo $KEY | spacepost login. In CI o negli script imposta invece la variabile d’ambiente:

export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"
spacepost whoami

La chiave viene da --api-key, poi da SPACEPOST_API_KEY, poi dal login salvato. L’URL di base dell’API viene da --base-url, poi da SPACEPOST_BASE_URL, poi dal login salvato, poi da https://api.spacepost.dev.

Comandi

Comando	Che cosa fa
login, logout, whoami	Gestiscono le credenziali. whoami mostra la chiave mascherata, l’URL di base e il numero di domini
send	Invia un’email
emails list, emails get <id>, emails cancel <id>	Ispezionano le email, annullano quelle pianificate
domains add <name>, list, get <id|name>, verify <id|name>, doctor <id|name>, rm <id|name>	Gestiscono i domini per id o nome
keys create, keys list, keys rm <id>	Chiavi API
webhooks list, webhooks create, webhooks rm <id>	Endpoint dei webhook
tenants list, create, get <ref>, pause <ref>, unpause <ref>, rm <ref>	Tenant della modalità piattaforma
open	Stampa (e apre) l’URL della dashboard

Flag globali: --api-key, --base-url, --json, -y/--yes (salta le conferme), -h/--help, -v/--version. I colori rispettano NO_COLOR.

Inviare

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	Descrizione
--from	Mittente su un dominio verificato (obbligatorio)
--to	Destinatario (obbligatorio; ripeti il flag per più destinatari)
--subject	Oggetto (obbligatorio)
--text, --html, --html-file	Corpo: testo semplice (- legge da stdin), HTML inline oppure un file HTML. Ne serve almeno uno; --html e --html-file non si possono combinare
--cc, --bcc, --reply-to	Ripetibili
--tag name=value	Tag ripetibile
--schedule "in 1 hour"	Orario ISO 8601 o linguaggio naturale
--attach <file>	Allegato ripetibile
--tenant <id|external-id>	Invia per conto di un tenant

In caso di successo stampa ✓ Queued: <id> (con --json, la risposta dell’API { "id": "..." }).

Email

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

Domini

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 stampa i record DNS da creare. --tenant rende il dominio di proprietà del tenant (vedi Modalità piattaforma).

domains doctor

spacepost domains doctor <id|name> cerca nel DNS pubblico ogni record DNS atteso (CNAME, TXT, MX), lo confronta con quanto si aspetta SpacePost e stampa che cosa manca o è sbagliato, con una soluzione per ciascun caso. Rileva il nome del dominio aggiunto due volte da un provider DNS, più record SPF, una priorità MX errata e il proxy di 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. ...

Usa --dns-server 1.1.1.1 per aggirare una cache obsoleta del resolver locale. Il codice di uscita è 1 quando un record obbligatorio manca o è sbagliato, quindi funziona come controllo in CI.

Chiavi API e webhook

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 stampa il token una sola volta. webhooks create stampa il signing_secret. --event è ripetibile (non esiste una forma separata da virgole), e --domain richiede --permission sending_access.

Tenant (modalità piattaforma)

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

Vedi Modalità piattaforma (tenant) per sapere che cosa isolano i tenant e come si inseriscono domini e webhook.

Scripting

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

I comandi distruttivi (domains rm, keys rm, webhooks rm, tenants rm) chiedono conferma; negli script e con --json passa --yes.

Codici di uscita ed errori

Codice	Significato
0	Successo
1	Errore dell’API o di runtime (anche domains doctor quando manca un record obbligatorio)
2	Errore d’uso: comando o flag sconosciuto, opzione obbligatoria mancante

Gli errori vanno su stderr con un suggerimento quando c’è. Con --json vengono stampati come JSON su stderr: { "error": { "name", "message", "statusCode", "hint" } }.

Variabili d’ambiente

Variabile	Scopo
SPACEPOST_API_KEY	Chiave API (ha la precedenza sul login salvato)
SPACEPOST_BASE_URL	URL di base alternativo dell’API
SPACEPOST_APP_URL	URL della dashboard stampato da spacepost open
XDG_CONFIG_HOME	Dove viene salvato il login ($XDG_CONFIG_HOME/spacepost/config.json)
NO_COLOR	Disattiva i colori