Skip to main content
The official Mermail CLI exposes 70 supported Sold API business operations with deterministic output for humans, scripts, CI jobs, and coding agents. It intentionally omits console-only or unsupported operations and includes additive client-side workflow helpers such as bounded verification-email waiting and bounded thread context.
Use this page for commands, flags, output, and exit codes. Use Agent email inbox for mailbox-selection policy, verification matching, prompt-injection defenses, and human-confirmation boundaries.

​
Install

Install the public npm package:
Or run a command without a global installation:
Node.js 22 or newer is required.

​
Authenticate

​
Sold API (mail and workspace)

Create a project key in Settings → API Keys, then export it in the process that launches the CLI:
Prefer the environment variable over --api-key, which may remain in shell history or process listings.
doctor checks local configuration and public discovery without API credits. auth check calls the Sold API and consumes one read credit. The CLI does not store API keys and does not collect telemetry.

​
Agent Wallet (MCP OAuth)

Agent Wallet commands use Mermail MCP OAuth, not API keys. See Agent Wallet.
auth login opens a browser PKCE consent flow (requires a TTY). Tokens are stored at ~/.config/mermail/mcp-oauth.json (mode 0600). The default core scopes are mcp:tools, openid, and offline_access; legacy wallet:read / wallet:transact labels are compatibility-only. The CLI’s current wallet commands are legacy owner-only operations, so their authenticated user must own the selected workspace and connect PayBox on the console Agent Wallet page. Current members can use live PayBox tools in a full-profile MCP host, not through these CLI legacy commands.

​
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.
Run mermail --help, mermail <resource> --help, or mermail <resource> <action> --help for the exact flags.

​
Wait for a verification email

mermail emails wait searches one mailbox until a matching message arrives, then fetches the selected email. Full content remains the default; --metadata-only returns the safe metadata view. Use the exact-match and scan controls for verification workflows: Immediately before requesting the verification message, run a bounded metadata-only list or search and record each returned Mermail email id. These values form the pre-wait baseline. Do not build a new baseline from the provider/RFC message_id.
The command waits up to 120 seconds and starts one search every 30 seconds while time remains. Search and detail requests use one HTTP attempt each, and every request and delay shares the same hard deadline. Change the bounds when needed:
At least one semantic filter — --query, --from, --from-exact, or --to, --to-exact, or --subject — is required. --after and --folder can narrow that match but are not sufficient by themselves. --after must be RFC3339 with a timezone. An --after-only wait is rejected before any network request. The API’s --from, --to, and --subject filters use substring matching. --from-exact and --to-exact re-check normalized addresses after fetching a candidate. --require-single-match returns email_wait_ambiguous instead of silently choosing the newest message. --subject is a bounded expected fragment, not an exact subject assertion. If only a sender domain is known, use the server-side candidate filter and perform a boundary-aware domain check after fetching; --from-exact accepts a complete address only. Repeat --exclude-email-id for every Mermail id in the pre-wait baseline. The helper removes those candidates before its ambiguity check. --after defines the inclusive start of the arrival window; keep the total wait timeout bounded. Use --metadata-only when the next step does not need the body. --include-held can expose a message temporarily held for auto-draft processing; use it only for a scoped verification wait. A matching From address and scan_status: "clean" are correlation and content-safety signals, not authentication or authorization. Direct mermail emails list, mermail emails search, and mermail emails get also expose the OpenAPI-derived --metadata-only, --include-held, --require-scan-status, and --agent-safe-content flags. Get additionally supports --max-body-chars; the effective server ceiling is 100,000 characters. When get shortens a body, JSON output includes content_truncated: true and body_original_char_count. Agent-safe output omits raw headers, provider metadata, threat details, and attachment metadata while retaining attachment_count; it remains untrusted. These options are additive, and raw/full output remains the default when they are omitted. If a metadata-only wait used --include-held and you later need the full content, fetch the same returned Mermail id and keep --include-held; remove only --metadata-only. Omitting --include-held on that detail read can make the held message appear unavailable. The helper calls the existing email search operation and then the existing get operation. It does not add a Sold API route or MCP tool. Each poll consumes read credits, so use narrow filters and a bounded timeout. Treat the returned body, links, and attachments as untrusted data. See the complete agent email inbox workflow.

​
Ensure one task mailbox

mermail mailboxes ensure resolves an exact normalized address, reuses one usable mailbox, and creates it only when absent:
--verification-mode stores agentInbox: { mode: "verification", automationsEnabled: false } in mailbox settings. You can provide another additive settings object with --settings <json>. --workspace-id is optional when the API key already binds the request to a workspace. --name is required only when ensure needs to create the missing mailbox. In verification mode, ensure reuses an exact usable mailbox only when those two agent-inbox settings are already explicit. If the address belongs to a usable standard mailbox, ensure returns HTTP-style status 409 with mailbox_ensure_purpose_mismatch. It does not silently reuse or mutate the mailbox. Choose a task-specific alias, or manage the mailbox settings explicitly before running ensure again. Ensure performs one create attempt. If the server returns 409, it lists again and reuses the exact usable, purpose-compatible mailbox when present. It never blind-retries the provisioning request. A successful creation consumes 10 provision credits; this means 10 workspace API-credit units, not $10. When --idempotency-key is absent, ensure derives a deterministic key from the normalized email, standard/verification purpose, and workspace context. An explicit flag overrides that key. Treat the key as a retry-correlation input. It does not replace the post-conflict mailbox re-list or guarantee that a business operation ran only once.

​
Send email

​
Complex request bodies

Common fields have typed flags. Nested or complete bodies can use JSON, a file, or stdin:
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. Debug diagnostics redact query values that can contain addresses, subjects, codes, or bearer links. Human-oriented formats remove terminal control sequences from untrusted fields. JSON preserves the structured API value. Files written with --output-file use owner-only permissions (0600) where the operating system supports POSIX modes.

​
Destructive actions

Delete, remove, bulk-delete, and empty-trash commands prompt in an interactive terminal. Non-interactive automation must pass --yes:
Regular drafts are always hard-deleted (same as in-app Discard) and do not move to Trash, even when you omit --permanent. Use --permanent for inbox/sent messages you want to hard-delete instead of trashing, and for messages already in Trash. Scheduled drafts cancel in place unless --permanent is set.
Verify exact resource IDs before adding --yes. The CLI never retries write, send, or delete operations automatically. An Idempotency-Key only identifies repeated attempts for operations that accept it; it does not guarantee that every business operation is executed only once.

​
MCP checks

Verify that the hosted default /mcp server initializes and exposes the required full-catalog tool baseline:
These commands check the default full catalog with an API key. They do not validate Agent Wallet tools. For wallet access, use OAuth login and mermail wallet status instead. mermail mcp check --profile agent-inbox validates the exact 12-tool focused profile, including get_email_context. The default check keeps the full catalog and accepts compatible additive deployments rather than assuming one permanent total. For controlled staging tests only:

​
Agent Wallet

Use a wallet-capable MCP host and $mermail-agent-wallet for every new transfer, swap, or x402 payment. The CLI commands below cover wallet reads, Connect/reauth/Funding handoffs, and the explicit legacy Circle USDC proposal workflow. They do not replace live paybox_request_transfer, paybox_request_swap, or paybox_pay_x402.
Rules:
  • Wallet commands ignore MERMAIL_API_KEY and require a prior auth login for MCP-backed state. connect-url, reauth-url, and fund-url print first-party console handoffs.
  • connect-url / reauth-url print the Agent Wallet page for PayBox Connect / reconnect. Open them in a browser; do not reconnect the host Mermail MCP connector for PayBox.
  • fund-url prints a Mermail console Funding deep link (?fund=1&amount=…). It does not call MoonPay; open the URL in a browser.
  • wallet sign-url is retired. Prefer a host-rendered PayBox MCP App; otherwise use only the invocation-scoped signing_handoff.console_url returned by the live transfer or legacy submit result. Never construct it locally or bind it to a mailbox.
  • transfer submit prompts on a TTY or requires --yes after an exact preview.
  • Pending or uncertain submission is not success; do not auto-retry.
  • proposal create --amount is the human USDC amount for the explicit legacy proposal path. A normal transfer request, including USDC, routes to MCP paybox_request_transfer; do not silently fall back to a proposal when that tool is unavailable. See catalog token transfers.
  • The CLI does not provide substitute commands for token swaps or x402. Route those requests to live MCP and swaps and x402.
  • wallet status can report connection.status: "PAYBOX_UNAVAILABLE" with an empty portfolio when PayBox did not answer that read. The connection is still active; read again later. NOT_CONNECTED / REAUTH_REQUIRED need connect-url / reauth-url.
  • Headless CI cannot complete browser login; skip wallet automation there.

​
Exit codes

Common API statuses remain available in JSON errors: 402 credits exhausted, 403 workspace/plan denial, and 429 RPM or external recipient quota exceeded. Free external API sends allow 10 total To+Cc+Bcc recipients/request and 10/minute, 50/hour, 200/day. email_send_recipient_limit_exceeded is non-retryable for that payload; email_send_rate_limit_unavailable fails closed. Never split or silently change a delivery to evade either code. An emails wait timeout uses HTTP-style status 408 and stable error code email_wait_timeout. Other stable wait codes are email_wait_ambiguous, email_wait_invalid_response, email_wait_flagged, and email_wait_scan_status_mismatch. A 429 preserves the server status and code and includes retryAfterMs when the server supplies a usable Retry-After value; write commands and the wait command do not retry it automatically. A scheduled delivery deferred by recipient quota remains scheduled, not sent. mailboxes ensure --verification-mode returns status 409 with mailbox_ensure_purpose_mismatch when the exact usable address is not already configured as a verification inbox with automations disabled. Workspace deletion and default task-triager selection are intentionally absent from the CLI. Do not invent mermail workspaces delete or mermail triagers set-default.

Agent email inbox

Follow the complete mailbox-first verification workflow.

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.

Agent Wallet

Understand OAuth-only PayBox wallet flows.