REST API 文档

GET/api/email/{domain}/{user}/

获取用户电子邮件的分页列表。列表响应仅包含元数据（无 body / html_body).

范围	地点	描述
domain	小路	电子邮件域名，例如 example.com
user	小路	用户名，例如 testuser
page	查询，可选	页码（默认1）
limit	查询，可选	每页项目数（默认 20 个，最多 100 个）

curl -X GET "https://BASE_URL/api/email/example.com/testuser/?page=1&limit=20"

{
  "emails": [
    {
      "id": 123,
      "subject": "Welcome",
      "sender": "[email protected]",
      "date": "2026-09-30T10:30:00.000Z",
      "has_attachments": false,
      "size": 1234
    }
  ],
  "total": 5,
  "page": 1,
  "limit": 20,
  "has_more": false
}

GET/api/email/{domain}/{user}/{email_id}

获取电子邮件的完整详细信息。

curl -X GET "https://BASE_URL/api/email/example.com/testuser/123"

DELETE/api/email/{domain}/{user}/{email_id}

删除特定电子邮件。

curl -X DELETE "https://BASE_URL/api/email/example.com/testuser/123"

{ "status": "deleted" }

POST/api/add-domain/{domain}

添加新域或更新现有域的在线状态。该域必须有一条 MX 记录指向要接受的系统主机名（状态 added, is_online: true).

curl -X POST "https://BASE_URL/api/add-domain/newdomain.com"

// 添加成功
{ "status": "added", "domain": "newdomain.com", "is_online": true }

// 现有域：更新其状态
{ "status": "updated", "domain": "newdomain.com", "is_online": false }

GET/api/all-domains/ & /api/random-domains/

所有在线域（私有，需要令牌）：

curl -X GET "https://BASE_URL/api/all-domains/" \
  -H "X-Domain-Token: YOUR_TOKEN"

随机在线域（公共）：

curl -X GET "https://BASE_URL/api/random-domains/?limit=10"

{ "domains": ["domain1.com", "domain2.com"], "total": 2 }

GET/api/check-mx/{domain}

检查域是否有指向系统的有效 MX 记录。

curl -X GET "https://BASE_URL/api/check-mx/example.com"

{ "result": "online" }   // 或者 "offline"

错误处理

代码	意义
200	成功
400	无效请求（例如格式错误的域名/电子邮件）
401	专用端点的令牌丢失或无效
404	未找到电子邮件
429	超出速率限制

{ "detail": "Domain not found" }

重要提示

• 电子邮件地址必须使用以下格式 [email protected]
• 只有具有有效 MX 记录的域才具有“在线”状态
• 电子邮件和非活动域将在之后自动删除 3天
• 仅限服务 收到 电子邮件 — 不支持发送和 SMTP 中继
• API 应用每个 IP 的速率限制
• 3天的保留期适用于直播服务；备份可能会保留更长时间的副本。此时不保证从所有副本中永久删除。
• 自定义域收件箱保持公开状态，可能会被第三方服务阻止。不保证验收和交付。