slab-email

面向AI代理的无头电子邮件连接器，通过REST和MCP提供。

slab-email是一个本地优先的微服务，通过标准化的API和MCP工具接口统一邮箱访问。

它专为slab-agents和其他需要安全凭证处理且受控访问多个电子邮件账户的AI运行时设计。

这是什么？

slab-email不是一个电子邮件UI。

它提供：

• 标准化的电子邮件提供商的读取/搜索/创建/发送能力。

• 用于账户和访问配置文件管理的管理REST接口。

• 面向LLM/工具客户端的MCP服务器。

• 针对以下提供商的适配器：

  • Proton（通过Proton Mail Bridge，必需）。

  • 通用IMAP/SMTP。

  • Gmail（通过OAuth2 + Gmail API）。

• 存储在SQLite中的加密凭据。

• 具有按配置文件能力限制的作用域连接令牌。

• 发送幂等性和基本的反循环速率限制。

架构

高级流程：

• slab-agents使用作用域连接令牌调用/mcp。

• REST管理端点配置提供商和访问配置文件。

• 账户存储在SQLite中；凭据在存储时加密。

• 请求时，根据账户配置和解密后的秘密创建提供商实例。

• slab-email针对提供商API（IMAP/SMTP或Gmail API）执行操作。

slab-agents (REST/MCP) -> slab-email
                             |
                             +-> sqlite (config + encrypted secrets)
                             +-> providers
                                 + proton_bridge -> Proton Mail Bridge (local IMAP/SMTP)
                                 + imap_smtp    -> Any IMAP/SMTP
                                 + gmail        -> Gmail API (OAuth2)

特性

• 多账户支持：

  • 同时连接和管理多个账户。

• 提供商抽象：

  • Proton Bridge + 通用IMAP/SMTP + Gmail。

• 连接器作用域权限：

  • 读取 / 草稿 / 发送。

• 使用idempotencyKey实现幂等发送/回复。

• 线程化读取/列表载荷和完整消息水化。

• 使用AES-256-GCM加密的秘密。

• 作用域限定于配置文件的访问令牌。

• 管理API和MCP API通过令牌要求分离。

• 支持Docker和CI。

技术栈

• Node.js + TypeScript

• Express 5

• SQLite（better-sqlite3）

• Zod

• MCP SDK（@modelcontextprotocol/sdk）

• IMAP/SMTP：imapflow，nodemailer

• Gmail：googleapis / google-auth-library

快速开始

1) 启动本地服务

npm install
cp .env.example .env

在.env中设置值，然后运行：

export SLAB_EMAIL_ADMIN_KEY=change-me
export SLAB_EMAIL_MASTER_KEY=<32-byte base64 or 64-hex key>
npm run dev

预期：

• GET /health → {"status":"ok"}。

• /mcp可通过POST /mcp访问。

2) 注册作用域配置文件 + 令牌

使用管理员令牌进行账户/配置文件管理，使用连接器令牌进行常规使用。

配置

必需/相关的环境变量：

• HOST（默认127.0.0.1）

• PORT（默认6981）

• DATABASE_PATH（默认./data/slab-email.db）

• SLAB_EMAIL_ADMIN_KEY（必需）

• SLAB_EMAIL_MASTER_KEY（必需，32字节密钥）

• GOOGLE_CLIENT_ID

• GOOGLE_CLIENT_SECRET

• GOOGLE_REDIRECT_URI（默认http://127.0.0.1:6981/api/oauth/google/callback）

• MAX_SENDS_PER_ACCOUNT_PER_HOUR（默认60）

• MCP_ALLOWED_ORIGINS（逗号分隔）

• MCP_ALLOWED_ORIGINS_HOSTS（逗号分隔）

• PUBLIC_ADMIN_ALLOWED_ORIGINS（逗号分隔）

查看.env.example获取最小启动配置。

Proton Bridge 设置

1. 安装Proton Mail Bridge。

2. 在Bridge中添加你的Proton账户，并复制生成的IMAP/SMTP配置。

3. 通过以下方式将配置应用到slab-email：

   • POST /api/accounts/proton-bridge

4. 测试：

   • POST /api/accounts/:id/test

本项目有意不实现Proton登录自动化。仅使用Bridge生成的凭据。

参见docs/proton.md。

Gmail 设置

1. 创建Google Cloud OAuth凭据。

2. 在.env中设置GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REDIRECT_URI。

3. 启动服务。

4. 使用：

   • POST /api/accounts/gmail/connect获取authorizationUrl。

5. 在浏览器中完成OAuth。

6. 回调：

   • GET /api/oauth/google/callback

7. Gmail账户将连同刷新令牌存储在加密数据库中。

参见docs/gmail.md。

REST API

• 基础：

  • GET /health

  • /api/*

  • POST /mcp

• 认证：

  • 管理员端点：Bearer <SLAB_EMAIL_ADMIN_KEY>

  • 操作和MCP端点：Bearer <作用域连接令牌>

参见docs/api.md获取完整的请求/响应示例。

MCP

端点：POST /mcp

工具：

• email_list_accounts

• email_search

• email_get_message

• email_list_threads

• email_get_thread

• email_create_draft

• email_send

• email_reply

参见docs/mcp.md获取工具载荷和用法。

安全模型

• SLAB_EMAIL_MASTER_KEY用于加密/解密提供商秘密。

• 秘密永远不会通过管理REST/MCP返回。

• 作用域连接令牌在操作上下文中替代管理员密钥。

• 按访问配置文件强制执行读取/写入/发送权限。

• 发送操作通过(accountId, idempotencyKey)实现幂等。

• 未知的发送结果以SEND_OUTCOME_UNKNOWN形式呈现，并且不会盲目地自动重试。

• 每个账户的发送节流默认值：MAX_SENDS_PER_ACCOUNT_PER_HOUR。

• 日志会掩盖可能敏感的密钥。

数据模型

• email_accounts：账户元数据和提供商配置（不含秘密）。

• email_account_secrets：加密的载荷（username，password，refreshToken）。

• access_profiles + access_profile_accounts。

• access_tokens：哈希后的连接令牌。

• send_operations：状态 + 审计字段和idempotency_key。

参见docs/architecture.md。

Docker

• Dockerfile用于构建镜像。

• docker-compose.yml用于本地运行。

注意：Proton Bridge是本地优先的。如果在Docker外的主机上运行Bridge，请仔细配置连接性（主机网络或等效方式），因为容器默认无法访问主机的127.0.0.1凭据。

开发

npm run dev      # start with hot reload
npm test         # run test suite
npm run lint
npm run typecheck
npm run build
npm start        # run production bundle

测试

领域测试涵盖：

• 账户生命周期和秘密加密

• OAuth状态验证

• 配置文件作用域和权限

• 搜索/列表与获取载荷的分离

• 发送幂等性

• 未知发送结果行为

• MCP认证/作用域/工具执行

限制（MVP）

• 不支持附件。

• 没有邮箱同步引擎、本地全文搜索索引或Webhook推送同步。

• 没有批处理/出站活动工作流。

• 此服务中没有Webmail UI。

slab-agents 集成

如果存在../slab-agents，请参阅docs/slab-agents-integration.md了解集成合同和配置。

许可证

MIT