统一多账户邮件收件箱：插件化过滤、LLM 智能分析、富终端界面与可嵌入核心
Unified multi-account mail inbox — plugin pipeline, LLM analysis, rich TUI, embeddable core
MailFlow merges mails from multiple accounts and providers into one stream, classifies every message with a four-level urgency contract, extracts timed obligations (exams, meetings, errands) into a schedule table with reminders, stores everything with a recoverable trash, and surfaces it through a Textual TUI, a colored command shell, or any chat-bot host embedding the core. Extend it with plugins — mail sources, LLM backends, processors, notifiers, storage — installed from a plugin marketplace.
- Multi-account, multi-adapter — provider adapters merge into one bounded stream; per-account failure isolation.
- Four-level urgency contract —
ad #909399(junk) ·info #67C23A(useful) ·important #E6A23C(read it) ·urgent #F56C6C(act now). Colors are part of the public contract, reused by CLI, TUI and notifiers. - LLM analysis — OpenAI-compatible chat completions (works with OpenCode relays, llama.cpp, vLLM) plus an Anthropic Claude backend; named LLMs with ordered fallback; structured summaries, reasons, reply drafts and timed action items.
- Timed-action table + reminders — exams/meetings/errands with time, type, content and preparation notes, drilling into the source mail; reminders fire at a configurable fixed time two days before the due date and at midnight on the due day.
- Two-step confirmed replies — draft → prepare (short-lived token) → confirm; double-send safe, editing invalidates the token.
- Recoverable retention — configurable mail retention (default 30 days) with a daily 04:00 cleanup; deleted mails recoverable for 7 days in trash.
- Rich logging — queue-based rich console output, rotating file, JSONL; levels, redirects and secret redaction all configurable; never touches the host's root logger.
- i18n — English (default) and Simplified Chinese built in; other languages load as data-only JSON packs; the choice persists.
- Plugin marketplace (VS Code style) — search, category filters, markdown details, install / uninstall / enable / disable from commands and the TUI; built-ins are categorized (mail_source, processor, llm_backend, notifier, storage, bot_exporter); disabling a plugin never breaks startup (orphaned config entries are skipped with a warning).
- Bot-framework export — turn a configured instance into a plugin for
NoneBot2, AstrBot or any other chatbot framework (
mailflow export --framework <id>, TUI export wizard with folder tree,make bot-plugin-*); exporters are plugins themselves, so new frameworks are a marketplace install, not a core change. - Full config management — every option visible in the TUI and the
configcommand (required/optional, defaults, descriptions, redacted secrets);config setpersists. - Quality gates — 144 unit/integration/e2e tests, mypy & pyright strict, ruff lint + format, Nuitka standalone/onefile executables, docs gate.
Requires Python ≥ 3.11 and uv.
git clone https://github.com/mailflow/mailflow.git
cd mailflow
uv sync --all-packages --group dev# edit configs/development.toml: add your mailbox(es) and LLM endpoint(s)
uv run mailflow tui -c configs/development.toml
uv run mailflow shell -c configs/development.toml
# or copy the example config, fill in your tokens, and run
cp configs/example.toml configs/local.toml
export YOUR_TOKEN=your-token
uv run mailflow run -c configs/local.tomlSee docs/development/setup.md for details.
help colored command documentation
mail list|show|delete|urgency <id> <level|auto>
action list|show|add|delete timed tasks; add "<summary>" --due "YYYY-MM-DD HH:MM" [--type] [--notes]
plugin list|show plugins, adapters, accounts, llms, bindings
plugin repo add|list|remove manage marketplaces
plugin market list|show|search <query> browse/store with markdown details
plugin install|uninstall <id> install or remove a plugin
plugin enable|disable <id> toggle a plugin (applies on next start)
export --framework <id> --output <dir> generate a chatbot-framework plugin (NoneBot, AstrBot, ...)
reply create|compose cn/en|edit|prepare|confirm|cancel compose: letter template (auto date, right-aligned signature)
lang get|set <code> switch language (persisted)
trash list|restore recover deleted mail
config list|get|set inspect and change every option
from mailflow.service import start_service
from mailflow_bundled import create_plugin_manager
service = await start_service(
config,
plugin_manager=create_plugin_manager(config),
extra_log_handlers=[my_host_handler],
)
snapshot = service.snapshot() # plugins, accounts, LLMs, bindings
mails = await service.list_mails() # full records + analysis + actions
service.on("mail.processed", handler) # async events
await service.commands.execute("mail list")
await service.stop()See docs/development/embedding.md.
| Level | Color | Meaning |
|---|---|---|
ad |
#909399 | irrelevant advertising / junk |
info |
#67C23A | useful but not time-critical (lecture notice) |
important |
#E6A23C | needs reading (verification code) |
urgent |
#F56C6C | must be handled now or at a specific time (exam) |
Manual overrides win while set; reset restores the automatic value.
make help # grouped, colored list of every target
make check # lint + format + mypy + pyright + pytest + docs gate
make coverage # per-package coverage report
make build # wheels for every package
make bot-plugin-nonebot | bot-plugin-astrbot # export the NoneBot / AstrBot plugin
make bot-plugin FRAMEWORK=<id> OUTPUT=<dir> # export for any installed exporter
make exe-standalone # Nuitka standalone (smoke test before onefile)
make exe-onefile| Area | Links |
|---|---|
| Architecture | overview · domain & mail · plugins · pipeline · LLM · logging · storage & retention · replies · TUI · bot export |
| Development | setup · deployment · embedding · tests · quality · packaging |
| Plugin development | overview · mail source · processor · LLM backend · notifier · storage · bot exporter |
| Configuration | overview · i18n |
| For AI agents | invariants · module map · change playbook |
| Decisions | ADRs · 0002-pluggy-pipeline · 0003-host-independent-core |
| Build history | BUILD_LOG · 简体中文 README |
Browse and install plugins from remote repositories:
uv run mailflow plugin repo add mailflow-repo https://github.com/Kingcxp/mailflow-repo
uv run mailflow plugin market list
uv run mailflow plugin market show mailflow-notify-ntfy
uv run mailflow plugin install mailflow-notify-ntfy # restart to loadThe mailflow-repo repository hosts the marketplace: one folder per plugin, grouped by category, so adding a plugin is a single pull request that never touches other plugins' files. Its docs/ folder is the plugin-development guide, and a pull-request workflow validates exactly the plugins each PR changes.
Write your own plugin — the TUI has a new-plugin wizard (Market tab →
New): pick a folder in the directory tree, optionally create a subfolder,
choose the template category (mail source / processor / LLM backend /
notifier / storage / bot exporter), and MailFlow generates a complete,
loadable template. The wizard is also available to hosts embedding the core
via mailflow.plugin_template.scaffold_plugin.
Ship MailFlow as a bot plugin — the Market tab's Export button opens the
same folder-tree wizard, now selecting a framework (NoneBot, AstrBot, ...)
and exporting a ready-to-install framework plugin from your configured
instance. The command-line equivalent is mailflow export --framework <id> --output <dir>; exporters are plugins, so a new framework is one install
away. The exported plugin embeds the full chat command surface: messages
starting with mailflow (NoneBot) or /mailflow (AstrBot) are dispatched
to the shared command router, long replies are split into several messages,
and the daily digest is paginated into chat. See
docs/architecture/bot-export.md.
Localized and styled — plugins can ship translated one-line
descriptions and markdown readmes (descriptions / readmes in
plugin.json); CLI and TUI automatically use the variant matching the app
language, and market show renders the readme with rich markdown effects
(bold, strike, <span style="color:#ff5500">colors</span>).
packages/mailflow-core host-agnostic domain, pipeline, service facade, bot export
packages/mailflow-bundled composition root: the official plugin set
packages/mailflow-cli rich Typer host (run/command/shell/export/...)
packages/mailflow-tui Textual UI (Mail/Actions/Runtime/Logs/Market/Settings + export wizard)
packages/mailflow-testkit deterministic fakes for tests (mailflow-mail-fake is a dev-only source plugin)
plugins/* discoverable adapters, processors and bot exporters
configs/ · translations/ example configs and language packs
docs/ architecture, development, agent documentation
MIT. IMAP is built in with presets for QQ, 163, Outlook and Gmail (any generic server works too) — see CHANGELOG.md.