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"

Mit spacepost --help siehst du alle Befehle und mit spacepost <command> --help die Optionen eines Befehls.

Authentifizierung

spacepost login fragt nach deinem API-Schlüssel, prüft ihn gegen die API und speichert ihn in ~/.config/spacepost/config.json (Modus 0600, beachtet XDG_CONFIG_HOME). Auch Eingaben per Pipe funktionieren: echo $KEY | spacepost login. Setze in CI oder Skripten stattdessen die Umgebungsvariable:

export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"
spacepost whoami

Der Schlüssel stammt aus --api-key, dann aus SPACEPOST_API_KEY, dann aus dem gespeicherten Login. Die Basis-URL der API stammt aus --base-url, dann aus SPACEPOST_BASE_URL, dann aus dem gespeicherten Login, dann ist es https://api.spacepost.dev.

Befehle

Befehl	Was er tut
login, logout, whoami	Verwaltet Zugangsdaten. whoami zeigt den maskierten Schlüssel, die Basis-URL und die Anzahl der Domains
send	Sendet eine E-Mail
emails list, emails get <id>, emails cancel <id>	Untersucht E-Mails, storniert geplante
domains add <name>, list, get <id|name>, verify <id|name>, doctor <id|name>, rm <id|name>	Verwaltet Domains per ID oder Name
keys create, keys list, keys rm <id>	API-Schlüssel
webhooks list, webhooks create, webhooks rm <id>	Webhook-Endpoints
tenants list, create, get <ref>, pause <ref>, unpause <ref>, rm <ref>	Tenants des Plattform-Modus
open	Gibt die Dashboard-URL aus (und öffnet sie)

Globale Flags: --api-key, --base-url, --json, -y/--yes (Bestätigungen überspringen), -h/--help, -v/--version. Farben beachten NO_COLOR.

Senden

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	Beschreibung
--from	Absender auf einer verifizierten Domain (erforderlich)
--to	Empfänger (erforderlich; wiederhole das Flag für mehrere)
--subject	Betreff (erforderlich)
--text, --html, --html-file	Body: Nur-Text (- liest stdin), Inline-HTML oder eine HTML-Datei. Mindestens eines ist erforderlich; --html und --html-file lassen sich nicht kombinieren
--cc, --bcc, --reply-to	Wiederholbar
--tag name=value	Wiederholbarer Tag
--schedule "in 1 hour"	ISO-8601-Zeit oder natürliche Sprache
--attach <file>	Wiederholbarer Dateianhang
--tenant <id|external-id>	Im Namen eines Tenants senden

Bei Erfolg wird ✓ Queued: <id> ausgegeben (mit --json die API-Antwort { "id": "..." }).

E-Mails

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

Domains

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 gibt die anzulegenden DNS-Einträge aus. --tenant macht die Domain zu einer Domain im Besitz eines Tenants (siehe Plattform-Modus).

domains doctor

spacepost domains doctor <id|name> fragt jeden erwarteten DNS-Eintrag (CNAME, TXT, MX) im öffentlichen DNS ab, vergleicht ihn mit dem, was SpacePost erwartet, und gibt aus, was fehlt oder falsch ist, jeweils mit einer Lösung. Erkannt werden ein von einem DNS-Anbieter doppelt angehängter Domainname, mehrere SPF-Einträge, eine falsche MX-Priorität und Cloudflare-Proxying.

$ 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. ...

Mit --dns-server 1.1.1.1 umgehst du einen veralteten lokalen Resolver-Cache. Der Exit-Code ist 1, wenn ein erforderlicher Eintrag fehlt oder falsch ist, sodass sich der Befehl als CI-Prüfung eignet.

API-Schlüssel und 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 gibt das Token einmal aus. webhooks create gibt das signing_secret aus. --event ist wiederholbar (es gibt keine kommagetrennte Form), und --domain erfordert --permission sending_access.

Tenants (Plattform-Modus)

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

Was Tenants isolieren und wie Domains und Webhooks dazugehören, steht unter Plattform-Modus (Tenants).

Skripting

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

Destruktive Befehle (domains rm, keys rm, webhooks rm, tenants rm) fragen nach einer Bestätigung; in Skripten und mit --json übergibst du --yes.

Exit-Codes und Fehler

Code	Bedeutung
0	Erfolg
1	API- oder Laufzeitfehler (auch domains doctor, wenn ein erforderlicher Eintrag fehlt)
2	Verwendungsfehler: unbekannter Befehl oder unbekanntes Flag, fehlende Pflichtoption

Fehler gehen mit einem Hinweis, wo es einen gibt, nach stderr. Mit --json werden sie als JSON auf stderr ausgegeben: { "error": { "name", "message", "statusCode", "hint" } }.

Umgebungsvariablen

Variable	Zweck
SPACEPOST_API_KEY	API-Schlüssel (überschreibt den gespeicherten Login)
SPACEPOST_BASE_URL	Alternative Basis-URL der API
SPACEPOST_APP_URL	Dashboard-URL, die spacepost open ausgibt
XDG_CONFIG_HOME	Wo der Login gespeichert wird ($XDG_CONFIG_HOME/spacepost/config.json)
NO_COLOR	Farben deaktivieren