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 May 14, 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

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