Skip to content

MailCLI v0.1.0

Choose a tag to compare

@nonozone nonozone released this 31 Mar 04:33
· 18 commits to main since this release

中文 | 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/