Skip to content

Releases

v0.2.0

Choose a tag to compare

@github-actions github-actions released this 06 Jul 12:07

What's Changed

  • feat: make MailCLI Go-only and add config diagnostics by @nonozone in #1

New Contributors

Full Changelog: v0.1.0...v0.2.0

MailCLI v0.1.0

Choose a tag to compare

@nonozone nonozone released this 31 Mar 04:33

中文 | 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 — .json paths 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-sync writes 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 — Reference watch → LLM → reply pipeline
  • tools/README.md — Integration guide with tool_to_cmd dispatch 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 support
  • examples/python/agent_inbox_assistant.py — Inbox-mode AI agent
  • examples/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.db

Getting 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.py

Full documentation: docs/en/

MailCLI v0.1.0-rc1

MailCLI v0.1.0-rc1 Pre-release
Pre-release

Choose a tag to compare

@nonozone nonozone released this 26 Mar 05:45

MailCLI v0.1.0-rc1

First release candidate for MailCLI as an open, AI-native email interface.

Highlights

  • Parse raw email into StandardMessage JSON and Markdown
  • Read inboxes through the baseline IMAP driver with list and get
  • Send new outbound drafts and replies through SMTP-backed IMAP-style accounts
  • Support reply_to_message_id and reply_to_id reply flows
  • Compile outbound MIME with multipart/alternative and attachment packaging
  • Expose stable machine-facing contracts for agents:
    • StandardMessage
    • DraftMessage
    • ReplyDraft
    • SendResult
  • Ship Python and shell examples, including an external provider contract and an optional OpenAI provider example

Included In This RC

  • mailcli parse
  • mailcli list
  • mailcli get
  • mailcli send
  • mailcli reply
  • IMAP raw fetch by sequence number, UID, and Message-ID
  • Stable outbound result codes such as auth_failed, message_not_found, and transport_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 parse
  • mailcli list
  • mailcli get
  • mailcli send
  • mailcli reply
  • StandardMessage
  • DraftMessage
  • ReplyDraft
  • SendResult

Verification

  • go test ./...
  • go build ./cmd/mailcli
  • python3 -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。

亮点

  • 将原始邮件解析成 StandardMessage JSON 和 Markdown
  • 通过基础 IMAP driver 提供 list / get 收件箱读取能力
  • 通过面向 IMAP 风格账户的 SMTP 路径发送新邮件和回复
  • 支持 reply_to_message_id 和 reply_to_id 回复流程
  • 出站 MIME 已支持 multipart/alternative 和附件打包
  • 为 agent 暴露稳定的机器接口:
    • StandardMessage
    • DraftMessage
    • ReplyDraft
    • SendResult
  • 提供 Python / shell 示例,以及 external provider 契约和可选 OpenAI provider 示例

这个 RC 已包含

  • mailcli parse
  • mailcli list
  • mailcli get
  • mailcli send
  • mailcli 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 parse
  • mailcli list
  • mailcli get
  • mailcli send
  • mailcli reply
  • StandardMessage
  • DraftMessage
  • ReplyDraft
  • SendResult

验证

  • go test ./...
  • go build ./cmd/mailcli
  • python3 -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