CLI - Mermail

The official Mermail CLI exposes all 62 Sold API business operations with deterministic output for humans, scripts, CI jobs, and coding agents.

Install

Until the package is on the public npm registry, install from GitHub:

npm install -g github:Nudgen-Marketing/mermail-cli
# after npm publish: npm install -g mermail-cli

Or run a command without a global installation:

npx --yes github:Nudgen-Marketing/mermail-cli --help

Node.js 22 or newer is required.

Authenticate

Create a project key in Settings → API Keys, then export it in the process that launches the CLI:

export MERMAIL_API_KEY="sk-proj-your-key"

The CLI does not store credentials and does not collect telemetry. Prefer the environment variable over --api-key, which may remain in shell history or process listings.

mermail doctor
mermail auth check

doctor checks local configuration and public discovery without API credits. auth check calls the Sold API and consumes one read credit.

Command structure

Commands follow mermail <resource> <action> [flags]: --mailbox-id accepts the mailbox public_id (UUID), hosted alias id, or current email. Prefer public_id from mermail mailboxes list.

mermail workspaces list
mermail mailboxes list --format table
mermail emails list --mailbox-id MAILBOX_PUBLIC_ID
mermail usage credits --workspace-id WORKSPACE_ID

Run mermail --help, mermail <resource> --help, or mermail <resource> <action> --help for the exact flags.

Send email

mermail emails send \
  --mailbox-id MAILBOX_PUBLIC_ID \
  --to [email protected] \
  --from [email protected] \
  --subject "Hello" \
  --text "Hello from Mermail"

Complex request bodies

Common fields have typed flags. Nested or complete bodies can use JSON, a file, or stdin:

mermail triagers create --mailbox-id MAILBOX_ID --data-file triager.json
printf '%s' '{"name":"Support"}' | \
  mermail folders create --mailbox-id MAILBOX_ID --data-file -

Typed flags override the same fields supplied in JSON. --data and --data-file cannot be used together.

Output formats

JSON is the stable default. Data is written to stdout; diagnostics and errors are written to stderr.

Format	Use
`json`	Scripts and agents; default
`yaml`	Human-readable structured output
`pretty` / `table`	Interactive inspection
`raw`	Text or explicitly requested binary output

mermail mailboxes list --format json | jq '.[].email'
mermail attachments download \
  --mailbox-id MAILBOX_ID \
  --email-id EMAIL_ID \
  --attachment-id ATTACHMENT_ID \
  --output-file attachment.pdf

Destructive actions

Delete, remove, bulk-delete, and empty-trash commands prompt in an interactive terminal. Non-interactive automation must pass --yes:

mermail emails delete \
  --mailbox-id MAILBOX_ID \
  --email-id EMAIL_ID \
  --permanent \
  --yes

Verify exact resource IDs before adding --yes. The CLI never retries write, send, or delete operations automatically. Idempotency-Key protects credit accounting but does not guarantee that every business operation is executed only once.

MCP checks

Verify that the hosted MCP server initializes and exposes exactly 63 tools:

mermail mcp check
mermail mcp tools --format table

For controlled staging tests only:

MERMAIL_BASE_URL=https://console-staging.mermail.app mermail mcp check

Exit codes

Code	Meaning
`0`	Success
`1`	API, network, or runtime failure
`2`	Invalid command, flag, or payload
`3`	Missing, invalid, expired, or revoked API key
`4`	Destructive confirmation required
`130`	Cancelled or interrupted

Common API statuses remain available in JSON errors: 402 credits exhausted, 403 workspace/plan denial, and 429 RPM exceeded.

Skills

Give coding agents the dedicated mermail-cli workflow.

MCP

Use direct Streamable HTTP tool calling.

Authentication

Create and protect project API keys.

API Reference

Review request and response schemas.

​Install

​Authenticate

​Command structure

​Send email

​Complex request bodies

​Output formats

​Destructive actions

​MCP checks

​Exit codes

​Related

Skills

MCP

Authentication

API Reference

Install

Authenticate

Command structure

Send email

Complex request bodies

Output formats

Destructive actions

MCP checks

Exit codes

Related