邮箱接码

misschat.chat · API

HTTP 接口文档

自建临时邮箱 API。随机创建邮箱无需密钥；按地址查询、列表与指定 local 创建在配置了 api_key 时需鉴权。

Base: /api JSON CORS *

鉴权说明

两种方式可并存，按接口要求选用。

方式用法
Bearer token 创建邮箱后返回的 token：Authorization: Bearer <token>
api_key 公网敏感操作：Header X-Api-Key，或 Query ?key=，或 Authorization: ApiKey <key>
Admin token 管理后台登录后获得：Header X-Admin-Token，或 Authorization: Admin <token> 
# 邮箱会话
Authorization: Bearer <mailbox_token>

# 按地址打开（需配置 api_key）
X-Api-Key: <your_api_key>

# 管理后台（密码登录后）
X-Admin-Token: <admin_token>
GET

/api/health

健康检查

无需鉴权。返回服务状态与域名信息。

curl http://127.0.0.1:8765/api/health

{
  "ok": true,
  "provider": "self-hosted",
  "domain": "misschat.chat",
  "smtp_port": 25
}
GET

/api/config

公开配置

无需鉴权。返回域名、SMTP 端口、是否 catch-all。

curl http://127.0.0.1:8765/api/config

{
  "domain": "misschat.chat",
  "smtp_port": 25,
  "catch_all": true
}
GET

/api/mailboxes

邮箱列表

需要 api_key（若已配置）。

参数说明
limit数量上限，默认 100，最大 500
tokens设为 1/true 时返回 token
 
curl -H "X-Api-Key: YOUR_KEY" \
  "http://127.0.0.1:8765/api/mailboxes?limit=50"
GET

/api/mailbox

打开 / 查询邮箱

用地址打开已有邮箱，或用 Bearer 查看当前会话邮箱。

参数说明
address / email / local完整地址或本地部分；按地址打开需 api_key
create默认 1；不存在时是否创建
Bearer不传 address 时，用 token 返回当前邮箱
 
# 按地址打开（需 api_key）
curl -H "X-Api-Key: YOUR_KEY" \
  "http://127.0.0.1:8765/api/mailbox?address=demo@misschat.chat"

# 用 token 查看
curl -H "Authorization: Bearer TOKEN" \
  http://127.0.0.1:8765/api/mailbox
POST

/api/mailbox

创建邮箱

随机创建可匿名；指定 local/address 需 api_key。

Body JSON说明
local可选，本地部分，如 demo
address / email可选，完整地址或本地部分
 
# 随机新建
curl -X POST http://127.0.0.1:8765/api/mailbox \
  -H "Content-Type: application/json" -d "{}"

{
  "id": "...",
  "address": "xxxx@misschat.chat",
  "token": "...",
  "reused": false
}

# 指定本地名（需 api_key）
curl -X POST http://127.0.0.1:8765/api/mailbox \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d "{\"local\":\"demo\"}"
GET

/api/messages

邮件列表

需要 Bearer token，或 address + api_key。

curl -H "Authorization: Bearer TOKEN" \
  http://127.0.0.1:8765/api/messages

# 或
curl -H "X-Api-Key: YOUR_KEY" \
  "http://127.0.0.1:8765/api/messages?address=demo@misschat.chat"
GET

/api/messages/<id>

邮件详情

需要 Bearer token，或 address + api_key。

curl -H "Authorization: Bearer TOKEN" \
  http://127.0.0.1:8765/api/messages/MSG_ID
GET

/api/code

提取最新验证码

需要 Bearer token，或 address + api_key。无验证码时返回 404。

参数说明
keyword可选，按关键词过滤邮件后再提取
 
curl -H "Authorization: Bearer TOKEN" \
  "http://127.0.0.1:8765/api/code?keyword=Cursor"
GET

/api/wait

长轮询等待验证码

需要 Bearer token，或 address + api_key。超时返回 408。

参数说明
timeout秒，默认 90
interval轮询间隔秒，默认 3
since / since_id只等此 ID 之后的新邮件
keyword可选关键词过滤
 
curl -H "Authorization: Bearer TOKEN" \
  "http://127.0.0.1:8765/api/wait?timeout=90&keyword=Cursor"
DELETE

/api/messages/<id>

删除邮件

需要 Bearer token，或 address + api_key。

curl -X DELETE \
  -H "Authorization: Bearer TOKEN" \
  http://127.0.0.1:8765/api/messages/MSG_ID

{ "ok": true }

管理后台 · 多域名

网页入口 /admin。密码为服务器 config.json 的 admin_password。添加域名后仍需自行配置 MX 指向本机。

方法路径说明
POST/api/admin/login{"password":"..."} → token
POST/api/admin/logout注销会话
GET/api/admin/domains域名列表
POST/api/admin/domains{"domain":"a.com","make_default":false}
POST/api/admin/domains/<name>/default设为默认域名
DELETE/api/admin/domains/<name>删除域名
 
# 登录
curl -X POST http://127.0.0.1:8765/api/admin/login \
  -H "Content-Type: application/json" \
  -d '{"password":"YOUR_ADMIN_PASSWORD"}'

# 添加域名
curl -X POST http://127.0.0.1:8765/api/admin/domains \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: TOKEN" \
  -d '{"domain":"mail.example.com"}'

# 创建邮箱时可指定域名
curl -X POST http://127.0.0.1:8765/api/mailbox \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

完整端点列表也可访问 GET /api/