bigcode
7370cce784
- 单一 Key:API 与 MCP 共用一个 wmh_ Key,凭据迁移至 settings 表(0004 删除 api_credentials) - Markdown:入库时 HTML→Markdown(mailhook 同思路),webhook payload 新增 markdown 字段 - /emails 路由改为 /inboxs 并支持域名筛选;设置按钮移入头像下拉 - 主题切换按钮(头像左侧,亮/暗持久化);设置模态仅 全局 Webhook/账号密码 两 tab 且高度限屏 - 列表操作列按钮加 SVG 图标;mailboxes 去 Webhook 列;最近邮件加收件人列
64 lines
2.1 KiB
Markdown
64 lines
2.1 KiB
Markdown
# Webhook、API 与 MCP
|
|
|
|
Webhook、API、MCP 全部属于 Console,Email Worker 不实现这些能力。
|
|
|
|
## Webhook(三级:邮箱 -> 域名 -> 全局)
|
|
|
|
收到邮件后按 邮箱 -> 域名 -> 全局 的顺序取第一个已配置的 Webhook(无配置则逐级回退),
|
|
入队 delivery(冻结当时的 url/headers/key 配置)。Payload(docs/07,
|
|
`markdown` 为正文 Markdown:入库时从 HTML part 转换(参考 mailhook 的 HTML→Markdown 思路),
|
|
无 HTML 时取纯文本;v2.1.0 起 payload 携带该字段):
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```text
|
|
/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_mailboxes、list_emails、get_email、
|
|
create_mailbox、delete_mailbox),Bearer MCP Key(wmh_)认证。
|
|
|
|
**单一 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。
|