CLI

The official shipmail-cli package gives agents, operators, and scripts a terminal-native way to call the ShipMail API. It includes shorthand commands for common workflows plus a raw API command for every REST endpoint.

Last updated July 5, 2026

Install

npx -y shipmail-cli --help

# Or install globally
npm install -g shipmail-cli
shipmail --help

Authentication

Authenticated commands read SHIPMAIL_API_KEY. You can also pass --api-key to any command.

export SHIPMAIL_API_KEY="sm_live_..."

# Optional for local or preview APIs
export SHIPMAIL_BASE_URL="https://shipmail.to/api/v1"

Quick workflow

# Check public API health
shipmail status

# Create and verify a domain
shipmail domains create example.com
shipmail domains verify dom_123

# Create a mailbox
shipmail mailboxes create --domain-id dom_123 --address hello --display-name "Hello"

# Send email
shipmail messages send \
  --mailbox-id mbx_123 \
  --to user@example.com \
  --subject "Hello" \
  --text "It works."

# Read inbound mail
shipmail inbox list mbx_123 --folder-role inbox --limit 25
shipmail inbox thread mbx_123 thr_123

Raw API calls

Use shipmail api for endpoints that need full JSON bodies, binary downloads, or custom headers. Paths are relative to the API base URL.

shipmail api GET /domains

shipmail api PATCH /mailboxes/mbx_123/spam-filter \
  --data '{"threshold":6}'

shipmail api PUT /mailboxes/mbx_123/rules \
  --data @rules.json

shipmail api GET "/mailboxes/mbx_123/inbox/attachments?blob_id=abc&name=invoice.pdf" \
  --output invoice.pdf

Commands

Area	Commands
status	Public API health check.
api	Raw method/path requests with JSON data, extra headers, and file output.
domains	list, search, create, get, verify, delete
mailboxes	list, create, get, folders, identities, rules
inbox	list, thread, update, move
messages	send, list, get
webhooks	list, create, test, deliveries
suppressions	list, remove
newsletter-domains	list
newsletters	create, update, preview, preflight, test-send, schedule, cancel, resume
newsletter-assets	list, upload, register-url
audiences	create, list, get, update, delete; subscribers add, list, get, by-email, update, unsubscribe, remove

Newsletter example

shipmail newsletter-domains list

shipmail newsletters create \
  --audience-id aud_123 \
  --newsletter-domain-id nwsdom_456 \
  --name "July changelog" \
  --subject "What shipped in July" \
  --blocks @blocks.json

shipmail newsletters update nws_789 --subject "Updated subject"

shipmail newsletters preview nws_789
shipmail newsletters test-send nws_789 --recipient-email owner@example.com
shipmail newsletters preflight nws_789
shipmail newsletters schedule nws_789 --scheduled-at 2026-08-01T09:00:00.000Z

Prefer --blocks @file.json for draft bodies. You can also pass --body-html or --body-text. Create requires at least one body field. Update requires at least one field to change. Test sends and schedules must pass newsletter preflight.

Webhook example

shipmail webhooks create \
  --url https://example.com/shipmail/webhook \
  --events message.received,message.bounced \
  --description "Production webhook"

shipmail webhooks deliveries whk_123 --status failed