CLI
The official shipmail-cli package calls the Shipmail API from a terminal, for you, your scripts or your agents. Short commands cover the everyday jobs, and shipmail api reaches every REST endpoint.
Last updated
Install
npx -y shipmail-cli --help
# Or install globally
npm install -g shipmail-cli
shipmail --helpTeach your coding agent Shipmail
One command adds the Shipmail skill to the current project, for Claude Code, Codex and Cursor. It writes .claude/skills/shipmail/SKILL.md and .agents/skills/shipmail/SKILL.md from the latest shipmail.to/skill.md. Commit them so your team gets them too, or add --global to install it in your home folder for every project. Run it again to update the skill.
npx -y shipmail-cli skills install
# Every project on this computer
npx -y shipmail-cli skills install --globalMember roles and mailbox access
shipmail members list --limit 25
shipmail members get mem_alice --json
# Needs members:write
shipmail members invite sam@acme.com --role member --mailbox mbx_123 [--all-mailboxes] [--newsletter-editor]
shipmail members invitations list
shipmail members invitations cancel inv_sam
shipmail members mailboxes grant mem_alice mbx_123
shipmail members mailboxes revoke mem_alice mbx_123Roles are owner, admin, or member. mailbox_access contains a scope of all or selected and a mailbox_ids array, empty for all.
With selected access, you only see the mailbox IDs your key can reach, so the list may be incomplete. An empty selected list may mean no grants or no visible grants. A key with only members:read has no mail reach and returns no selected mailbox IDs. JSON output keeps this access object as is.
Inviting people and sharing mailboxes need members:write, which no preset includes (an All access key does). The invitee receives an email and creates their own account; you never receive their credentials. See the Members API for who may grant which mailboxes.
Sandbox commands
With an sm_test_... key, use --sandbox-outcome on sends and mailboxes sandbox-inbound for fake replies. See the sandbox guide.
Authentication
Run shipmail login once to sign in through the browser. The CLI opens Shipmail, you choose the organizations it may reach, and every command then runs without an API key. Agents such as Claude Code and Codex that run the CLI on your computer use the same login.
shipmail login
# Print the URL instead of opening a browser
shipmail login --no-browser
# Sign out and revoke the login
shipmail logoutThe login is saved in the macOS Keychain, in the Secret Service through secret-tool on Linux, or otherwise in ~/.config/shipmail/credentials.json, readable only by you. It refreshes itself. When it expires or is revoked, the CLI deletes it and asks you to run shipmail login again.
If the login can reach several organizations, pass --organization org_... or set SHIPMAIL_ORGANIZATION. To save a default, run shipmail login --organization org_....
An API key still works and wins over the login. The CLI checks first --api-key, then SHIPMAIL_API_KEY, then the saved login. Use an API key for servers and CI, where no browser is available.
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 dns-records d290f1ee-6c54-4b01-90e6-d701748f0851
shipmail domains verify d290f1ee-6c54-4b01-90e6-d701748f0851
shipmail domains health d290f1ee-6c54-4b01-90e6-d701748f0851
# Create a mailbox
shipmail mailboxes create --domain-id d290f1ee-6c54-4b01-90e6-d701748f0851 --address hello --password-file ./mailbox-password.txt --display-name "Hello"
shipmail mailboxes rules f47ac10b-58cc-4372-a567-0e02b2c3d479
shipmail mailboxes suspend f47ac10b-58cc-4372-a567-0e02b2c3d479
shipmail mailboxes resume f47ac10b-58cc-4372-a567-0e02b2c3d479
shipmail mailboxes alias-add f47ac10b-58cc-4372-a567-0e02b2c3d479 --address sales
shipmail mailboxes forwarding-add f47ac10b-58cc-4372-a567-0e02b2c3d479 --destination owner@example.net --recipient nabeel@example.com
shipmail mailboxes forwarding-add f47ac10b-58cc-4372-a567-0e02b2c3d479 --destination accountant@example.net --rules-only
# Forward bounces and automatic replies too (new destinations skip them)
shipmail mailboxes forwarding-add f47ac10b-58cc-4372-a567-0e02b2c3d479 --destination owner@example.net --recipient nabeel@example.com --skip-automated false
shipmail mailboxes forwarding f47ac10b-58cc-4372-a567-0e02b2c3d479
shipmail mailboxes app-passwords list f47ac10b-58cc-4372-a567-0e02b2c3d479
shipmail mailboxes app-passwords create f47ac10b-58cc-4372-a567-0e02b2c3d479 --name "Desktop mail" --expires-at 2026-10-01T00:00:00Z
shipmail mailboxes app-passwords revoke f47ac10b-58cc-4372-a567-0e02b2c3d479 appwd_0123456789abcdefghjkmnpq
# SMTP credentials for a transactional sender (the password is printed once)
shipmail smtp-credentials create --from notifications@notify.example.com --name "Supabase Auth"
shipmail smtp-credentials list --from notifications@notify.example.com
shipmail smtp-credentials revoke smtpc_0123456789abcdefghjkmnpq
# Transactional setup: sending subdomain, DNS records, verification, From address
shipmail transactional-domains create --root-domain example.com --subdomain notify
shipmail transactional-domains verify txdom_0123456789abcdefghjkmnpq
shipmail transactional-senders create --domain-id txdom_0123456789abcdefghjkmnpq --mailbox-id f47ac10b-58cc-4372-a567-0e02b2c3d479 --local-part notifications --display-name "Acme"
shipmail transactional-senders update txbind_0123456789abcdefghjkmnpq --state disabled
shipmail mailboxes export f47ac10b-58cc-4372-a567-0e02b2c3d479
shipmail mailboxes export-status f47ac10b-58cc-4372-a567-0e02b2c3d479 mbexp_0123456789abcdefghjkmnpq
shipmail mailboxes import-resume f47ac10b-58cc-4372-a567-0e02b2c3d479 imp_0123456789abcdefghjkmnpq
shipmail mailboxes import-restore f47ac10b-58cc-4372-a567-0e02b2c3d479 imp_0123456789abcdefghjkmnpq --file-id impf_0123456789abcdefghjkmnpq
# Send email
shipmail messages send \
--mailbox-id f47ac10b-58cc-4372-a567-0e02b2c3d479 \
--to user@example.com \
--subject "Hello" \
--text "It works." \
--client-reference crm-123 \
--metadata '{"campaign":"onboarding"}' \
--source-rfc-message-id '<crm-123@example.com>'
# Find the same message later
shipmail messages list --client-reference crm-123
# Pull an analytics-safe incremental page
shipmail messages analytics --updated-after 2026-07-01T00:00:00Z --limit 100
# Reply while keeping your own correlation reference
shipmail messages reply msg_123 --to user@example.com --text "Thanks" --client-reference crm-reply-123
# Accept, tentatively accept or decline the calendar invitation a message carries
shipmail messages invitation respond msg_123 --response accepted
# Read inbound mail
shipmail inbox list f47ac10b-58cc-4372-a567-0e02b2c3d479 --folder-role inbox --limit 25
# Filter by sender, To recipient, subject or attachment (--has-attachment false for none)
shipmail inbox list f47ac10b-58cc-4372-a567-0e02b2c3d479 --from billing@vendor.example --subject invoice --has-attachment
# Unread mail only (--unread false for read mail), as a message list or as threads
shipmail inbox list f47ac10b-58cc-4372-a567-0e02b2c3d479 --unread
shipmail inbox threads f47ac10b-58cc-4372-a567-0e02b2c3d479 --unread
shipmail inbox threads f47ac10b-58cc-4372-a567-0e02b2c3d479 --attention-state needs_reply --after 2025-07-20T00:00:00Z
shipmail inbox thread f47ac10b-58cc-4372-a567-0e02b2c3d479 thr_123
# Create a server-addressed draft from the returned version, review it, then send
# --quote-history quotes their message below your text when it is sent
shipmail inbox draft f47ac10b-58cc-4372-a567-0e02b2c3d479 thr_123 --expected-version 7 --text "Thanks" --quote-history
shipmail inbox send-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 thr_123 drf_123
# List, read, revise or delete reply drafts; the new body replaces the old one
shipmail inbox drafts f47ac10b-58cc-4372-a567-0e02b2c3d479 thr_123
shipmail inbox get-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 thr_123 drf_123
shipmail inbox update-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 thr_123 drf_123 --html "<p>Thanks for the note.</p>"
shipmail inbox delete-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 thr_123 drf_123
# Save a stored message as an .eml file
shipmail inbox raw f47ac10b-58cc-4372-a567-0e02b2c3d479 eml_123 --output message.eml
# Save a new email to Drafts for a person to review and send; this never sends
shipmail inbox compose-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 --to jane@example.com --subject "Quick intro" --text "Hi Jane,"
shipmail inbox get-compose-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 eml_draft_123
# Keep one file, add a staged upload; --clear-attachments removes them all
shipmail inbox update-compose-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 eml_draft_123 --keep-attachment Gc9a1b2c3d4 --staged-attachment-id sat_9k2m4x
shipmail inbox delete-compose-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 eml_draft_123
# Capture a frozen historical reply snapshot
shipmail reply-scans create --mailbox-id f47ac10b-58cc-4372-a567-0e02b2c3d479 --after 2025-07-20T00:00:00Z
shipmail reply-scans status rsc_123
shipmail reply-scans results rsc_123 --limit 100Attach files
Pass --attach <file>, once per file, to messages send (scheduled sends too), inbox draft, inbox compose-draft, inbox update-compose-draft, inbox update-draft and scheduled-messages update. The filename is the file's name and the content type comes from its extension, or application/octet-stream when the extension is unknown. Replies take no files.
messages send puts files inline when they total 7 MB or less, because the whole email can be 10 MB with encoding. Larger files are staged through --mailbox-id first, up to 25 MB each. A transactional sender takes inline files only, so a --from send without --mailbox-id stops with an error when its files are over 7 MB. Drafts and scheduled updates always stage files through their mailbox.
shipmail messages send --mailbox-id f47ac10b-58cc-4372-a567-0e02b2c3d479 \
--to customer@example.com --subject "Invoice" --text "Attached." \
--attach ./invoice.pdf --attach ./terms.pdf
shipmail inbox compose-draft f47ac10b-58cc-4372-a567-0e02b2c3d479 \
--to jane@example.com --subject "Proposal" --text "Hi Jane," --attach ./proposal.pdfEmail held for review
When the API key holds email to outside addresses for review, shipmail messages send and shipmail messages reply send nothing to a recipient outside your domains. They save the email to Drafts, print Held for review: saved as draft <id>. Outside recipients: ... and exit 0. With --json they print the held_message object.
Batch sends and reply state
shipmail messages send-batch takes --messages, a JSON array of up to 50 send bodies, inline or as @file like the other JSON options. It prints the batch id and one line per item: the sent message id, the held draft id, or the error. Pass --idempotency-key so a retry sends nothing twice, and --json for the full response.
shipmail messages send-batch --messages @batch.json --idempotency-key q4-outreach-1
shipmail messages list --batch-id msgb_abc123
shipmail threads list --batch-id msgb_abc123 \
--attention-state waiting_on_them \
--before 2026-11-05T00:00:00Zthreads list needs --mailbox-id or --batch-id. --attention-state takes one state or several, comma-separated, on threads list and inbox threads. --after is inclusive and --before exclusive. --unread on inbox list and inbox threads keeps unread mail, the team's read state in a mailbox whose read status is per person.
Raw API calls
Use shipmail api when you need a full JSON body, a binary download or a custom header. Paths are relative to the API base URL.
shipmail api GET /domains
shipmail api POST /mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/folders \
--data '{"name":"Finance"}'
shipmail api GET "/mailboxes/f47ac10b-58cc-4372-a567-0e02b2c3d479/inbox/attachments?message_id=eml_123&blob_id=abc&name=invoice.pdf" \
--output invoice.pdfCommands
| Area | Commands |
|---|---|
| login, logout | Sign in through the browser without an API key, and sign out. |
| status | Public API health check. |
| organization access | Plan, access, trial and mailbox capacity of the key's organization. When the organization owner can fix a refusal, the CLI prints the Shipmail link to send them. |
| organization get, update, ai-settings | Read and change the default time zone (--default-timezone Europe/Paris, or none to clear it) and the AI switches (ai-settings update --models-enabled or --automatic-send-enabled). Changes need an Owner or Admin. |
| api | Any method and path, with a JSON body, extra headers and output to a file. |
| automations | list, create, get, update, run, test (dry run on one message) |
| domains | list, search, create, get, dns-records, health, verify, delete |
| mailboxes | list, create, get, suspend, resume, aliases, alias-add, alias-remove, forwarding, forwarding-add, forwarding-remove, app-passwords, folders, identities, rules |
| members | list, get, invite, invitations list|cancel, mailboxes grant|revoke |
| inbox | list, thread, update, move |
| messages | send (with --template to send a stored template), send-batch, list (--batch-id), get |
| threads | list (--mailbox-id or --batch-id, with --attention-state, --after and --before) |
| templates | list, create, get, update, delete, publish, render, versions, version, restore |
| webhooks | list, create, update, test, deliveries |
| event-queues | list, create, get, delete, events, ack |
| smtp-credentials | list (filter by --from), create, revoke |
| transactional-domains | list, create, get, verify, delete |
| transactional-senders | list (filter by --domain-id), create, get, update |
| suppressions | add, list (filter by scope), remove, remove-batch, resubscribe (lift a newsletter opt-out) |
| customers | list, get, create, update, upsert, delete, reply-times, fields |
| newsletter-sender-identities | list, create, update, delete |
| newsletter-domains | list, create, verify, delete |
| newsletters | create, update, preview, preflight, test-send, schedule, cancel, resume |
| newsletter-assets | list, upload, register-url |
| audiences | create, list, get, update, delete; subscribers add, add-batch (--dry-run), list, get, by-email, update, unsubscribe (--scope organization or audience), resubscribe, resend-confirmation, remove; feed get, update, rotate, revoke; segments list, create, get, update, delete |
| calendar | events (list, create, get, update, delete), availability |
| booking-pages | list, create, get, update, delete |
| booking-links | list, create, get, update, revoke |
Newsletter media
shipmail newsletter-assets list --kind image --q hero --limit 25
shipmail newsletter-assets list --kind image --q hero --limit 25 --cursor "cursor-from-previous-response"
shipmail newsletter-assets upload ./hero.png --content-type image/png
shipmail newsletter-assets upload ./demo.mp4 --content-type video/mp4 --thumbnail ./demo-poster.jpgUpload sends the file straight to storage, then calls a one-time verification endpoint. A video also needs a JPEG poster, passed with --thumbnail.
Calendar invitation language
shipmail calendar events create --mailbox hello@yourdomain.com --title "Intro call" --start 2026-08-07T08:30:00 --timezone Europe/Paris --duration PT1H --operation-key calendar-create-01 --send-invitations true --invitation-language fr --attendees '[{"email":"guest@example.com"}]'--invitation-language accepts en, fr, or es for create and update commands. Reuse --operation-key only to retry the exact same payload. Updates also accept --expected-revision and --send-guest-updates.
Email templates
shipmail templates create \
--name "Welcome" \
--subject "Welcome, {{name}}" \
--html @welcome.html \
--fallback plan=Free \
--publish
shipmail templates render tpl_123 --var name=Ada
shipmail messages send --from hello@example.com --to ada@example.com \
--template tpl_123 --var name=Ada
shipmail templates update tpl_123 --subject "Welcome aboard, {{name}}"
shipmail templates publish tpl_123
shipmail templates versions tpl_123
shipmail templates restore tpl_123 1--html and --text take a value or an @file. Repeat --fallback key=value for each default. update changes the draft only, and --clear-html, --clear-text and --clear-fallbacks remove a field. render previews the draft, or a version with --template-version.
With messages send --template, the template supplies the subject and body, so --subject, --html and --text are refused. --var key=value sets a variable, and --template-version pins a version instead of the published one. A send missing a required variable fails with HTTP 422 and prints each detail with its code, such as missing_variable. See the Templates API.
Automations
shipmail automations create --name "Daily brief" --definition @automation.json
shipmail automations update aaut_123 --status paused
shipmail automations run aaut_123
shipmail automations test aaut_123 --mailbox-id mbx_support --message-id eml_123Pass the definition as inline JSON or as an @file. Create and update also take --idempotency-key. See the Automations API.
Audience feed settings
shipmail audiences feed update aud_123 \
--canonical-url https://example.com/feed.xml \
--entry-limit 25
shipmail audiences feed get aud_123--entry-limit must be a whole number from 10 to 100. The CLI rejects anything else before it sends the request. The canonical URL is your own HTTPS feed URL, and the feed lists it as its Atom self link.
Check a subscriber list before importing
# subscribers.json: [{ "email_address": "jane@example.com", "display_name": "Jane" }, ...]
shipmail audiences subscribers add-batch aud_123 --subscribers @subscribers.json --dry-run
# Then add them for real
shipmail audiences subscribers add-batch aud_123 --subscribers @subscribers.jsonadd-batch takes up to 1000 subscribers, as emails after the audience ID or as a JSON array in --subscribers. --dry-run shows what the import would do. Each row gets the outcome it would have, and nothing is added, charged or sent. A skipped_invalid row carries a reason code, and a typo carries the corrected address in suggestion. A dry run does not check the subscriber limit, the monthly add quota or the API key's recipient limits.
Booking page conferencing
shipmail booking-pages create --name "Intro" --mailbox hello@example.com --slug intro --duration-minutes 30 --availability-days 1,2,3,4,5 --window-start-minutes 540 --window-end-minutes 1020 --timezone America/New_York --conferencing-provider zoom
shipmail booking-pages update bkp_123 --conferencing-provider noneUse zoom or google_meet once the provider is connected to the page's mailbox. On update, none removes the provider. See conferencing setup.
Booking page slots
shipmail booking-pages slots bkp_123 --from 2026-11-09T00:00:00Z --to 2026-11-16T00:00:00ZPrints the open slots the page offers, exactly as its public page shows them, as UTC instants, with the page's timezone. Without --from and --to it reads from now to the end of the page's booking horizon, at most 62 days. Needs the calendar:read scope.
One-off booking links
shipmail booking-links create --name "Call with Sam" --mailbox hello@example.com --duration-minutes 30 --timezone Europe/Lisbon --range 2026-11-02T09:00:00Z/2026-11-02T12:00:00Z --max-bookings 1
shipmail booking-links list --status open
shipmail booking-links revoke bkp_123Repeat --range for each offered time, or pass --source-page to offer a booking page's weekly hours. --max-bookings unlimited keeps the link open after the first booking. You can't undo a revoke.
Newsletter example
shipmail newsletter-domains create --root-domain example.com --reply-to-address hello@example.com
# Publish the dns_records it prints, then:
shipmail newsletter-domains verify nwsdom_123
shipmail newsletter-sender-identities create --newsletter-domain-id nwsdom_123 --from-name "Acme" --business-name "Acme Ltd."
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_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
# The 500 most engaged subscribers first, then 1,000 more, then everyone left
shipmail newsletters schedule nws_789 --scheduled-at 2026-08-01T09:00:00.000Z --limit 500
shipmail newsletters send-more nws_789 --count 1000
shipmail newsletters send-more nws_789
# Test a second subject (needs tracking), and turn on list cleanup
shipmail newsletters update nws_789 --subject-b "Another subject" --track-engagement true
# Publish on the newsletter website only, with no email
shipmail newsletters update nws_789 --publish-target website
shipmail audiences update aud_123 --cleanup true --cleanup-inactive-days 120
# No View in browser link in this issue, or by default in new issues of the audience
shipmail newsletters update nws_789 --view-in-browser false
shipmail audiences update aud_123 --view-in-browser-default false
# Track opens and clicks by default in new issues; skip the last-chance email in list cleanup
shipmail audiences update aud_123 --track-engagement-default true --cleanup-send-last-chance false
# New dashboard issues of the audience go to the website only, with UTM tags and a feed title link
shipmail audiences update aud_123 --publish-target-default website --add-utm-tags-default true --feed-entry-url-default https://example.com/blog
# Your own subject and message for the confirmation email; null restores the built-in wording
shipmail audiences update aud_123 --confirmation-email-copy @confirmation-copy.json
shipmail audiences update aud_123 --last-chance-email-copy nullWrite draft bodies with --blocks @file.json when you can. You can also pass --body-html or --body-text. Create needs at least one body field, and update needs at least one field to change. A test send or schedule fails if the newsletter doesn't pass preflight.
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 only their safe attributes and URLs.
Webhook example
shipmail webhooks create \
--url https://example.com/shipmail/webhook \
--events message.received,message.bounced \
--description "Production webhook" \
--authorization "Bearer <your endpoint key>"
# Remove the Authorization header later
shipmail webhooks update whk_123 --clear-authorization
# Sign deliveries for a receiver that checks Standard Webhooks signatures
shipmail webhooks update whk_123 --standard-webhooks-secret "whsec_..."
shipmail webhooks update whk_123 --clear-standard-webhooks-secret
# Add reply_text to message.received and skip senders that fail DMARC
shipmail webhooks update whk_123 --include-reply-text true --authenticated-senders-only true
# Deliver message.received only from one address and one domain, then from everyone again
shipmail webhooks update whk_123 --allowed-sender jane@customer.com --allowed-sender customer.org
shipmail webhooks update whk_123 --clear-allowed-senders
shipmail webhooks deliveries whk_123 --status failed