Repository navigation
Releases
v0.2.0
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/
MailCLI v0.1.0-rc1
MailCLI v0.1.0-rc1
First release candidate for MailCLI as an open, AI-native email interface.
Highlights
- Parse raw email into
StandardMessageJSON and Markdown - Read inboxes through the baseline IMAP driver with
listandget - Send new outbound drafts and replies through SMTP-backed IMAP-style accounts
- Support
reply_to_message_idandreply_to_idreply flows - Compile outbound MIME with
multipart/alternativeand attachment packaging - Expose stable machine-facing contracts for agents:
StandardMessageDraftMessageReplyDraftSendResult
- Ship Python and shell examples, including an external provider contract and an optional OpenAI provider example
Included In This RC
mailcli parsemailcli listmailcli getmailcli sendmailcli reply- IMAP raw fetch by sequence number, UID, and
Message-ID - Stable outbound result codes such as
auth_failed,message_not_found, andtransport_not_configured - Config secret injection via environment variables for password fields
- Driver extension guidance and contributor docs
- Expanded parser fixture corpus covering:
- plaintext mail
- promo/newsletter mail
- bounce mail
- verification mail
- invoice/payment mail
- security reset mail
- attachment-entry mail
Still Evolving
- HTML cleanup and URL normalization heuristics
- action extraction coverage
- verification-code extraction outside common layouts
- richer search and local indexing
- additional providers beyond the baseline IMAP/SMTP path
Recommended Stable Boundary For Integrators
For this RC, the intended stable boundary is:
mailcli parsemailcli listmailcli getmailcli sendmailcli replyStandardMessageDraftMessageReplyDraftSendResult
Verification
go test ./...go build ./cmd/mailclipython3 -m py_compile examples/python/*.py examples/providers/*.py
Docs
- Release notes:
docs/en/release/v0.1-rc.md - Agent workflows:
docs/en/agent-workflows.md - Outbound spec:
docs/en/spec/outbound-message.md - Driver extension spec:
docs/en/spec/driver-extension.md
MailCLI v0.1.0-rc1
这是 MailCLI 作为开放式 AI Native 邮件接口的第一个 release candidate。
亮点
- 将原始邮件解析成
StandardMessageJSON 和 Markdown - 通过基础 IMAP driver 提供
list/get收件箱读取能力 - 通过面向 IMAP 风格账户的 SMTP 路径发送新邮件和回复
- 支持
reply_to_message_id和reply_to_id回复流程 - 出站 MIME 已支持
multipart/alternative和附件打包 - 为 agent 暴露稳定的机器接口:
StandardMessageDraftMessageReplyDraftSendResult
- 提供 Python / shell 示例,以及 external provider 契约和可选 OpenAI provider 示例
这个 RC 已包含
mailcli parsemailcli listmailcli getmailcli sendmailcli reply- 基于序号、UID 和
Message-ID的 IMAP 原始邮件抓取 - 稳定的出站结果码,例如
auth_failed、message_not_found、transport_not_configured - 面向密码字段的环境变量秘密注入
- driver 扩展说明与贡献文档
- 已扩充的 parser 样本集,覆盖:
- 纯文本邮件
- 推广 / newsletter 邮件
- 退信邮件
- 验证码邮件
- 账单 / 支付邮件
- 安全重置邮件
- 附件入口邮件
仍在演进中的部分
- HTML 清洗与 URL 归一化 heuristic
- action 提取覆盖率
- 常见布局之外的验证码提取
- 更丰富的搜索与本地索引
- 基础 IMAP/SMTP 之外的更多 provider
建议视为稳定的集成边界
在这个 RC 阶段,建议将以下部分视为稳定边界:
mailcli parsemailcli listmailcli getmailcli sendmailcli replyStandardMessageDraftMessageReplyDraftSendResult
验证
go test ./...go build ./cmd/mailclipython3 -m py_compile examples/python/*.py examples/providers/*.py
文档
- 发布说明:
docs/zh-CN/release/v0.1-rc.md - Agent 协作流程:
docs/zh-CN/agent-workflows.md - 发送侧规范:
docs/zh-CN/spec/outbound-message.md - Driver 扩展规范:
docs/zh-CN/spec/driver-extension.md