mail2webhook API 帮助

收到邮件 → 存本地 SQLite → POST 回调该邮箱绑定的 webhook。创建邮箱、管理域名、检索邮件都走下面的 HTTP API。

鉴权：除 /healthz 和本帮助页外，所有请求需带请求头 Authorization: Bearer <api_key>（api_key 配置在服务端 config.yaml）。

1. 域名管理

方法	路径	说明
POST	`/api/domains`	新增收件域名。body：`{"domain":"example.com"}`。重复添加幂等（返回 created:false）
GET	`/api/domains?q=关键字`	列出/检索域名（含每个域名的邮箱数）。`q` 为子串过滤，可省略
DELETE	`/api/domains/{domain}?purge=true`	删除域名。域名下还有邮箱时返回 409；确认连邮箱（含全部邮件）一起删加 `?purge=true`

2. 邮箱管理

方法	路径	说明
POST	`/api/mailboxes`	创建/更新邮箱。body（均可省略）：`{"prefix":"test1","domain":"mail.3823.net","webhook_url":"https://...","webhook_format":"raw"}`。prefix 省略则随机；domain 省略用最早添加的域名；webhook_url 省略用服务端 default_webhook_url；webhook_format 省略用 default_webhook_format。重复创建同地址 = 更新其 webhook
GET	`/api/mailboxes`	列出所有邮箱（含邮件计数）
DELETE	`/api/mailboxes/{email}`	删除邮箱及其全部邮件

3. 邮件读取

方法	路径	说明
GET	`/api/mailboxes/{email}/emails?limit=20`	该邮箱的邮件列表（新→旧，limit ≤ 100）
GET	`/api/emails/{id}`	单封邮件详情（含 headers 对象）
GET	`/api/emails/{id}/raw`	原始 .eml 报文下载

Webhook 回调格式

邮件到达后，服务会向邮箱绑定的 webhook_url 发 POST 请求，格式由 webhook_format 决定：

raw（默认）：请求体为原始 .eml 邮件报文，Content-Type message/rfc822。适合服务端自行解析原始邮件。
json：请求体为结构化 JSON（字段：id / mailbox / from / to / subject / body_text / body_html / headers / received_at），Content-Type application/json。

两种格式都附带请求头 X-Mail2Webhook-ID（邮件 ID）与 X-Mail2Webhook-Mailbox（收件邮箱）。回调失败只记日志，不重试、不影响收信。

SMTP 收信规则

只收「域名已注册 + 邮箱已创建」的收件人，其余在 RCPT 阶段直接 550 拒收（无 catch-all）。
邮件保留 7 天（retention.email_ttl），后台每小时清理过期数据。

curl 示例

# 新增域名
curl -X POST https://mails.my.dhs.org/api/domains \
  -H "Authorization: Bearer $KEY" -d '{"domain":"mail.3823.net"}'

# 创建邮箱（不传 webhook 则用服务端默认）
curl -X POST https://mails.my.dhs.org/api/mailboxes \
  -H "Authorization: Bearer $KEY" -d '{"prefix":"verify"}'

# 查收到的邮件
curl -H "Authorization: Bearer $KEY" \
  https://mails.my.dhs.org/api/mailboxes/verify@mail.3823.net/emails