Mailbox

mailbox

通过一个 HTTP API 和位于同一端口的 /mcp MCP 端点，跨多个 IMAP/SMTP 账户读取、整理、起草和发送邮件。每个 bearer token 都会控制客户端可访问的操作和邮箱。

如需供 Agent 访问，请为令牌配置明确的权限：

• 受限令牌。 持有 read、draft 和 organize 权限的令牌无法发送或删除，也看不到这些工具。
• 删除默认移至 Trash。 删除操作会将邮件移至 Trash。永久删除需要 delete 权限，且只能从 Trash 文件夹执行。服务绝不会对整个文件夹执行 EXPUNGE。
• 分两步起草。 Agent 可以准备回复；由人工（或持有 send 权限的令牌）发送。
• 发送保护。 包含每小时速率限制、试运行模式，以及经配置的精确身份或选择加入的域名模式授权的发件人地址。
• 邮件分析。 检查 SPF/DKIM/DMARC 判定、标头不匹配、隐藏文本和欺骗性链接。只有当接收服务器与您的配置匹配时，判定结果才可信。需要时可请求经过净化的 HTML。
• 审计日志。 每次写入操作以及每次被拒绝的写入操作都会记录（绝不记录邮件正文）。

邮件正文和草稿保留在 IMAP 上。共享的 SQLite 数据库存储审计记录、发送计数器、检查点、草稿发送声明和 webhook 投递元数据。API 请求会在使用完毕后关闭邮件服务器连接；监视器会保持 IMAP 连接打开以接收通知。

该服务使用 Python 的 imaplib 和 smtplib、FastAPI、官方 MCP Python SDK，以及用于 HTML 净化的 nh3。依赖更新通过 uv 的 exclude-newer 设置强制执行七天的版本发布日期限制。

目录

• 快速开始
• 配置
• HTTP API、MCP、安全和 webhook
• Agent 集成
• 架构和开发
• 运维、备份和迁移

快速开始

1. 将 config.example.yaml 复制为 config.yaml，并将 .env.example 复制为 .env。配置您的账户，并将 .env 中的每个占位符替换为对应密码或通过 openssl rand -hex 32 生成的新令牌。使用 chmod 600 限制这两个文件的访问权限。
2. 启动容器。命名卷会在重启后保留运维状态：

docker run --rm \
  -p 127.0.0.1:8000:8000 \
  --env-file .env \
  -v "$PWD/config.yaml:/etc/mailboxd/config.yaml:ro" \
  -v mailboxd-state:/var/lib/mailboxd \
  psyb0t/mailbox:latest

3. 检查运行状况并列出邮件：

TOKEN="paste-the-token-here"

curl -s http://localhost:8000/health | jq                                               # health is always open
curl -s -H "Authorization: Bearer $TOKEN" http://localhost:8000/mailboxes | jq
curl -s -H "Authorization: Bearer $TOKEN" 'http://localhost:8000/inbox?limit=5' | jq

Docker Compose

仓库中的 docker-compose.yml 会在 127.0.0.1:${PORT:-8000} 上发布服务，以只读方式挂载 ./config.yaml（或 $MAILBOXD_CONFIG），并创建 mailboxd-state 卷：

services:
  mailboxd:
    image: psyb0t/mailbox:latest
    ports: ["127.0.0.1:8000:8000"]
    volumes:
      # Keep config.yaml out of Git and restrict access to its credentials.
      - ./config.yaml:/etc/mailboxd/config.yaml:ro
      - mailboxd-state:/var/lib/mailboxd
volumes:
  mailboxd-state:

可选的 webhook 监视器是在同一文件中的第二个服务，默认关闭：docker compose --profile watch up -d。

功能

类别	操作
读取	统一收件箱、结构化搜索、原始来源、标头、附件和邮件线程
整理	已读标记、标签、移动、创建邮箱和 Trash
发送	已配置的身份、签名、回复、IMAP 草稿和已发送邮件副本
访问	REST 和 MCP 共用的逐令牌权限范围和邮箱允许列表
运维	SQLite 审计记录、共享发送限制、检查点和持久化签名 webhook

挂载 /var/lib/mailboxd 以持久化运维状态。HTTP 工作进程和可选监视器会在本地文件系统上共用一个 SQLite 数据库。替换无状态部署前，请阅读迁移说明。

开发

make lint           # flake8 and mypy
make test-coverage  # full suite, production container and coverage floor
make audit          # frozen runtime and dev dependency advisories
make build          # production image
make help           # all available targets

所有项目工具均在开发镜像中运行。测试使用套接字级 IMAP/SMTP 固件、本地 HTTP 接收器、真实 SQLite 文件和生产容器冒烟测试。详情请参阅开发。

许可证

WTFPL。请参阅LICENSE和第三方组件。