Sendmux CLI

Sendmux CLI

Use this skill when the terminal is the right Sendmux surface.

Boundaries

• Do not ask the user to paste API keys.
• Use smx_root_ keys only for management:* commands.
• Use smx_mbx_ keys or scoped smx_agent_ tokens for mailbox:* commands.
• Use a send-capable smx_mbx_ key or owner-approved Sending-resource smx_agent_ token for sending:* commands. Pre-claim smx_agent_ tokens cannot send.
• Do not run destructive commands without explicit confirmation.
• Use --json for agent-readable output.
• Prefer task-specific Sendmux skills when the user needs strategy; use this skill for exact CLI mechanics.

Install

npm install -g @sendmux/cli
sendmux --help

The package exposes the sendmux binary. Use the latest CLI before using smx_agent_ tokens; older installs may reject that prefix before sending a request.

Profiles

Create separate profiles for root and mailbox keys.

sendmux profiles:set default --api-key "$SENDMUX_ROOT_KEY" --default --json
sendmux profiles:set mailbox --api-key "$SENDMUX_MBX_KEY" --json
sendmux profiles:set sending --api-key "$SENDMUX_MBX_KEY" --json
sendmux profiles:list --json
sendmux profiles:show default --json

Profile reads mask stored keys. profiles:set reports key_kind as root or mailbox.

Authentication resolution:

1. --api-key, then SENDMUX_API_KEY.
2. If no direct key is present, --profile / -p, then SENDMUX_PROFILE, then the configured default profile.
3. Base URL comes from --base-url, then SENDMUX_BASE_URL, then the selected profile.

Preflight

The CLI infers key kind from the prefix before sending a request.

Wrong-key examples fail before network:

Command requires a root API key, but --api-key contains a mailbox API key.
Command requires a send-capable `smx_mbx_` key or owner-approved Sending-resource `smx_agent_` token, but --api-key contains a root API key.

Command catalogue

The CLI exposes generated operation commands:

Use command-level help to discover accepted path, query, header, and body fields:

sendmux management:create-domain --help
sendmux mailbox:search-message-snippets --help
sendmux sending:send:batch --help
sendmux sending:upload-attachment --help

Operation flags

Operation commands share these flags:

--path, --query, and --header require name=value. Booleans use true or false. Repeat an array-valued parameter rather than comma-joining it.

Pass either --body or --body-file, not both.

Use sendmux-attachments for attachment-heavy flows and size/token trade-offs.

Examples

Create a domain:

sendmux management:create-domain \
  --profile default \
  --idempotency-key "$IDEMPOTENCY_KEY" \
  --body '{"domain":"example.com","mode":"send_receive"}' \
  --json

Get domain DNS records:

sendmux management:get-domain-zone-file \
  --profile default \
  --path public_id=mdom_abc \
  --json

Search a mailbox without reading full messages:

sendmux mailbox:search-message-snippets \
  --profile mailbox \
  --query q=invoice \
  --query is_unread=true \
  --query limit=10 \
  --json

Batch-read selected mailbox messages:

sendmux mailbox:batch-get-messages \
  --profile mailbox \
  --body '{
    "ids": ["eml_abc", "eml_def"],
    "body_mode": "clean_json",
    "max_body_chars": 4000
  }' \
  --json

Send a batch:

sendmux sending:send:batch \
  --profile sending \
  --idempotency-key "$IDEMPOTENCY_KEY" \
  --body-file ./messages.json \
  --json

Send through the Sending API with a local attachment:

sendmux sending:send \
  --profile sending \
  --idempotency-key "$IDEMPOTENCY_KEY" \
  --attach ./report.pdf \
  --body '{"from":{"email":"sender@example.com"},"to":{"email":"user@example.com"},"subject":"Report","html_body":"<p>Attached.</p>"}' \
  --json

sending:send --attach uploads the file first and injects an attachment_id reference; it does not place base64 in the send body.

Upload a Sending attachment separately:

sendmux sending:upload-attachment \
  --profile sending \
  --body-file ./report.pdf \
  --query filename=report.pdf \
  --query content_type=application/pdf \
  --json

Send a mailbox message with a local attachment:

sendmux mailbox:send-message \
  --profile mailbox \
  --idempotency-key "$IDEMPOTENCY_KEY" \
  --attach ./report.pdf \
  --body '{"to":[{"email":"user@example.com","name":null}],"subject":"Report","text_body":"Attached."}' \
  --json

Mailbox attachment upload commands share the 7,500,000 byte per-attachment cap. For larger files, split the file or host it externally and send a link.

Upload a mailbox attachment by presigned URL:

sendmux mailbox:upload-attachment \
  --profile mailbox \
  --file ./report.pdf \
  --via-presigned \
  --json

Poll one unchanged-safe delivery log:

sendmux management:get-email-log \
  --profile default \
  --path public_id=dlog_abc \
  --if-none-match "$ETAG" \
  --json

Routing

• First setup/auth check: sendmux-getting-started.
• Sending strategy and body shape: sendmux-send-email.
• Attachment file paths and presigned upload/download: sendmux-attachments.
• Mailbox read, search, sync, triage, or reply: sendmux-mailbox-agent.
• Account-level management strategy: sendmux-management.
• MCP connection setup: sendmux-mcp-setup.
• Cheapest-call doctrine: sendmux-token-efficient-usage.