@mailhooks/cli

Command-line interface for the Mailhooks email platform, designed for agentic systems and shell scripts.

Every command emits JSON to stdout and JSON errors to stderr, so the CLI composes cleanly with jq, pipelines, and LLM tool loops.

Install

npm install -g @mailhooks/cli
# or one-off:
npx @mailhooks/cli emails list

Quick start

# Option 1: store credentials once (plaintext, mode 0600 in ~/.config/mailhooks/)
mailhooks login --api-key mh_live_...

# Multiple environments? Use profiles:
mailhooks login --profile prod    --api-key mh_prod_...
mailhooks login --profile staging --api-key mh_staging_... --base-url https://staging-api.mailhooks.dev/api
mailhooks profiles list
mailhooks --profile staging emails list    # per-invocation override
mailhooks profiles use staging              # or switch the default

# Option 2: env var (no disk persistence)
export MAILHOOKS_API_KEY=mh_live_...

# Then use any command:
mailhooks emails list --per-page 5
mailhooks emails wait-for --subject "verification" --timeout 60000
mailhooks whoami   # active profile, creds (masked), source, domains
mailhooks logout   # remove the current profile (use --all to nuke everything)

Resolution order: --api-key flag → MAILHOOKS_API_KEY → current profile. Profile selection: --profile → MAILHOOKS_PROFILE → currentProfile in config.

Agent usage

The CLI is intended to be called from agentic systems (LLM tool loops, scripts, automations). See AGENTS.md for the full agent-facing guide, including the canonical wait-for → content → mark-read loop, exit code contract, and patterns like extracting one-time codes.

Commands

• mailhooks login [--profile name] — store API key (flag, stdin, or hidden TTY prompt)
• mailhooks logout [--profile name] [--all] — remove credentials
• mailhooks whoami — show active credentials (masked), source, profile, domains
• mailhooks profiles list — list configured profiles
• mailhooks profiles use <name> — switch the current profile
• mailhooks emails list — paginated list with filters
• mailhooks emails get <id> — fetch a single email (metadata)
• mailhooks emails content <id> — fetch HTML + text body
• mailhooks emails wait-for — block until a matching email arrives
• mailhooks emails mark-read <id> / mark-unread <id>
• mailhooks emails delete <id>
• mailhooks emails download-eml <id>
• mailhooks emails download-attachment <emailId> <attachmentId>
• mailhooks parse-eml [file] — parse an EML file (path or stdin) into JSON
• mailhooks listen — forward real-time email events to a local webhook (like stripe listen)

Run mailhooks --help or mailhooks <command> --help for full flag lists.

Configuration

| Env var | Flag | Purpose | |---|---|---| | MAILHOOKS_API_KEY | --api-key | API key. Required unless stored via mailhooks login. | | MAILHOOKS_API_URL | --base-url | Override API base. Default: https://mailhooks.dev/api. | | MAILHOOKS_PROFILE | --profile | Which stored profile to use. | | MAILHOOKS_CONFIG_PATH | — | Override the config file path. |

Global flags: --pretty / --no-pretty (format JSON — defaults to pretty on a TTY, compact when piped), --help, --version.

Stored config lives at ~/.config/mailhooks/config.json (mode 0600). See AGENTS.md for the full security note.

listen

Forward real-time email events to a local webhook endpoint — like the Stripe CLI's stripe listen or ngrok, but for Mailhooks.

# Forward all email events to localhost:3000/webhooks
mailhooks listen

# Custom endpoint
mailhooks listen -f http://localhost:8080/api/webhooks

# With webhook signature (so your server can verify X-Webhook-Signature)
mailhooks listen --secret whsec_dev_secret

# Distributed mode (load-balanced SSE — only one listener gets each event)
mailhooks listen --mode distributed

# Quiet mode (no stdout, just forwarding)
mailhooks listen --no-print

The CLI connects to Mailhooks via SSE. Each email.received or email.updated event is POSTed to your local URL as JSON with headers Content-Type, X-Mailhooks-Event, and optionally X-Webhook-Signature.

License

MIT