Agent Mail Gateway

Agent Mail Gateway

为每个 AI Agent 分配专属电子邮件地址，同时不授予其邮箱的访问凭据。

Agent Mail Gateway 是一款小型可自托管服务（单个 Docker 容器），位于 AI Agent 与现有邮件服务器上的普通邮箱之间。每个 Agent 都会获得一个 API 密钥，且只能用于一个邮箱。Agent 可以通过网关读取和回复邮件、发送附件以及管理日历邀请，但只能与获准联系人通信，而且每封外发邮件都会经过检查。

Agent 可通过 MCP（Model Context Protocol）或普通 REST API 与服务通信。邮件会以 Markdown 而非 HTML 格式提供，从而节省大量令牌。

---

为什么要用

将邮箱的 IMAP/SMTP 密码交给 Agent，意味着它可以读取所有邮件、向任何人发送邮件，而一封收到的邮件中的提示词注入就可能导致它泄露数据或向他人发送垃圾邮件。网关会妥善保管密码，并对每项请求执行你的规则：

不使用网关	使用网关
Agent 知道邮箱密码	Agent 只有其邮箱对应的 API 密钥
读取所有邮件，包括垃圾邮件和钓鱼邮件	只能看到来自获准发件人的邮件
可以向任何人发送邮件	只能向获准的收件人发送邮件
草率或错误的邮件会被发出	每封邮件发送前都会经过检查（规则、可选的大模型以及你的策略）
恶意软件和提示词注入会传达到 Agent	收到邮件时会检查附件和内容，并隐藏或标记可疑内容
HTML 邮件会消耗数千个令牌	邮件以精简的 Markdown 格式提供

功能

邮箱访问

• 列出、搜索、读取、标记、删除；支持收发附件——可作为文本、base64，或直接从收到的邮件中获取，让 Agent 无需处理 CSV 的 base64。
• 将 PDF 和图像转换为 Agent 可读取的文本（get_attachment 使用 format: "text"）：内置 PDF 文本层提取，图像则通过视觉模型或本地 OCR（Tesseract）处理。
• 回复（包括回复所有人）和转发——网关会自动填写收件人、Re:/Fwd: 和邮件线程信息。
• 阅读时将 HTML 转为 Markdown，发送时将 Markdown 转为 HTML。

日历

• 发送、更新和取消邀请；邀请会在 Outlook、Gmail 和 Apple Calendar 中正确更新。
• 查看谁接受或拒绝了你的邀请。
• 阅读收到的邀请，并接受、拒绝或暂时接受。

控制与安全

• 为每个邮箱设置允许列表，指定 Agent 可以接收邮件和写信的对象（name@domain 或 *@domain）。其他内容对 Agent 不可见，并会移至废纸篓（或保留）。
• 拒绝伪造的发件人（由你的邮件服务器检查 SPF/DKIM/DMARC）。
• 检查收到的邮件附件和内容；每项检查可设置为隐藏、标记或关闭，也可按发件人跳过：危险文件（程序、宏、伪装的文件类型——默认开启）、使用 ClamAV 进行病毒扫描，以及对文本、PDF 和图像进行提示词注入检查（详情见下文）。
• 设置每小时发送限制，并记录每次发送、拒绝和删除的审计日志。
• 密码错误时不会快速重试，因此服务器的 fail2ban 不会封锁网关。

发送前审核（详情见下文）

• 内置规则会检测空邮件、仅含附件的邮件、提到“见附件”但未附加文件的邮件、遗留占位符和意外重复邮件——默认开启。
• 可选的 LLM 审核（例如使用 Ollama 中的本地模型）会判断“这封邮件是否完整且合理？”。
• 可选的策略：用通俗语言编写自己的规则，可应用于所有人或特定收件人——例如，“绝不分享财务信息”、“绝不向 Alex 提及礼物”。

集成

• 支持通过 Streamable HTTP 使用 MCP、供仅支持 stdio 的客户端使用的 stdio 桥接，以及带有 /docs OpenAPI 文档的 REST API。
• 收到新邮件时发送签名 Webhook（兼容 Hermes Agent Webhook 路由）。
• 提供 Hermes Agent 插件，其中包含教 Agent 使用邮箱的技能。
• 适用于任何 IMAP/SMTP 服务器：Plesk、IONOS、Outlook、Postfix/Dovecot 等。

工作原理

 Agent ──MCP / REST + API key──▶ ┌────────────────────────────────────────┐
                                 │ Auth       key → exactly one mailbox   │
 Agent ◀──signed webhook──────── │ Policy     who may write / be written  │
                                 │ Review     rules · LLM · your policies │
                                 │ Inbound    file types · virus · inject.│
                                 │ Converter  HTML ⇄ Markdown             │
                                 │ Calendar   invitations and replies     │
                                 │ Mailbox    IMAP + instant new-mail push│──IMAP──▶ your mail server
                                 │ Sender     SMTP + copy to "Sent"       │──SMTP──▶
                                 └────────────────────────────────────────┘
                                   config.yaml + .env (read-only)

邮件保留在你的邮件服务器上；网关只会在本地保留一个小型 SQLite 文件来存储自身状态。

快速开始

为每个 Agent 使用专用邮箱（例如 [email protected]），不要使用个人邮箱：默认情况下，不在允许列表中的发件人的邮件会被移至废纸篓。

1. 获取文件：

   mkdir agent-mail-gateway && cd agent-mail-gateway
   curl -LO https://raw.githubusercontent.com/dominikamann/agent-mail-gateway/main/docker-compose.yml
   curl -L -o config.yaml https://raw.githubusercontent.com/dominikamann/agent-mail-gateway/main/config.example.yaml
   curl -L -o .env https://raw.githubusercontent.com/dominikamann/agent-mail-gateway/main/.env.example
   

2. 编辑 config.yaml：为每个 Agent 添加一项，填写其邮件服务器、登录信息和允许列表。
3. 将密钥放入 .env（openssl rand -hex 32 可生成合适的 API 密钥）。
4. 启动并检查：

   docker compose up -d
   curl http://localhost:8080/health   # {"status":"ok"}; with a key also that mailbox's state
   curl -H "Authorization: Bearer <the AGENT_API_KEY from .env>" http://localhost:8080/v1/mailbox
   

邮箱配置的最简示例：

mailboxes:
  - name: assistant
    address: [email protected]
    api_key: ${AGENT_API_KEY}
    imap: { host: mail.yourmailserver.eu, port: 993, security: tls }
    smtp: { host: mail.yourmailserver.eu, port: 465, security: tls }
    username: [email protected]
    password: ${AGENT_MAIL_PASSWORD}
    allow_receive_from: [[email protected], "*@yourcompany.eu"]
    allow_send_to: [[email protected]]

每个选项的说明见 docs/configuration.md。

发送前审核

Agent 有时会马虎——邮件只有附件、写着“请查收附件”却没有文件，或者留下 Hello {name}。网关会在每封邮件和邀请发送前进行检查。如果有问题，就不会发送任何内容，Agent 会收到清晰的错误说明及原因（review_rejected），以便修正消息后重试。被拒绝的尝试不会计入发送限额。

共有三层，可按邮箱分别选择：

层级	默认值	功能
规则	开启（block）	无需 AI 的固定检查：正文为空、只有附件、缺少主题、提及附件但未附上、残留占位符、10 分钟内重复发送同一封邮件、邀请时间已过。
LLM 审核	关闭	请大模型判断消息是否完整且合理（例如，回复是否确实回答了问题）。
策略	关闭	使用自然语言编写自己的规则，由大模型检查——可应用于所有收件人，也可仅应用于指定收件人。

规则和 LLM 审核可以拦截消息、仅发出警告（仍然发送并报告问题），也可以关闭；每条策略规则都可以选择拦截或警告。检查范围包括新邮件、回复、转发、邀请及其更改，以及对邀请回复的评论。

    review:
      rules: block                       # block | warn | off
      llm:                               # any OpenAI-compatible endpoint, e.g. a local Ollama
        url: http://ollama:11434/v1
        model: llama3.1:8b
        mode: warn                       # quality check: warn | block | off
      policies:
        mode: block                      # what a violation does: block | warn
        rules:
          - rule: Never share financial information such as revenue, prices, invoices, bank details or salaries.
          - rule: Never mention gifts, presents or surprise plans.
            recipients: [[email protected]]
          - rule: Never send calendar invitations.
            recipients: [[email protected]]

策略也会读取附件：文本文件、PDF，以及在设置 attachments.read_images 时读取图像。设置 recipients 的规则仅在消息发送给其中某人时生效（收件人、抄送、密送或邀请参与者）。使用 Ollama 时，审核完全在你自己的机器上运行；邮件内容不会离开你的服务器。长消息会分段检查——不会截断内容；可以配置分段大小和限制，以适配模型的上下文窗口。内置审核提示词可以替换或扩展——请参阅 docs/configuration.md。

收件邮件检查

允许列表决定谁可以联系你的 Agent；这些检查则关注收到的内容。对于每项检查，你可以选择发现问题后的处理方式：隐藏消息（类似于发件人不在允许列表中）、标记消息（Agent 可以看到警告，但无法下载危险文件），或关闭。通过 skip_senders，可以跳过对可信发件人的检查——这样你仍然可以通过邮件向 Agent 发送指令。

检查项	默认值	功能
dangerous_attachment	flag	程序和脚本（按名称和内容检查）、含宏的 Office 文件、伪装文件（例如 invoice.pdf 实际并非 PDF）、包含程序的 ZIP 文件、受密码保护的压缩包。也适用于发出的文件。
virus	hide	使用 ClamAV 扫描每个附件（可选容器）；也适用于发出的文件。
prompt_injection	flag	使用 review.llm 中指定的模型检查文本、PDF 和图像中是否包含针对 AI 的指令。
scan_failed	flag	检查无法运行（扫描器或模型无法访问）。

    attachments:
      clamav: { host: clamav, port: 3310 }          # optional, see docker-compose.yml
      read_images: { engine: ocr, languages: [eng, deu] }   # or a vision model
    inbound_checks:
      prompt_injection:
        action: flag
        skip_senders: [[email protected]]       # your own instructions are not flagged
      dangerous_attachment: { action: hide }

图像由视觉模型读取（例如 Ollama 中的 qwen2.5vl），或由网关内的 OCR 读取（Tesseract）；PDF 则由 pdf.js 读取。你可以选择让所有操作都在自己的机器上运行。详情请参阅： docs/configuration.md。

使用方法

MCP 工具

将任意 MCP 客户端指向 http://<host>:8080/mcp，并添加请求头 Authorization: Bearer <api key>，或使用 stdio 桥接。

工具	功能
get_mailbox_info	自己的地址、当前日期和时间、允许列表、限制以及审核规则/政策
list_messages	收到的邮件，按最新优先排序；可按未读筛选，或按文本、发件人、主题、日期搜索
read_message	以 Markdown 格式显示一封邮件，包括附件列表和收到的邀请
get_attachment	下载附件，或将 PDF/图片作为文本读取（format: "text"）
mark_message / delete_message	标记为已读/未读；移至废纸篓（若允许）
send_message	发送新邮件（Markdown、附件）
reply_message / forward_message	在邮件会话中回复（或回复全部）；转发并附带附件
create_event / update_event / cancel_event	发送、更改和取消邀请
list_events / get_event	查看自己的日程及参与者回复
respond_to_invitation	接受、拒绝或暂定接受收到的邀请

REST

# send a message
curl -X POST http://localhost:8080/v1/messages \
  -H "Authorization: Bearer $AGENT_API_KEY" -H "Content-Type: application/json" \
  -d '{"to":["[email protected]"],"subject":"Daily report","body_markdown":"All **green** today."}'

# unread mail
curl -H "Authorization: Bearer $AGENT_API_KEY" "http://localhost:8080/v1/messages?unread=true"

所有端点、错误代码和 webhook 格式：docs/api.md。

Hermes Agent

在 ~/.hermes/config.yaml 中连接 MCP 服务，并安装插件，教会你的 Agent 安全地使用邮箱：

hermes plugins install dominikamann/agent-mail-gateway/integrations/hermes/agent-mail-gateway --enable

分步指南（包括如何在收到新邮件时唤醒 Agent）：docs/hermes.md。

文档

• 配置 — 所有选项、允许列表、审核、端口、发件人身份验证
• REST API、webhook 和 MCP 工具
• Hermes Agent 集成与插件
• stdio 客户端
• 安全模型
• 参与贡献 · 更新日志

安全

请在专用网络上运行网关，或将其置于启用了 TLS 的反向代理之后 — API 密钥通过 Authorization 请求头传输。请按照 SECURITY.md 中的说明私下报告漏洞。

许可证

MIT

---

由 amannlabs.eu 倾力提供