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`	本文: プレーンテキスト(`-` で標準入力を読み込み)、インライン HTML、または HTML ファイル。少なくとも 1 つが必須で、`--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 レコード(CNAME、TXT、MX)を公開 DNS で調べ、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 の場合は、stderr に JSON で出力されます: { "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`	色を無効にします