Cat MailsCat Mails API
Cat Mails 提供用于读取邮箱邮件的 API，支持 GET 与 POST 两种调用方式。
API 地址
https://mails.cat/api
所有 API 调用都通过这个入口。
---认证方式
API 使用 Token 进行认证。
Token 即用户 API Key。
Authorization: Bearer mk_xxxxx
---
获取邮件（GET 方式）
GET 模式是最简单的方式，通过 URL 参数调用。
GET /api?type=getmails&mail=demo@mails.cat&key=API_KEY
参数说明
| 参数 | 说明 |
|---|---|
| type | 固定值 getmails |
| 要查询的邮箱 | |
| key | 用户 API Key |
curl "https://mails.cat/api?type=getmails&mail=demo@mails.cat&key=mk_xxx"
返回
{
"success": true,
"count": 1,
"data": [
{
"id": 128,
"mail_from": "github@github.com",
"mail_to": "demo@mails.cat",
"subject": "GitHub login code",
"content": "Your code is 482913",
"received_at": "2026-03-18 12:10:00"
}
]
}
---
获取邮件（POST 方式）
POST 模式使用 Bearer Token 认证，不需要在 URL 传 key。
POST /api
Header
Authorization: Bearer mk_xxx
Body
mail=demo@mails.cat
示例
curl https://mails.cat/api \
-X POST \
-H "Authorization: Bearer mk_xxx" \
-d "mail=demo@mails.cat"
返回格式与 GET 完全相同。
---
获取 API Key 可访问邮箱
获取当前 API Key 允许访问的邮箱地址。
POST /api?action=mailboxes
示例
curl https://mails.cat/api?action=mailboxes \
-X POST \
-H "Authorization: Bearer mk_xxx"
返回
{
"success": true,
"address": "demo@mails.cat,hello@mails.cat"
}
---
创建临时邮箱
创建一个临时邮箱地址。该邮箱会自动绑定到当前 API Key 用户。
POST /api?action=create_temp_mailbox
示例
curl https://mails.cat/api?action=create_temp_mailbox \
-X POST \
-H "Authorization: Bearer mk_xxx"
返回
{
"success": true,
"mail": "tmpa83f29ab@temp.mails.cat"
}
说明
| 字段 | 说明 |
|---|---|
| 新创建的临时邮箱地址 |
临时邮箱会存储在系统 alias 表中，并标记为 is_temp = 1。
删除临时邮箱
删除一个临时邮箱地址。只允许删除通过 API 创建的临时邮箱。
POST /api?action=delete_temp_mailbox
参数
| 参数 | 说明 |
|---|---|
| 要删除的临时邮箱 |
curl https://mails.cat/api?action=delete_temp_mailbox \
-X POST \
-H "Authorization: Bearer mk_xxx" \
-d "mail=tmpa83f29ab@temp.mails.cat"
成功返回
{
"success": true,
"message": "Temp mailbox deleted"
}
删除失败
{
"success": false,
"error": "Cannot delete main mailbox or alias mailbox (only temp mailbox allowed)"
}
注意：
- 该接口只能删除临时邮箱
- 主邮箱无法通过 API 删除
- 普通 alias 邮箱也无法通过该接口删除
WebSocket 实时收件
Cat Mail 同时支持 WebSocket 实时收件。当新的邮件写入系统时，服务器会立即推送给客户端，无需轮询 API。
wss://websocket.mails.cat/?key=API_KEY
参数说明
| 参数 | 说明 |
|---|---|
| key | 用户 API Key |
| 可选，指定监听的邮箱，多个邮箱用逗号分隔 |
如果不提供 mail 参数，服务器会自动订阅该 API Key 允许访问的全部邮箱。
示例
const ws = new WebSocket(
"wss://websocket.mails.cat/?key=mk_xxx&mail=demo@mails.cat"
)
ws.onmessage = (e) => {
console.log("New mail:", e.data)
}
服务器推送示例
{
"from": "github@github.com",
"to": "demo@mails.cat",
"subject": "GitHub login code",
"content": "Your code is 482913",
"received_at": "2026-03-18 12:10:00"
}
每当有新邮件写入对应邮箱，服务器会立即推送该 JSON 数据。
---返回格式
成功
{
"success": true
}
错误
{
"success": false,
"error": "Invalid API key"
}
常见错误
| 错误 | 说明 |
|---|---|
| Missing key | 未提供 API key |
| Invalid key | API key 无效 |
| Missing mail | 未提供邮箱参数 |
| Mailbox scope is invalid | API key 无权限访问该邮箱 |