CLI Reference

The mails CLI gives you full access to mails-agent from the terminal. Send emails, check your inbox, wait for verification codes, and manage your configuration.

Installation

npm install -g mails-agent

After installation, the mails command is available globally.

mails --version
# mails-agent v1.x.x

Commands

mails send

Send an email from your mailbox.

mails send --to [email protected] --subject "Hello" --body "Message body"

# With HTML body
mails send --to [email protected] --subject "Report" --html "<h1>Report</h1><p>Details...</p>"

# With attachment
mails send --to [email protected] --subject "Report" --body "See attached" --attach report.pdf

# Multiple recipients
mails send --to [email protected] --to [email protected] --subject "Team update" --body "..."

Flag	Required	Description
--to	Yes	Recipient email address
--subject	Yes	Email subject line
--body	No*	Plain text body
--html	No*	HTML body
--attach	No	File path to attach (repeatable)
--from	No	Sender address (defaults to configured mailbox)

* At least one of --body or --html is required.

Note: --cc, --bcc, and --in-reply-to are available via the API only, not the CLI.

mails inbox

List emails in your mailbox.

# Show recent emails
mails inbox

# Filter by query
mails inbox --query "verification code"

# Limit results
mails inbox --limit 5

Flag	Default	Description
--query	-	Search query to filter emails
--limit	20	Maximum number of emails to return
--mailbox	-	Override mailbox (full-access keys only)
--direction	-	Filter by inbound or outbound
--threads	-	List email threads instead of individual emails
--label	-	Filter by label: newsletter, notification, code, personal
--semantic	-	Use semantic search mode (requires Vectorize)
--mode	keyword	Search mode: keyword, semantic, or hybrid
--plain	-	Output plain text (no colors, tab-separated)

mails code

Wait for a verification code to arrive. Blocks until a code is found or the timeout is reached.

# Wait for a code (default 30s timeout)
mails code

# Custom timeout
mails code --timeout 55

# Wait for code sent to specific address
mails code --to [email protected] --timeout 30

# Use in a script
CODE=$(mails code --timeout 30)
echo "Verification code: $CODE"

Flag	Default	Description
--to	configured mailbox	Mailbox to watch for incoming codes
--timeout	30	Maximum seconds to wait
--since	now	Only consider emails after this ISO 8601 timestamp

mails claim

Claim a new mailbox address. Takes a positional argument for the name. Returns a mailbox-scoped API key.

# Claim a specific address
mails claim myagent

# This creates [email protected]

Argument	Required	Description
<name>	Yes	Desired mailbox username (before the @). Creates [email protected].

mails config

View or set CLI configuration. Uses mails config set <key> <value> syntax.

# Show current config
mails config

# Set API key
mails config set api_key mk_abc123...

# Set API URL (for self-hosted)
mails config set worker_url https://your-worker.your-domain.workers.dev

# Set default mailbox
mails config set mailbox [email protected]

# Set default from address
mails config set default_from [email protected]

Config key	Description
api_key	Set the API key
worker_url	Set the API base URL
mailbox	Set the default mailbox address
default_from	Set the default sender address

mails doctor

Diagnose common configuration issues. Checks API connectivity, key validity, mailbox existence, and DNS records.

mails doctor

# Example output:
#   mails doctor
#   ────────────
#   ✓ Config:   ~/.mails/config.json
#     mailbox:  [email protected]
#     api_key:  mk_8a3c12...
#   ✓ API:      https://mails-worker.genedai.workers.dev (connected)
#   ✓ Mailbox:  [email protected] (exists)
#   ✓ Send:     enabled (Resend configured)
#
#   All checks passed ✓

mails demo

Send a test email to your configured mailbox and verify it arrives. Useful for confirming that send and receive are working end-to-end.

mails demo

mails stats

Show mailbox statistics: total emails, sent count, received count, and monthly totals.

mails stats

mails thread

Manage email threads.

# List threads
mails thread list

# Get a specific thread with all messages
mails thread thr_abc123

mails webhook

Manage webhooks for the current mailbox.

# List current webhook configuration
mails webhook list

# Set a webhook URL for the current mailbox
mails webhook set https://your-server.com/webhook

mails help

Show help with all available commands and usage examples.

mails help

mails version

Print the installed version.

mails version
# mails-agent v1.x.x

Environment Variables

Variable	Description
MAILS_API_URL	Override API base URL (default: https://mails-worker.genedai.workers.dev)
MAILS_CLAIM_URL	Override claim page URL (default: https://mails0.com)

Priority order: environment variable > config file.

Configuration File

The CLI stores its configuration in ~/.mails/config.json:

{
  "api_key": "mk_8a3c12ef90b74d2e56f1a8c3d0e9b7f4a2c5d8e1f0b3a6c98a3c12ef90b74d2e",
  "worker_url": "https://mails-worker.genedai.workers.dev",
  "mailbox": "[email protected]",
  "default_from": "[email protected]"
}