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>`	웹훅 엔드포인트
`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 레코드(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 키와 웹훅

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

테넌트가 무엇을 분리하고 도메인과 웹훅이 어떻게 연결되는지는 플랫폼 모드(테넌트)를 참고하세요.

스크립트 작성

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`	색상 비활성화