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"

运行 spacepost --help 查看所有命令，运行 spacepost <command> --help 查看某个命令的选项。

身份验证

spacepost login 会询问你的 API 密钥，向 API 校验后将其保存到 ~/.config/spacepost/config.json（权限 0600，遵循 XDG_CONFIG_HOME）。也支持管道输入：echo $KEY | spacepost login。在 CI 或脚本中，请改为设置环境变量：

export SPACEPOST_API_KEY="sp_live_YOUR_API_KEY"
spacepost whoami

密钥的来源优先级依次为：--api-key、SPACEPOST_API_KEY、已保存的登录信息。API 基础 URL 的来源优先级依次为：--base-url、SPACEPOST_BASE_URL、已保存的登录信息、https://api.spacepost.dev。

命令

命令	作用
`login`, `logout`, `whoami`	管理凭据。`whoami` 会显示脱敏后的密钥、基础 URL 和域名数量
`send`	发送邮件
`emails list`, `emails get <id>`, `emails cancel <id>`	查看邮件，取消定时邮件
`domains add <name>`, `list`, `get <id\|name>`, `verify <id\|name>`, `doctor <id\|name>`, `rm <id\|name>`	按 id 或名称管理域名
`keys create`, `keys list`, `keys rm <id>`	API 密钥
`webhooks list`, `webhooks create`, `webhooks rm <id>`	Webhook 端点
`tenants list`, `create`, `get <ref>`, `pause <ref>`, `unpause <ref>`, `rm <ref>`	平台模式租户
`open`	打印（并打开）控制台 URL

全局标志：--api-key、--base-url、--json、-y/--yes（跳过确认）、-h/--help、-v/--version。颜色输出遵循 NO_COLOR。

发送

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 -

标志	说明
`--from`	已验证域名上的发件人（必填）
`--to`	收件人（必填；多个收件人时重复该标志）
`--subject`	主题（必填）
`--text`, `--html`, `--html-file`	正文：纯文本（`-` 表示从 stdin 读取）、内联 HTML 或 HTML 文件。至少需要一个；`--html` 和 `--html-file` 不能同时使用
`--cc`, `--bcc`, `--reply-to`	可重复使用
`--tag name=value`	可重复使用的标签
`--schedule "in 1 hour"`	ISO 8601 时间或自然语言
`--attach <file>`	可重复使用的文件附件
`--tenant <id\|external-id>`	代表某个租户发送

成功时会打印 ✓ Queued: <id>（使用 --json 时，则输出 API 响应 { "id": "..." }）。

邮件

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

域名

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 会打印需要创建的 DNS 记录。--tenant 会让该域名归租户所有（参见平台模式）。

domains doctor

spacepost domains doctor <id|name> 会在公共 DNS 中查询每一条应有的 DNS 记录（CNAME、TXT、MX），与 SpacePost 的预期进行比较，并打印缺失或错误的内容及对应的修复方法。它能检测出 DNS 服务商重复追加域名、存在多条 SPF 记录、MX 优先级错误以及 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. ...

使用 --dns-server 1.1.1.1 可绕过过期的本地解析器缓存。当必需的记录缺失或有误时，退出码为 1，因此可以作为 CI 检查使用。

API 密钥与 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 只会打印一次令牌。webhooks create 会打印 signing_secret。--event 可以重复使用（不支持逗号分隔的写法），--domain 需要配合 --permission sending_access。

租户（平台模式）

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

租户隔离哪些内容，以及域名和 Webhook 如何配合，请参见平台模式（租户）。

脚本化

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

具有破坏性的命令（domains rm、keys rm、webhooks rm、tenants rm）会要求确认；在脚本中以及使用 --json 时，请传入 --yes。

退出码与错误

退出码	含义
`0`	成功
`1`	API 或运行时错误（当必需的记录缺失时，`domains doctor` 也会返回该值）
`2`	用法错误：未知的命令或标志、缺少必需的选项

错误会输出到 stderr，并在有提示时附上提示。使用 --json 时，它们会以 JSON 形式打印到 stderr：{ "error": { "name", "message", "statusCode", "hint" } }。

环境变量

变量	用途
`SPACEPOST_API_KEY`	API 密钥（覆盖已保存的登录信息）
`SPACEPOST_BASE_URL`	备用的 API 基础 URL
`SPACEPOST_APP_URL`	`spacepost open` 打印的控制台 URL
`XDG_CONFIG_HOME`	登录信息的保存位置（`$XDG_CONFIG_HOME/spacepost/config.json`）
`NO_COLOR`	禁用颜色