Repository navigation
MailCLI v0.1.0
中文 | English
MailCLI v0.1.0 Release Notes
Summary
v0.1.0 is the first stable release of MailCLI — an AI-native email interface that turns raw MIME into clean, structured context for agents and LLM workflows.
It ships with a complete read-write-watch loop, a high-performance SQLite + FTS5 local index, persistent watch state, and stable JSON contracts for every command.
What's In This Release
New Commands (since RC)
| Command | Description |
|---|---|
mailcli watch |
Stream JSONL events from one or more mailboxes (IMAP IDLE + polling fallback) |
mailcli delete |
Delete a message from a remote mailbox |
mailcli move |
Move a message to another mailbox |
mailcli mark |
Mark a message as read or unread |
mailcli export |
Export the local index as JSONL, JSON, or CSV |
mailcli config show|test |
Show accounts (passwords redacted) or test a live connection |
SQLite + FTS5 Local Index
The local index has been fully migrated from a JSON flat file to a SQLite database with FTS5 full-text search.
- FTS5 recall — unicode61 tokenizer, prefix search, diacritics-insensitive
- Field-weighted re-ranking — subject > snippet > body > sender (Go-layer
scoreMatch) - BulkUpsert — all messages in a single transaction; 3.2× faster than per-message commits
- BulkHas — single SQL query to check N IDs at once (replaces N round-trips)
- WAL mode — concurrent reads during writes
- Backward compatible —
.jsonpaths are silently remapped to.db
Persistent Watch State
mailcli watch --index <path> now maintains a watch_seen table in SQLite.
- Seen IDs are restored from the database on startup
- No messages are re-emitted after a process restart
- On first run, existing mailbox contents are seeded silently (no old-mail flood)
--auto-syncwrites each new message to the local index in the same transaction
AI Tool Schemas
Ready-to-use JSON schemas for LLM function calling:
tools/openai.json— OpenAI Function Calling format (12 tools)tools/anthropic.json— Anthropic Tool Use format (12 tools)tools/agent_example.py— Referencewatch → LLM → replypipelinetools/README.md— Integration guide withtool_to_cmddispatch pattern
Parser Improvements
- Chinese email fixture coverage: verify-signin, reset-password, invoice, unsubscribe, confirm-subscription, attachment, view-online, abuse
- Full-width digit verification code extraction
- Safe-link URL unwrapping (Proofpoint, Barracuda)
- Conservative confirm-email heuristic tightening
- Broader confirm-subscription keyword coverage
Examples & Fixtures
examples/python/agent_thread_assistant.py— Thread-mode AI agent with external provider supportexamples/python/agent_inbox_assistant.py— Inbox-mode AI agentexamples/providers/— Template and OpenAI external provider implementations- Complete local thread demo artifacts under
examples/artifacts/local-thread-demo/
Stable Contracts
These interfaces are considered stable for v0.1.x:
Commands: parse, list, get, sync, search, threads, thread, send, reply, delete, move, mark, export, watch, config show|test
JSON types: StandardMessage, DraftMessage, ReplyDraft, SendResult, OperationResult, SearchResult, ThreadSummary
Tool schemas: tools/openai.json, tools/anthropic.json (all 12 tools)
Still Evolving
- HTML body extraction for unusual email templates
- Verification code extraction beyond common OTP layouts
- Richer outbound HTML rendering and attachment ergonomics
Upgrading from RC
No migration required. If you have an existing *.json index, it is automatically remapped to *.db on first use. A new SQLite database is created with the same data layout.
# Existing usage continues to work unchanged:
mailcli sync --index /tmp/mailcli.json # → transparently uses /tmp/mailcli.dbGetting Started
go build -o mailcli ./cmd/mailcli
# Zero-network quick start
./mailcli sync --config examples/config/fixtures-dir.yaml \
--account fixtures --index /tmp/demo.db --limit 0
./mailcli threads --index /tmp/demo.db
# Watch + AI agent
mailcli watch --account work --index ~/.config/mailcli/index.db --auto-sync \
| python3 tools/agent_example.pyFull documentation: docs/en/