Skip to content

index.mdx

Latest commit

 

History

History
174 lines (128 loc) · 4.61 KB

index.mdx

File metadata and controls

174 lines (128 loc) · 4.61 KB
Raw
title CLI
description Install and configure the Sendmux CLI for management, mailbox, and sending workflows.
keywords
Sendmux CLI
@sendmux/cli
sendmux
profiles
Management API
Mailbox API
Sending API

Use the sendmux CLI when you want terminal access to the same Management, Mailbox, and Sending API surfaces exposed by the SDKs.

Sending and Mailbox commands accept mailbox-compatible `smx_mbx_` keys or scoped `smx_agent_` tokens. Management commands require team-scoped `smx_root_` keys.

Install

Install the CLI from npm.

npm install -g @sendmux/cli

Check the installed command.

sendmux --version
sendmux --help

Configure profiles

Save API keys as local CLI profiles so you do not pass a key on every command.

sendmux profiles:set mailbox \
  --api-key "$SENDMUX_MAILBOX_KEY" \
  --default
sendmux profiles:set management \
  --api-key "$SENDMUX_ROOT_KEY"

The CLI stores profile configuration locally with restricted file permissions. profiles:list --verbose and profiles:show mask saved keys.

sendmux profiles:list
sendmux profiles:list --verbose
sendmux profiles:show management

Authentication order

Every API command resolves credentials in this order:

  1. --api-key
  2. SENDMUX_API_KEY
  3. --profile
  4. SENDMUX_PROFILE
  5. the configured default profile

--base-url overrides the API base URL for one command. SENDMUX_BASE_URL overrides it for the current shell. A profile can also store a base URL override.

Before running the API call, the CLI checks that the key prefix matches the command surface. A management command fails early when it receives a mailbox-compatible key, and mailbox or sending commands fail early when they receive a root key. API permissions still apply, so a pre-claim smx_agent_ token cannot send email.

Run commands

Commands use colon-separated names.

sendmux sending:send \
  --profile mailbox \
  --body '{"from":{"email":"sender@example.com"},"to":{"email":"recipient@example.com"},"subject":"Hello","text_body":"Sent with the Sendmux CLI"}' \
  --idempotency-key send-cli-001
sendmux mailbox:messages:list \
  --profile mailbox \
  --query limit=25
sendmux management:mailboxes:list \
  --profile management \
  --query limit=25

Pass request bodies inline with --body or from a file with --body-file.

sendmux management:create-mailbox \
  --profile management \
  --body-file ./mailbox.json \
  --idempotency-key create-mailbox-001

Pass parameters with repeatable name=value flags:

  • --path name=value for path parameters.
  • --query name=value for query parameters.
  • --header name=value for supported headers.

Typed values are validated before the request is sent. Unknown parameter names fail with the supported names for that command.

Output

Without --json, API commands print formatted JSON for easy reading. Use --json when another process needs machine-readable output from the CLI.

sendmux management:mailboxes:list --profile management --json

Text responses return { "text": "..." } with --json. Binary responses return base64 data and byte_length.

Request safety flags

Use the dedicated safety flags when the generated command supports the corresponding header:

Flag Header
--idempotency-key Idempotency-Key
--if-match If-Match
--if-none-match If-None-Match

The CLI rejects these flags on commands whose API operation does not accept the matching header.

Command reference

The CLI command set is generated from the public API surfaces. Run sendmux --help to see the current topics, sendmux <topic> --help to browse a surface, and sendmux <command> --help for the flags supported by one command.

For example:

sendmux sending --help
sendmux mailbox --help
sendmux management --help
sendmux sending:send --help

Next steps

Choose package-managed clients for application code. Create scoped credentials before configuring CLI profiles. Review the API used by mailbox commands. Review the API used by management commands.