Mailflow

Reliably trigger OpenCode sessions and prompts from classic Outlook emails, while giving OpenCode agents a controlled set of email MCP tools.

Mailflow does not cram email listening, rules, session invocation, approval, and UI back into one big plugin. The first release uses an independent Core, a Windows Outlook connector, an OpenCode HTTP adapter, and narrow-responsibility MCP; the original win-console remains untouched, with compatibility tools and a dry-run-first migration path.

Final Form

flowchart LR
  O["Outlook Classic<br/>Windows 用户会话"] -->|"标准化邮件 / Outlook 命令"| C["Mailflow Core<br/>SQLite · 规则 · 队列 · 审批"]
  C -->|"创建 session + prompt_async"| OC["OpenCode Server"]
  OC --> A["OpenCode 会话 / Agent"]
  A -->|"stdio MCP"| M["Mailflow MCP"]
  M -->|"受 token 保护的 API"| C
  C -->|"草稿 / 导出 / 经审批发送"| O
  UI["本地中文管理台"] --> C
  WC["原 win-console"] -. "兼容工具 / 能力注册 / 可回滚迁移" .-> C

Boundaries are clear:

• The Outlook connector only handles Outlook data adaptation, reliable delivery, and Outlook native actions; the specific transport mechanism is not a Core contract.

• Core is the single source of truth, responsible for SQLite, rule versions, idempotency, retries, auditing, approval, and connector commands.

• Core directly calls the OpenCode HTTP API to create sessions and asynchronously submit prompts.

• MCP only provides email reading, attachment export, reply drafting, and approved sending tools for agents within a session; it does not listen to the mailbox.

• The admin console handles rules, operations, approval, and failure recovery, independent of the Outlook panel.

Outlook Plugin or OpenCode Plugin?

The first version does not do a "heavy plugin" on either side. This is a deliberate choice:

So: design content can certainly be displayed on an Outlook extension panel, but the core should not be placed inside it. Classic Outlook's VSTO/COM add-ins are affected by Office bitness, signing, load disabling, and process lifecycle. The current deliverable uses an independent tray-style COM connector; when a thin VSTO panel is added later, Core, MCP, or the database will not need changes. OpenCode plugins are also an optional experience layer; session triggering is already done via a stable HTTP API.

v0.1.0 Already Includes

• Node.js 24 + built-in SQLite zero-runtime-dependency Core.

• Email event storage, rule matching, rule versioning, run state machine, idempotency keys, leases, exponential backoff retry, and dead letter.

• OpenCode session creation and prompt_async, supporting per-message, per-conversation, and pinned-session strategies.

• Prompt safety envelope: email content explicitly marked as untrusted data, with body/attachment size limits.

• Standard MCP stdio server, plus legacy tool aliases like outlook_search, outlook_read, outlook_attachments.

• Windows x64 Outlook Classic connector: email delivery, Outlook native read/write, command idempotency, and send reconciliation.

• send_unknown safety closure: 5 bounded delay checks, admin console manual confirmation, and "generate a brand new approval after confirming not sent"; no check will automatically resend.

• Reply drafts first sync with Outlook before opening approval; normalized hashes of subject, recipients, and body jointly prevent sending old drafts; auto-send is off by default.

• Chinese-language admin console, REST API, and SSE status stream.

• win-console rule/status dry-run import, capability registration/heartbeat, and clear rollback path.

• Linux Core tests, Windows connector build, and tag-driven GitHub Release workflow.

Quick Start

1. Download

Get from GitHub Releases:

• email-workflow-0.1.0-runtime.zip: Core, MCP, admin console, documentation, and connector source code;

• email-workflow-0.1.0-outlook-classic-win-x64.zip: Self-contained Windows x64 connector;

• aleygey-email-workflow-0.1.0.tgz: npm format runtime package.

Core requires Node.js 24+; connector requires Windows x64 with classic desktop Outlook.

2. First Initialize Keys and Merge OpenCode Security Configuration

Do not start OpenCode first, nor overwrite existing opencode.json/opencode.jsonc with example files. First generate .env in the runtime extraction directory:

node dist/src/cli.js init --output .env

Merge the agent.mailflow-email and mcp.mailflow from examples/opencode-mailflow-complete.json into your existing OpenCode configuration, preserving existing providers, models, agents, plugins, and other MCPs. Runtime zip users should change the command in the example to an absolute path on the local machine, for example:

"command": ["node", "C:\\Mailflow\\email-workflow\\dist\\src\\mcp\\cli.js"]

The examples do not embed secrets. The same user environment that starts OpenCode must have MAILFLOW_MCP_TOKEN set, with the same value as MAILFLOW_API_TOKEN in .env; it is not the connector token:

$env:MAILFLOW_MCP_TOKEN = "<复制 .env 中 MAILFLOW_API_TOKEN 的值>"

MAILFLOW_CONNECTOR_TOKEN is only used by the Outlook connector and must be different from the API/MCP token. init refuses to overwrite an existing .env by default.

3. Start OpenCode

opencode serve --hostname 127.0.0.1 --port 4096

OpenCode must be started from the environment where MAILFLOW_MCP_TOKEN was just set, so that {env:MAILFLOW_MCP_TOKEN} in the example can be resolved.

4. Start Mailflow Core

Modify the OpenCode address in .env as needed, then start in the runtime extraction directory:

node --env-file=.env dist/src/cli.js serve

Production operation requires two non-empty and different tokens; starting Core without authentication is not supported as a default. The defaults OPENCODE_MAILFLOW_AGENT=mailflow-email and OPENCODE_REQUIRE_SAFE_AGENT=true are set; do not disable validation just to "get it running first".

Visit http://127.0.0.1:8798. On first entry to the admin console, save the API token in Settings.

Running from source:

npm ci
npm run check
npm run dev

5. Start Outlook Connector

Extract the Windows connector, copy connector.example.json to:

%LOCALAPPDATA%\Mailflow\OutlookConnector\connector.json

Set the same connector token as Core, keep coreBaseUrl as http://127.0.0.1:8798, then run:

.\mailflow-outlook-connector.exe

See the Operations Manual for full configuration, key delivery, and troubleshooting steps.

How an Email Becomes a Session

1. The connector submits the email according to a stable contract; Core receives it and deduplicates by connector/event ID; the connector's internal ingestion/recovery method does not enter the business contract.

2. Core normalizes the email, saves it to SQLite, and performs matching against fixed versions of enabled rules.

3. On match, a run with a stable idempotency key is created; the worker leases the run, retrying with exponential backoff when offline.

4. The OpenCode adapter creates or reuses a session and adds the mailflow_run_id stable marker to the prompt.

5. Before each prompt submission, Core verifies that the target mailflow-email agent exists and still has fail-closed permissions; if the agent needs email information, it calls back to Core via approved read-only MCP tools.

6. The AI reply is first synced as an Outlook draft; approval appears only after successful sync. On approval, both the Core draft version and the normalized hash of Outlook's subject/recipients/body are verified; every step writes an audit log.

Security Defaults

• Core listens only on 127.0.0.1 by default; OpenCode connections only accept loopback HTTP or HTTPS. Remote plaintext HTTP is denied by default.

• First startup must execute node dist/src/cli.js init --output .env; Core enforces that both API token and connector token exist, are different from each other, each at least 32 UTF-8 bytes, and rejects public placeholders from examples. MCP uses the API token via MAILFLOW_MCP_TOKEN; the connector uses a separate token.

• All Core write requests with a body must declare JSON Content-Type; non-JSON requests return 415 directly.

• The default agent is mailflow-email. Core reads the agent definition from OpenCode before each prompt submission: there must first be a catch-all * deny boundary, followed by only read/glob/grep/list within the workspace, *.env/*.env.* deny covering any directory level, and the precisely named read-only Mailflow MCP tools from the example. The read-only MCP whitelist is search/get/list-attachments/get-run and the purely read legacy search/read; outlook_attachments, which can export files, is not included. If the agent is missing, the permission response is unrecognizable, or any other allow appears, it fails closed.

• Rules are created disabled by default; preview first, then enable.

• Email body is data, not instructions; attachments expose only metadata by default.

• Replies require manual approval. AI replies must first complete Outlook draft sync; modifying in the approval interface invalidates the old approval, queues a draft.update, and after successful sync generates a new approval that the user must click again. If the subject, To/Cc/Bcc, or body in Outlook changes after approval, the normalized hash mismatch prevents sending.

• When MailItem.Send() cross-process result is uncertain, it enters send_unknown. Core only performs 5 delayed status checks; the admin console can "Check Outlook", "Confirm Sent", or "Confirm Not Sent". Confirming not sent invalidates the old approval and generates a new one, still requiring another click; the system never turns reconciliation into automatic resending.

• Legacy data import defaults to dry-run; applying the import requires explicit --apply.

The current version's read-only agent can still read the selected workspace and query other emails in this Core via approved MCP tools; it is not a per-run independent data sandbox. SQLite also persistently stores email bodies and raw snapshots; v0.1.0 has no automatic retention cleanup task. Production use should configure a dedicated least-privilege workspace/mailbox, controlled model accounts, Windows directory ACLs, full-disk encryption, and operational data retention cycles; strict cross-project/cross-mailbox isolation requires future per-run capabilities. See SECURITY.md.

MAILFLOW_ALLOW_UNAUTHENTICATED_LOOPBACK=1, OPENCODE_ALLOW_INSECURE_REMOTE=1, and OPENCODE_REQUIRE_SAFE_AGENT=false are only for isolated local development diagnostics, not production configurations, and cannot be used to process real emails.

Do not expose Core or OpenCode server directly to the public internet. For cross-Windows/WSL or cross-machine deployments, use HTTPS, origin restrictions, and firewalls. More details in SECURITY.md.

win-console Will Not Disappear

The old repository is not deleted, overwritten, or history-changed. Mailflow additionally provides:

• Compatibility aliases for old MCP tool names;

• external-capabilities registration and heartbeat;

• Migration reports for rules, processed receipts, queues, and checkpoints;

• Default dry-run, explicit apply, source file SHA-256, and target mapping;

• Anti-dual-trigger steps and one-click logic rollback during switching.

See docs/legacy-win-console-baseline.md for the complete item-by-item mapping.

Documentation Navigation

• Full Design Document: User interface, six complete flows, API, data, security, testing, and phased implementation.

• Architecture Boundaries: Why split into Core, connector, adapter, MCP, and optional UI.

• Operations Manual: Installation, OpenCode/MCP configuration, backup, migration, rollback, and troubleshooting.

• win-console Compatibility Baseline: Legacy features, legacy data, and rollback requirements.

• v0.1.0 Release Notes.

Development and Verification

npm ci
npm run typecheck
npm test
npm run pack:release

Windows connector:

dotnet build connector/Mailflow.OutlookConnector/Mailflow.OutlookConnector.csproj -c Release

Since Outlook COM depends on a real Windows user profile, CI handles Windows compilation and non-COM tests; before release, still perform connection, email ingestion, draft sync, secondary approval, and sending smoke tests on the target machine's classic Outlook.

License

MIT