开发者文档 · MailEdge

接口参考

HTTP API

所有业务接口都需要登录会话；管理员接口还需要管理员权限。请求和响应使用 JSON，附件也支持通过 multipart/form-data 上传。

认证边界：API 不接受 Cloudflare API Token 作为 MailEdge 登录凭据。请先在已部署的 MailEdge 管理界面完成初始化和登录。

发信

发件地址必须是当前账户持有的信箱；正文为空会被拒绝。

POST /api/mail/send
Content-Type: application/json

{
  "from": "hello@example.com",
  "to": ["you@example.com"],
  "subject": "Hello MailEdge",
  "text": "邮件正文"
}

请求也支持 markdown 字段，服务端会生成邮件安全 HTML；附件可以使用 base64 内联，也可以通过 multipart 表单上传。

查询与统计

GET /api/mailboxes
GET /api/messages?mailboxId=...&limit=50
GET /api/stats?mailboxId=...

渠道管理

GET  /api/providers
POST /api/providers
POST /api/providers/:id/test
POST /api/providers/:id/default

分享与下载

GET    /api/attachments
POST   /api/attachments/stage
DELETE /api/attachments
GET    /api/shares
POST   /api/shares/:token/revoke
GET    /d/:token

大附件在发信时会自动生成对象存储分享链接；/api/attachments/stage 用于把已归档附件暂存到写信区，/d/:token 是公开下载地址。

扩展能力

Provider 扩展接口

SDK 状态：当前仓库没有独立的 npm、JavaScript/TypeScript 或 Python 客户端 SDK。下面的代码是 MailEdge Worker 内部的 TypeScript Provider 接口，用于维护者新增发信渠道，并不是可以直接安装的第三方 SDK。

内置实现包括 Cloudflare Email Service、Resend、Sendflare 和 SMTP，统一通过同一个 send() 方法发送邮件。外部应用目前应使用上方的 HTTP API，并通过 MailEdge 登录会话鉴权。

export type MailProviderType =
  | "cloudflare"
  | "resend"
  | "sendflare"
  | "smtp";

export interface MailProvider {
  readonly type: MailProviderType;
  send(input: SendMailInput): Promise<SendMailResult>;
}

要新增 SES、Mailgun 或 Postmark 等渠道，需要在源码 src/mail/providers/ 中实现该接口，并在 src/mail/factory.ts 注册配置分支。只有 transient 错误（网络故障、408、429、5xx 等）才会切换备用渠道或进入延迟重试；permanent 错误会立即失败，避免同一封邮件重复发送。

开发环境

本地开发

克隆仓库后安装依赖，并准备本地 Cloudflare 配置。生产数据和机密不会自动同步到本地环境。

npm install
cp .dev.vars.example .dev.vars
npx wrangler d1 migrations apply mailedge --local
npm run dev

npm run verify
# lint + typecheck + 全部测试（真实 workerd）

本地模拟 Email Routing 投递：

curl -X POST 'http://127.0.0.1:8787/cdn-cgi/handler/email?from=a@x.com&to=you@domain.com' \
  --data-binary @test.eml -H 'Content-Type: message/rfc822'