Botmail CLI (botmail-cli)

The official, zero-dependency, AI-agent-native CLI for Botmail. Manage projects, provision persistent and ephemeral inboxes, send and read emails, and generate MCP configurations from any terminal or autonomous coding agent.

Public Repository: https://github.com/lysdexic1/botmail-cli

Installation

Install globally or invoke directly from GitHub via npx:

# Install globally
npm install -g github:lysdexic1/botmail-cli
botmail --version

# Or run directly without installing
npx github:lysdexic1/botmail-cli --help

AI-Agent-Native Design

botmail-cli is built to be operated natively by autonomous AI agents (Claude Code, Cline, Cursor, Codex, and custom shell agents) as well as human developers:

• Self-Discoverable Manifest (botmail schema): Outputs a complete machine-readable JSON manifest of all commands, flags, endpoints, and exit codes in one call.
• Structured JSON Mode (--json / BOTMAIL_OUTPUT=json): Every command supports --json (or -j) and emits deterministic JSON on stdout, including structured JSON errors.
• Idempotent Writes (--operation-id): Every write command (inboxes create, messages send, messages reply, messages archive, messages delete) accepts an idempotency key so agents can safely retry without duplicate deliveries.
• Untrusted Content Boundaries: Message read/list/search outputs carry data_untrusted: true in JSON mode and explicit boundary headers in human mode.

Authentication

Authenticate interactively in your browser via OAuth 2.1 PKCE S256, or supply a scoped agent credential token directly for headless/CI environments:

# Interactive browser OAuth 2.1 PKCE login
botmail auth login

# Headless / AI agent token login
botmail auth login --token bm_...

# Or use environment variables without writing to disk
export BOTMAIL_API_TOKEN="bm_..."
export BOTMAIL_OUTPUT="json"

# Verify active identity
botmail auth status

Command Reference

Projects & Inboxes

botmail projects list [--json]
botmail projects create --name "Support Agent"
botmail inboxes check support-agent [--json]
botmail inboxes create --project <projectId> --prefix support-agent --type persistent
botmail inboxes list [--project <projectId>] [--json]
botmail inboxes close <inboxId>

Messages & Free Internal Escalation Bus (0 Credits)

botmail messages list --inbox <inboxId> [--direction inbound|outbound] [--folder inbox|archive] [--json]
botmail messages search --query "verification" [--inbox <inboxId>] [--json]
botmail messages get <messageId> [--json]
botmail messages send --inbox <inboxId> --to recipient@example.com --subject "Status" --text "Hello!" [--operation-id <key>] [--json]
botmail messages escalate <messageId> --to tier2-eng@botmail.work --severity high --note "Reproducible 502 in checkout" [--operation-id <key>] [--json]
botmail messages reply <messageId> --text "Received and processed." [--operation-id <key>] [--json]
botmail messages archive <messageId>
botmail messages delete <messageId>
botmail escalation status [--json]
botmail escalation provision --prefix tier2-eng --display-name "Tier-2 Engineering"

Quotas, Agents, Credentials & MCP Config

botmail usage [--json]
botmail agents list
botmail agents create --name "CI Runner"
botmail credentials create --agent <agentId> --name "CI Token" --scopes read,send,manage
botmail credentials revoke <credentialId>
botmail mcp config [--json]
botmail schema