Multi Email

Multi Email 是一个开源的 Codex 插件和 MCP 服务器，用于独立授权的 Gmail 和 Microsoft 365 邮箱。每个操作都明确指定 account_alias；没有隐式的活动邮箱。

它支持搜索、读取、草稿、归档、已读状态更改、Gmail 标签、Microsoft 类别，以及通过服务器强制执行的 localhost 审查窗口发送邮件。

发布状态：0.1.2 仅当从 lanfuli/multi-email 下带注释的 v0.1.2 标签或匹配的 GitHub 发布安装时才是官方版本。codex-multi-email npm 包尚未发布；安装前请验证仓库所有者和发布标签。

为什么存在

大多数电子邮件集成假设只有一个活动账户。Multi Email 保持路由明确，以便一个请求可以覆盖多个独立授权的账户，而不会混淆消息 ID、草稿、标签或凭据。

Codex task
  -> Multi Email skill and MCP tools
  -> local Node.js MCP process
  -> Gmail API or Microsoft Graph

OAuth tokens -> macOS Keychain
Account aliases and OAuth app settings -> local mode-0600 config
Mailbox content returned by tools -> Codex conversation/model context

MCP 进程和凭据存储运行在 Mac 上，但端到端工作流不一定仅限本地。提示和工具结果（包括选定的邮件内容）可能会根据用户的产品、账户和数据控制设置由 Codex/OpenAI 处理。Google 和 Microsoft 也会处理提供商 API 流量。请参阅 安全、隐私和数据流。

Related MCP server: Agentic Mail Bridge

安全模型

• 每个操作都需要明确的 account_alias。

• 读取是技能默认；修改需要当前明确的用户请求。

• 不提供永久删除功能。

• 邮件正文、附件、引用文本、签名和链接被视为不可信数据，绝不作为工具指令。

• 搜索、写入批处理、收件人和正文大小均有限制。

• 发送被阻止，直到用户在 127.0.0.1 窗口中查看完整的受支持纯文本草稿并点击“批准”。

• 短生命周期的 approval_request_id 绑定到有效发送清单：经过身份验证的主体、邮箱、有效发送者身份、草稿和线程身份、每个收件人、主题、完整正文、提供商修订版以及已验证的附件缺失。批准会过期、一次性使用，并且任何绑定更改都会使其失效。

• 版本 0.1.2 在提供商草稿包含 HTML、多部分或未知 MIME、内联内容、附件、格式错误的邮箱地址、不支持的 From/Sender/Reply-To 身份或不完整的提供商修订版时，会在审查或发送前关闭。

• 提供商发送请求是根据已批准的允许列表纯文本字段构建的。Gmail 在草稿发送请求中提供该冻结的原始消息；Microsoft 使用一个 MIME sendMail 请求，而不是发送可变的提供商草稿。

• 没有 MCP 工具可以批准自己的发送请求。

• 发送在结果不明确时绝不会自动重试，因为提供商可能已经接受了它。

这些控制减少了意外和提示注入的操作；它们不会使 OAuth 令牌变为只读。Google gmail.modify 和 Microsoft Mail.ReadWrite 以及 Mail.Send 授予了实质性的邮箱访问权限。

支持的操作

该插件不会有意调用提供商附件内容端点、通过 MCP 暴露附件内容、永久删除邮件、操作日历、暴露任意提供商 API，或自动启用发送别名、委派身份或共享邮箱。Gmail format=full 响应仍可能将小的内联 MIME 部分字节传送到本地进程；它们不会由工具返回。消息读取仅暴露附件名称。插件创建的草稿是纯文本。包含 HTML、内联内容、附件、格式错误的邮箱地址或不支持身份的提供商草稿无法通过版本 0.1.2 中的发送审查门。

搜索查询是提供商原生的：Google 使用 Gmail 搜索语法，Microsoft 365 使用 Microsoft Graph 邮件搜索语法。

mail_list_accounts 报告本地凭据是否存在，使用 credentialPresent 和 connectionStatus（credential_present_unverified 或 not_authorized）。这些字段不是身份验证声明。使用 mail_diagnose_accounts 验证当前令牌、范围和提供商身份健康状态。

要求

• 配备 Apple Silicon 或 Intel 的 macOS

• Node.js 22 或更高版本

• 支持本地 stdio MCP 和插件的 Codex 桌面版或 CLI

• 用于 Gmail 账户的 Google Cloud Desktop OAuth 客户端，并启用 Gmail API

• 用于 Microsoft 365 账户的 Microsoft Entra 公共客户端应用程序

提交的 dist/ 捆绑包包含其 JavaScript 依赖项和两个 macOS Keychain 原生二进制文件，因此 Git 市场快照可以在没有提交的 node_modules/ 目录的情况下启动。开发和 npm 库导入仍使用正常的 npm 依赖项。

从 GitHub 安装

最透明的安装是本地克隆：

git clone https://github.com/lanfuli/multi-email.git
cd multi-email
git checkout --detach v0.1.2
node ./scripts/multi-email --help
codex plugin marketplace add "$(pwd)"
codex plugin add multi-email@multi-email

安装后启动新的 Codex 任务，以便发现技能和 MCP 工具。

一旦仓库存在，Codex 也接受 Git 市场源：

codex plugin marketplace add lanfuli/multi-email --ref v0.1.2
codex plugin add multi-email@multi-email

显式的 --ref 将安装的快照保持在已审查的发布版本上，而不是移动的默认分支。仓库市场条目使用文档化的仓库根本地源（"./"）。当前文档化的 Codex 市场模式也有 URL、git-subdir 和 npm 源形式；此仓库不使用 npm 源，因为尚未进行 npm 发布。

下面的设置示例从匹配的本地克隆运行。未来的 npm 安装可以直接使用等效的 multi-email ... 二进制文件；不要从消费项目中运行 npm run setup。

配置 OAuth

默认配置路径是：

~/.config/codex-multi-email/config.json

设置 CODEX_MULTI_EMAIL_CONFIG 以使用另一个绝对路径。设置 CLI 会创建缺失的配置目录，权限为 0700，保持现有父目录的权限不变，写入配置文件时权限为 0600，并拒绝符号链接或非普通文件的配置目标。

独立初始化任一提供商，或在一个命令中提供两个提供商设置。

仅 Google：

node ./scripts/multi-email init \
  --google-client-json /absolute/path/to/desktop-oauth.json

仅 Microsoft：

node ./scripts/multi-email init \
  --microsoft-client-id <entra-application-client-id> \
  --microsoft-tenant organizations

两个提供商：

node ./scripts/multi-email init \
  --google-client-json /absolute/path/to/desktop-oauth.json \
  --microsoft-client-id <entra-application-client-id> \
  --microsoft-tenant organizations

稍后添加或替换 Microsoft 设置：

node ./scripts/multi-email set-microsoft-client <entra-application-client-id> \
  --microsoft-tenant organizations

独立添加和授权每个邮箱：

node ./scripts/multi-email add-account gmail-01 <gmail-address> google
node ./scripts/multi-email auth gmail-01

node ./scripts/multi-email add-account m365-main <microsoft-365-address> microsoft
node ./scripts/multi-email auth m365-main

node ./scripts/multi-email list
node ./scripts/multi-email doctor

仅在文档中使用占位符；不要提交真实地址、OAuth 客户端 JSON、生成的配置、授权 URL、代码或令牌。

Google OAuth

Google 授权通过回环桌面 OAuth 流程请求 openid、email 和 gmail.modify。返回的 Gmail 配置文件必须与配置的地址完全匹配，然后令牌才会存储在 Keychain 中。

自带 OAuth 凭据并不能免除应用或用户遵守 Google 的验证、同意屏幕、测试用户、受限范围、组织、配额或保留要求。处于测试状态的 OAuth 项目可能与已验证的生产应用行为不同，个人账户或管理员仍可能阻止访问。

Microsoft OAuth

Microsoft 授权使用 MSAL 系统浏览器交互式授权，并请求委派的 User.Read、Mail.ReadWrite 和 Mail.Send。在存储 MSAL 缓存之前，/me 配置文件必须与配置的身份匹配。租户策略或管理员同意可能会阻止这些范围。

在 Codex 中使用

始终指定账户别名：

• “使用 gmail-01 查找最近两天的未读消息。”

• “在 gmail-01 和 m365-main 中，总结需要我回复的消息，不要做任何更改。”

• “在 m365-main 中创建回复草稿；不要发送。”

• “诊断所有已配置的账户，不要读取或更改邮件。”

对于发送：

1. 让 Codex 准备选定的草稿以供审查。

2. 在 MCP 服务器打开的 localhost 窗口中检查经过身份验证的身份、有效的 From/Sender/Reply-To、每个收件人、主题、线程头、格式、附件状态以及完整的纯文本正文。

3. 在该窗口中点击“批准”或“拒绝”。

4. 返回 Codex 并明确确认本地审查已完成。

5. 服务器重建有效发送清单，使用一次性批准，重新检查提供商修订版，并将批准的允许列表字段冻结到一个发送请求中。

6. Microsoft 冻结发送有意保留原始源草稿，因为 Graph 的现有草稿发送操作没有条件修订保护。检查结果字段 sourceDraftRetained；未经新审查，不要再次发送该保留的草稿。

不要将本地审查 URL、cookie、nonce、指纹、OAuth 值或 Keychain 内容粘贴到 Codex 或问题中。

更新

对于本地克隆市场：

git fetch origin --tags
git checkout --detach v0.1.2
codex plugin add multi-email@multi-email

仅将 v0.1.2 替换为您已审查的较新带注释的发布标签。使用 --ref 安装的 Git 市场保持固定，因此显式将其移动到新版本：

codex plugin remove multi-email@multi-email
codex plugin marketplace remove multi-email
codex plugin marketplace add lanfuli/multi-email --ref v0.1.2
codex plugin add multi-email@multi-email

重新安装后启动新的 Codex 任务。

卸载并删除本地数据

移除插件和市场：

codex plugin remove multi-email@multi-email
codex plugin marketplace remove multi-email

插件移除不会删除 OAuth 凭据或配置。在删除克隆之前，优先使用受保护的生命周期命令：

node ./scripts/multi-email logout <alias> --confirm
node ./scripts/multi-email revoke <alias> --confirm

logout 删除本地凭据。revoke 还会在提供商安全支持的情况下尝试提供商端撤销；Microsoft 可能需要通过 Microsoft My Apps 移除，然后执行 logout。检查命令结果，而不是假设提供商撤销成功。

当前 Keychain 项目使用服务 io.github.lanfuli.multi-email。历史安装可能还有 com.openai.codex.multi-email 下的已验证旧项目；凭据存储仅在验证提供商身份后迁移，而 doctor 故意只读，从不迁移。使用 macOS Keychain Access 进行可选的旧项目清理，并在删除 ~/.config/codex-multi-email/config.json 之前检查确切的配置路径。

开发

npm ci
npm run validate
npm run pack:check
npm audit --omit=dev --audit-level=high

npm run build 使用 package-lock.json 中确切的 @vercel/ncc 版本，生成 CommonJS 捆绑包 dist/server.cjs，并包含 keyring.darwin-arm64.node 和 keyring.darwin-x64.node。CommonJS 是有意为之，因为原生 Keychain 加载器依赖于 Node 的 __filename/createRequire 行为。冷安装检查测试了无依赖的 Git 快照和已安装的 npm tarball。

包元数据在结构上已为未来名为 codex-multi-email 的公共 npm 包做好准备，但本 README 不声称该名称已保留或包已发布。维护者必须进行身份验证、验证所有权、检查 npm publish --dry-run，并显式发布。

参见 CONTRIBUTING.md、SECURITY.md 和 CHANGELOG.md。

故障排查

• 未知别名： 运行 node ./scripts/multi-email list，然后在每次调用时使用确切的别名。

• 连接状态不明确： 为单个别名或所有别名调用 mail_diagnose_accounts；它会检查凭据是否存在、令牌是否可用、作用域和身份，而不会读取消息或进行写入。

• 未授权或令牌已过期： 重新运行 node ./scripts/multi-email auth <alias>；切勿将令牌粘贴到聊天中。

• 审查请求已过期/被拒绝： 在本地窗口中准备新的审查并做出新的决定。

• 批准后草稿发生更改： 再次审查完整的新草稿。

• 草稿不可审查： 移除 HTML、内联内容、附件、备用发件人身份或额外的 Reply-To 值，或通过 Multi Email 将其重新创建为纯文本草稿。不要绕过门禁。

• 发送结果不确定： 不要重试；先以只读方式检查 Drafts 和 Sent。

• Gmail 授权被阻止： 验证 OAuth 同意屏幕、测试用户状态、请求的 Gmail 作用域、账户/组织策略以及应用验证状态。

• Microsoft 同意被阻止： 验证公共客户端设置、租户选择、委派权限和管理员策略。

• 共享邮箱或备用发件人地址： 在实现并端到端验证确切的委派身份和权限之前，暂不支持。

许可证

MIT © 2026 Vincent_Lan。参见 LICENSE。