Shipmail CLI

Official command line interface for the Shipmail API.

npx -y shipmail-cli --help

Authentication

Most commands require an API key. Create one in the Shipmail dashboard and export it:

export SHIPMAIL_API_KEY="sm_live_..."

You can also pass --api-key to any command. Use SHIPMAIL_BASE_URL or --base-url when targeting a non-production API. Approved partners can set SHIPMAIL_ORGANIZATION_ID or pass --organization-id for delegated infrastructure calls.

Common Commands

# Check public API health
shipmail status

# Create a domain, retrieve records, and verify DNS
shipmail domains create example.com
shipmail domains dns-records dom_123
shipmail domains verify dom_123

# Create a mailbox
shipmail mailboxes create --domain-id dom_123 --address hello --password-file ./mailbox-password.txt --display-name "Hello"
shipmail mailboxes suspend mbx_123
shipmail mailboxes resume mbx_123
shipmail mailboxes forwarding-add mbx_123 --destination [email protected]
shipmail mailboxes forwarding mbx_123
shipmail mailboxes forwarding-remove mbx_123 fwd_123
shipmail mailboxes rules mbx_123
shipmail mailboxes app-passwords list mbx_123
shipmail mailboxes app-passwords create mbx_123 --name "Desktop mail" --expires-at 2026-10-01T00:00:00Z
shipmail mailboxes app-passwords revoke mbx_123 appwd_123

# Send email
shipmail messages send \
  --mailbox-id mbx_123 \
  --to [email protected] \
  --subject "Hello" \
  --text "It works." \
  --client-reference crm-123 \
  --metadata '{"campaign":"onboarding"}' \
  --source-rfc-message-id '<[email protected]>'

shipmail messages list --client-reference crm-123
shipmail messages analytics --updated-after 2026-07-01T00:00:00Z --limit 100
shipmail messages reply msg_123 --to [email protected] --text "Thanks"

# Stage a raw file, then pass the returned sat_... ID when sending
shipmail mailboxes stage-attachment mbx_123 ./invoice.pdf --content-type application/pdf

# Prepare a five-minute, single-use upload URL for a browser-hosted component
shipmail mailboxes prepare-attachment-upload mbx_123 ./invoice.pdf --content-type application/pdf

shipmail messages send \
  --mailbox-id mbx_123 \
  --to [email protected] \
  --subject "Invoice" \
  --text "Attached." \
  --staged-attachment-id sat_123 \
  --scheduled-at 2026-08-01T08:00:00.000Z

shipmail scheduled-messages list
shipmail scheduled-messages get msg_123
shipmail scheduled-messages update msg_123 \
  --to [email protected] \
  --subject "Updated invoice" \
  --text "Attached." \
  --staged-attachment-id sat_123 \
  --scheduled-at 2026-08-02T08:00:00.000Z
shipmail scheduled-messages cancel msg_123

# Use an sm_test_... key to simulate an outbound result and fake inbound reply
shipmail messages send --mailbox-id mbx_123 --to [email protected] --subject "Test" --text "Not delivered" --sandbox-outcome bounced
shipmail mailboxes sandbox-inbound mbx_123 --from [email protected] --subject "Re: Test" --text "Fake inbound reply"

# Read inbound mail
shipmail inbox list 550e8400-e29b-41d4-a716-446655440000 --folder-role inbox --after 2025-07-20T00:00:00Z --limit 25
shipmail inbox message 550e8400-e29b-41d4-a716-446655440000 eml_123
shipmail inbox threads 550e8400-e29b-41d4-a716-446655440000 --attention-state needs_reply --after 2025-07-20T00:00:00Z --limit 50
shipmail inbox thread 550e8400-e29b-41d4-a716-446655440000 thr_123
shipmail inbox draft 550e8400-e29b-41d4-a716-446655440000 thr_123 --expected-version 7 --text "Thanks for the note"
# Apply your approval policy; stale drafts fail with 409 without delivery.
shipmail inbox send-draft 550e8400-e29b-41d4-a716-446655440000 thr_123 drf_123
shipmail inbox thread-attention 550e8400-e29b-41d4-a716-446655440000 thr_123 --done true --expected-version 8
shipmail inbox reply-message 550e8400-e29b-41d4-a716-446655440000 eml_123 --to [email protected] --text "Thanks"
shipmail inbox reply-thread 550e8400-e29b-41d4-a716-446655440000 thr_123 --to [email protected] --text "Following up"

# Frozen historical scan, retained for 30 days (repeat --mailbox-id for more mailboxes)
shipmail reply-scans create --mailbox-id 550e8400-e29b-41d4-a716-446655440000 --after 2025-07-20T00:00:00Z
shipmail reply-scans status rsc_123
shipmail reply-scans results rsc_123 --limit 100

# Find reusable sender identity IDs, then create a draft with blocks
shipmail newsletter-sender-identities list
shipmail newsletters create \
  --audience-id aud_123 \
  --sender-identity-id nwsid_456 \
  --name "July changelog" \
  --subject "What shipped in July" \
  --blocks @blocks.json
shipmail newsletters update nws_123 --subject "Updated subject"
# A concurrent update exits with conflict (409); fetch the latest newsletter before retrying.
shipmail newsletters preview nws_123
shipmail newsletters test-send nws_123 --recipient-email [email protected]
shipmail newsletters preflight nws_123
shipmail newsletters schedule nws_123 --scheduled-at 2026-08-01T09:00:00.000Z
shipmail newsletter-assets list --kind image --q hero --limit 25
shipmail newsletter-assets upload ./hero.png --content-type image/png
shipmail newsletter-assets upload ./demo.mp4 --content-type video/mp4 --thumbnail ./demo-poster.jpg
shipmail newsletter-assets register-url https://cdn.shipmail.to/newsletter-images/org_123/hero.png

# Manage webhooks
shipmail webhooks create \
  --url https://example.com/shipmail/webhook \
  --events message.received,message.bounced
shipmail webhooks deliveries whk_123 --status failed
shipmail webhooks replay-delivery whk_123 dlv_123 --idempotency-key replay-123

# Partner beta lifecycle and delegated infrastructure
shipmail partner organizations create --name "Operator" --external-reference operator_123 --owner-email [email protected] --mailbox-limit 3 --data-classification internal_test
shipmail partner usage
shipmail partner credential-grants list
shipmail partner credential-grants consume grant_123 --name "Embedded webmail"
shipmail domains list --organization-id 00000000-0000-4000-8000-000000000123
shipmail mailboxes create --organization-id 00000000-0000-4000-8000-000000000123 --domain-id dom_123 --address support --generate-password

Paragraph, quote, callout, list-item, and column bodies in --blocks accept bare text or sanitized inline HTML. Use <p> and <br> for line breaks. Shipmail keeps a, b, br, code, em, i, p, s, span, strong, and u, with safe attributes and URLs.

newsletter-assets upload uses a five-minute direct storage PUT, then calls the single-use completion URL. Video uploads require a JPEG poster through --thumbnail. newsletter-assets list includes current newsletter media storage usage and a pagination.next_cursor value in the JSON response. Pass that opaque value back with --cursor to browse the next page.

Generic API Command

The api command reaches every Shipmail REST endpoint, including endpoints that do not have a shorthand command yet.

shipmail api GET /domains

Use repeatable --header "Name: value" flags for request headers. Use --output path to write non-JSON responses, such as attachment downloads.

Command Surface

• status
• api <METHOD> <PATH>
• domains list|search|create|get|verify|delete
• mailboxes list|create|get|suspend|resume|forwarding|forwarding-add|forwarding-remove|app-passwords|folders|identities|stage-attachment|prepare-attachment-upload
• inbox list|message|threads|thread|thread-state|draft|send-draft|reply-message|reply-thread|update|move
• reply-scans create|status|results
• messages send|list|analytics|get|reply (test keys also support --sandbox-outcome)
• scheduled-messages list|get|update|cancel
• mailboxes sandbox-inbound
• webhooks list|create|test|deliveries|replay-delivery
• suppressions list|remove
• audiences list|create|get|update|delete
• audiences feed get|update|rotate|revoke
• audiences subscribers add|list|get|by-email|update|unsubscribe|resubscribe|remove
• newsletter-sender-identities list
• newsletter-domains list
• newsletters create|update|preview|preflight|test-send|schedule|cancel|resume
• newsletter-assets list|upload|register-url
• partner organizations list|create|get|update|invite|suspend|resume|offboard
• partner credential-grants list|consume
• partner usage

Configure a publisher-owned Atom self URL and the number of recent issues:

shipmail audiences feed update aud_123 \
  --canonical-url https://example.com/feed.xml \
  --entry-limit 25

Run shipmail --help for flags and examples.