zmail（zmail 命令行）

/zmail — agent-first email

What zmail is: Email reimagined for agents and automation—not a human-first inbox UI. It syncs mail over IMAP, stores messages as files (maildir-style) and indexes them in local SQLite with FTS5. The primary surface is the CLI: search, read, thread, who, attachments, and zmail ask for natural-language questions (OpenAI). Same index powers every command—queries stay local and fast so the assistant can treat mail like a repository of communication artifacts (invoices, travel, Zoom summaries, etc.) instead of paging through Gmail.

Why use it: Traditional webmail is slow and awkward for AI workflows. zmail’s promise is local-first, privacy-friendly mail you control, agent-intuitive commands, and room to grow toward “the agent is the interface”—plain-language prompts become searches and reads, not manual digging.

Transparency (registries & security review)

Use this block to keep ClawHub / OpenClaw registry fields aligned with the skill body—avoid “no credentials required” when the CLI clearly needs secrets.

OpenClaw parses metadata.openclaw.requires per Creating skills: bins = executables expected on PATH (zmail exists only after the global install step). config lists environment variables this workflow expects for a configured mailbox (mirror the same in ClawHub package metadata if the UI has separate fields).

Agent checklist

1. Confirm Node.js 20+ (node -v).
2. npm install -g @cirne/zmail (see Install).
3. Choose setup: zmail wizard (TTY) or zmail setup (flags/env, no prompts).
4. User must have a Gmail app password (or compatible IMAP credentials)—Gmail: app password.
5. Run zmail sync --since … then zmail refresh / zmail status.
6. Learn the CLI from the CLI: run zmail, zmail --help, and zmail <command> --help. Read any hint (and truncation fields) in JSON output—zmail uses them to disclose the next capability (Canonical docs & discovery).
7. For questions over mail, prefer zmail ask first; use search / read / thread / who / attachment when you need fine control (Ask vs primitives).
8. Never paste secrets into chat logs; use env or flags in the user’s shell.

Install

node -v   # must be v20+
npm install -g @cirne/zmail

• If better-sqlite3 fails to load (wrong Node ABI), the CLI may rebuild automatically on first run; if not, run npm rebuild better-sqlite3 using the same node binary that runs zmail.
• Global install note: npm may install to a directory that is not on PATH; ensure that global bin is on PATH, or use npx @cirne/zmail for one-off commands.

Config and data default to ZMAIL_HOME (default ~/.zmail): config.json, .env, and data/ (SQLite + maildir).

Gmail: get an app password

Gmail does not allow normal account passwords for IMAP clients. Use a 16‑character app password.

1. Turn on 2‑Step Verification (required):

Google Account → Security → 2‑Step Verification

1. Create an app password (sign in with Google account):

App passwords - Choose app: Mail (or Other and name it zmail). - Google shows a 16‑character password (often shown in groups; enter without spaces).

1. Use full Gmail address as IMAP user (e.g. you@gmail.com) and the app password as ZMAIL_IMAP_PASSWORD / --password.

If app passwords are disabled (workspace policy, account type), the user must use whatever IMAP credentials their admin allows.

zmail wizard (interactive humans)

• When: Real terminal with TTY; user is present to answer prompts.
• Run: zmail wizard

Optional: --no-validate (skip live IMAP/OpenAI checks), --clean (wipe local config + cached mail under ZMAIL_HOME; IMAP unchanged; may prompt unless --yes).

• If stdin is not a TTY (agents, CI, pipes): wizard exits with a message to use zmail setup instead.
• Wizard walks through email, IMAP app password, OpenAI key, default sync window, and can start background sync at the end.

zmail setup (agents & automation)

Non-interactive. No prompts when all inputs are provided via flags and/or environment variables.

Required today (all three):

Examples:

zmail setup \
  --email 'user@gmail.com' \
  --password 'abcdefghijklmnop' \
  --openai-key 'sk-...'

export ZMAIL_EMAIL='user@gmail.com'
export ZMAIL_IMAP_PASSWORD='abcdefghijklmnop'
export ZMAIL_OPENAI_API_KEY='sk-...'
zmail setup

Optional flags:

If any required value is missing, zmail setup prints what’s missing and exits—fix env/flags and retry.

OpenAI key: Required for zmail setup / zmail wizard as shipped. It is stored in ~/.zmail/.env. Same key powers zmail ask, zmail inbox, and related features. Search/read/thread/who/attachment do not need the API at query time once mail is indexed.

Secrets and files (after setup)

Security: Treat .env like credentials—don’t commit it, don’t paste into tickets or agent transcripts. Rotate app passwords if exposed.

First sync and daily use

zmail sync --since 30d    # initial backfill (often runs in background; note log path on stdout)
zmail refresh             # fetch new mail since last sync
zmail status              # local sync + index health
zmail ask "your question" # one-shot NL answer (OpenAI); good default for agents
zmail search 'query'      # FTS hits (JSON default; --text for tables)

• Long sync: Safe to run in background; use zmail status and the sync log file path the CLI prints.
• Refresh is the habitual “get new mail” command after the first sync.

zmail ask vs primitives

zmail ask "<question>" runs zmail’s answer pipeline in one go: it figures out how to search and pull the right messages, then synthesizes a complete answer for the user. For the calling agent, that usually means fewer steps and a ready-made summary—best when the goal is “answer this question about my mail” rather than “give me raw hits.” Requires ZMAIL_OPENAI_API_KEY (or OPENAI_API_KEY). Optional --verbose if you need to trace what it did.

Primitives (search, read, thread, who, attachment list / attachment read) expose structured, explicit steps: you choose the query, which message IDs to open, whether you need full body or raw, threads, contacts, or extracted attachment text. They do not call OpenAI for the core path—good for scripts, tight filters, verbatim quotes, debugging, or when the outer agent wants to own the reasoning and token budget.

Rule of thumb: Start with ask. If the answer is too shallow, wrong, or you need more detail or accuracy, switch to search → read / thread (and attachment when documents matter). Combine both: e.g. ask for orientation, then read on specific message_ids from search if you must verify.

Full tradeoffs and hybrid patterns: docs/ASK.md at the package/repo root (paths in references/CANONICAL-DOCS.md).

Install this skill folder (hosts)

Copy the zmail directory (this skill) into an end-user location—not into the zmail source repo’s .cursor/skills/ (those are dev-only).

Folder name must stay zmail to match frontmatter name (Agent Skills spec). Copy the whole skills/zmail/ directory (includes references/).

OpenClaw: heartbeat + fresh mail

For OpenClaw, use a heartbeat (not a separate cron per mailbox tick) for periodic “anything new in email?” awareness—OpenClaw’s own guide recommends heartbeat for inbox-style checks because it batches with other routine work and can suppress noise when nothing matters. See Cron vs heartbeat and Heartbeat (interval, HEARTBEAT.md, HEARTBEAT_OK, agents.defaults.heartbeat, etc.).

Put zmail on the workspace HEARTBEAT.md checklist, for example:

1. Ingest new mail: run zmail refresh (forward IMAP sync into the local index), or use zmail inbox <window> --refresh so the forward sync runs immediately before the scan (same sync path as refresh; optional --force if you need to skip STATUS fast-path—see zmail inbox --help).
2. Surface what’s worth attention: run zmail inbox over a window (e.g. 24h, 3d, or your inbox.defaultWindow in config.json) so the LLM returns notable recent mail in JSON (newMail, …). Requires ZMAIL_OPENAI_API_KEY (or OPENAI_API_KEY). Use --text if you want a human-readable digest. Add --include-noise only if marketing/social should count as “notable.”
3. If nothing needs a human ping, answer HEARTBEAT_OK so OpenClaw drops the turn quietly (per Heartbeat docs).

Cost / habit: refresh alone does not call OpenAI; inbox does. Keep the checklist short; widen the inbox window only when needed.

More detail

• references/CANONICAL-DOCS.md — CLI-first discovery (zmail, --help, per-command help), hints in output, and a table of canonical markdown (AGENTS.md, docs/VISION.md, docs/ASK.md, docs/ARCHITECTURE.md, docs/MCP.md, OPP-025).