Webhook、API 与 MCP

Webhook、API、MCP 全部属于 Console,Email Worker 不实现这些能力。

全量 HTTP 端点参考(含 Console Web API、/api/v1、MCP、/auth 统一登录)见 docs/API.md;本文只讲设计要点。

Webhook(三级:邮箱 -> 域名 -> 全局)

收到邮件后按邮箱 -> 域名 -> 全局的顺序取第一个已配置的 Webhook(无配置则逐级回退), 入队 delivery(冻结当时的 url/headers/key 配置)。Payload(docs/07, markdown 为正文 Markdown:入库时从 HTML part 转换(参考 mailhook 的 HTML→Markdown 思路), 无 HTML 时取纯文本;v2.1.0 起 payload 携带该字段):

{
  "event": "email.received",
  "id": "msg_xxx",
  "mailbox": "hello@example.com",
  "from": "user@example.org",
  "to": ["hello@example.com"],
  "subject": "Hello",
  "text": "Hello World",
  "markdown": "Hello **World**",
  "received_at": "2026-09-30T10:00:00Z"
}

请求头:X-WmailHub-Event、X-WmailHub-Delivery、X-WmailHub-Timestamp、X-WmailHub-Signature (签名 = HMAC-SHA256(key, ${timestamp}.${body}));配置了 key 时默认携带 Authorization: Bearer <key>,自定义 Authorization 头优先;无 key 时不携带签名头。

2xx 为成功;5xx 和 timeout 按指数退避重试,达到最大尝试次数后置 exhausted。

API

/api/v1/accounts
/api/v1/domains
/api/v1/mailboxes
/api/v1/emails
/api/v1/mcp

API 属于 Console,Bearer API Key(wmh_)认证。

MCP

MCP 允许 Agent 查询域名/邮箱、获取邮件、创建/删除邮箱(list_domains、list_mailboxes、list_emails、 get_email、create_mailbox、delete_mailbox),Bearer MCP Key(wmh_)认证。 create_mailbox(v2.8.0 起)的 domain_id 可省略,省略时随机分配一个已启用 Email Workers 的域名 (此时 address 必须为本地部分);另支持可选 webhook 参数,创建时直接配置邮箱级 Webhook URL。

单一 Key(v2.1.0):API 与 MCP 共用同一个 Key(wmh_ 开头 32 位,设置模态窗口中生成/轮换/撤销), 凭据存 settings 表(api_key_hash/api_key_last4/api_key_created_at),不再单独建 api_credentials 表; 生成新 Key 后旧 Key 立即失效。

MCP/API 获取邮件时必须检查邮件是否过期、mailbox scope 和 API credential scope。

内部 API

/internal/email/authorize 与 /internal/email/ingest 为 Email Worker 专用(docs/04), 与 Webhook/API/MCP 无关。

SSRF

Webhook endpoint 必须防 SSRF,至少阻止 localhost、private IPv4/IPv6、link-local、 metadata endpoint 和 DNS rebinding。

2.5 KiB Raw Blame History

Webhook、API 与 MCP

Webhook(三级:邮箱 -> 域名 -> 全局)

API

MCP

内部 API

SSRF

2.5 KiB

Raw Blame History