临时邮箱 API 接口文档

概览

Temp Mail 提供公共临时邮箱的生成、邮件查询、状态检查、续期和删除能力。

服务域名：mail.tempbox.cn
当前 HTTP 基础地址：http://mail.tempbox.cn
推荐 HTTPS 基础地址：https://mail.tempbox.cn
API 前缀：/api
请求与响应格式：application/json
普通临时邮箱默认有效期：10 分钟
普通临时邮箱到期后默认保留 24 小时 用于续期，保留窗口由 TEMP_MAIL_RENEW_GRACE_MINUTES 控制

生成临时邮箱

http

GET /api/generate
GET /api/generate?prefix={prefix}

业务说明

用于创建一个新的临时邮箱，邮箱域名固定为 mail.tempbox.cn。
不传 prefix 或传入空白 prefix 时，服务端随机生成 8 位邮箱前缀。
传入合法 prefix 时，生成邮箱地址为 {prefix}@mail.tempbox.cn。
如果同一个自定义前缀对应的邮箱已经存在，本接口会刷新该邮箱的创建时间，相当于重新开始 10 分钟有效期。
创建邮箱时会触发过期清理：超过有效期且超过可续期保留窗口的旧邮箱会被清理。

Query 参数

参数	类型	必填	说明
`prefix`	string	否	自定义邮箱前缀，最长 50 个字符，只能包含字母、数字、下划线和中划线；必须作为单个 `prefix` 参数传入。留空时自动生成随机邮箱。

成功响应

json

{
  "email": "example@mail.tempbox.cn",
  "created_at": 1781250185,
  "expires_in": 600
}

字段说明

字段	类型	说明
`email`	string	生成的临时邮箱地址。
`created_at`	integer	邮箱创建/刷新时间，Unix 秒级时间戳。
`expires_in`	integer	剩余有效期，单位秒。普通临时邮箱默认返回 `600`。

错误响应

以下情况会返回 422，响应内容为 请重新使用别的自定义前缀。：

自定义前缀包含非法字符，例如 @、空格、中文等。
自定义前缀超过长度限制。
同一请求重复传入多个 prefix 参数。
自定义前缀包含受限内容。
自定义前缀对应服务保留邮箱。

json

{
  "detail": "请重新使用别的自定义前缀。"
}

以下情况会返回 429：同一 IP 在 60 秒内创建邮箱超过 10 次。

json

{
  "detail": "Too many requests. Please try again later."
}

查询邮箱邮件

http

GET /api/messages/{email}

业务说明

用于查询指定邮箱已经收到的邮件列表。
邮件按 received_at 倒序返回，最新邮件在前。
如果邮箱仍在有效期内，会返回当前已入库的邮件。
如果邮箱已经到期但仍在可续期保留窗口内，接口仍可返回该邮箱历史邮件，但该邮箱在续期前不会继续接收新邮件。
如果邮箱不存在，或已超过可续期保留窗口被清理，返回空数组 []，不会返回 404。
每个邮箱最多保留 TEMP_MAIL_MAX_MESSAGES 条邮件，超过后会删除最早的邮件。

Path 参数

参数	类型	必填	说明
`email`	string	是	完整邮箱地址，需要 URL encode，例如 `test123%40mail.tempbox.cn`。

成功响应

json

[
  {
    "id": "message-id",
    "from_addr": "sender@example.com",
    "subject": "验证码",
    "content": "您的验证码是 123456",
    "received_at": 1781250185,
    "content_is_html": false,
    "content_html": null
  }
]

没有邮件、邮箱不存在、或邮箱已被清理时返回空数组：

json

[]

字段说明

字段	类型	说明
`id`	string	邮件 ID。
`from_addr`	string	发件人地址。
`subject`	string	邮件主题。
`content`	string	邮件正文文本。
`received_at`	integer	收件时间，Unix 秒级时间戳。
`content_is_html`	boolean	邮件正文是否包含可安全展示的 HTML。
`content_html`	string/null	经过服务端过滤后的 HTML 内容；普通文本邮件为 `null`。

错误响应

本接口对“邮箱不存在”“邮箱已过期”“没有邮件”都返回 200 和空数组，不使用业务错误响应。只有请求方法不正确、路径不匹配或服务端异常时，才会由 Web 框架返回通用错误。

检查邮箱状态

http

GET /api/check/{email}

业务说明

用于判断指定邮箱当前是否处于可接收邮件的有效期内。
普通邮箱未过期时返回 valid: true 和剩余秒数。
普通邮箱刚到期但仍在可续期保留窗口内时返回 valid: false，expires_in: 0；这种邮箱仍可调用续期接口恢复使用。
邮箱不存在，或已超过可续期保留窗口被清理时，也返回 valid: false，expires_in: 0。

Path 参数

参数	类型	必填	说明
`email`	string	是	完整邮箱地址，需要 URL encode，例如 `test123%40mail.tempbox.cn`。

成功响应：邮箱有效

json

{
  "valid": true,
  "expires_in": 480
}

成功响应：邮箱不存在、已过期或已被清理

json

{
  "valid": false,
  "expires_in": 0
}

字段说明

字段	类型	说明
`valid`	boolean	邮箱当前是否有效。只有仍可接收新邮件时为 `true`。
`expires_in`	integer	剩余有效期，单位秒；普通邮箱无效时为 `0`。

错误响应

本接口对“邮箱不存在”“邮箱已过期”“邮箱已被清理”都返回 200，通过 valid: false 表示状态，不使用业务错误响应。只有请求方法不正确、路径不匹配或服务端异常时，才会由 Web 框架返回通用错误。

续期邮箱

http

POST /api/extend/{email}

业务说明

用于把指定邮箱恢复为新的 10 分钟有效期。
普通邮箱未过期时也可以调用续期，调用后有效期从当前时间重新计算。
普通邮箱到期后会停止接收新邮件，但只要仍在可续期保留窗口内，就可以调用本接口恢复使用。
当前默认可续期保留窗口是 1440 分钟（24 小时），由 TEMP_MAIL_RENEW_GRACE_MINUTES 控制。
续期成功后会把邮箱的创建/刷新时间更新为当前时间，并返回新的剩余有效期。

可续期条件

满足以下任一条件时可以续期：

邮箱是仍存在于系统中的普通临时邮箱，且未超过可续期保留窗口。

以下情况不能续期：

邮箱从未创建过。
邮箱已被用户删除。
邮箱已超过有效期加可续期保留窗口，并被清理任务删除。

Path 参数

参数	类型	必填	说明
`email`	string	是	完整邮箱地址，需要 URL encode，例如 `test123%40mail.tempbox.cn`。

成功响应

json

{
  "status": "ok",
  "expires_in": 600
}

错误响应

以下情况会返回 404：邮箱不存在、已被删除，或已超过可续期保留窗口被清理。

json

{
  "detail": "Mailbox not found or expired"
}

注：错误响应中的 expired 表示邮箱已超过可续期保留窗口并被清理；刚到期但仍在保留窗口内的邮箱可以续期。

删除邮箱

http

DELETE /api/delete/{email}

业务说明

用于提前结束指定普通临时邮箱。
删除成功后，该邮箱和关联邮件会被删除，之后不能再查询邮件、接收邮件或续期。
普通邮箱未过期时可以删除。
普通邮箱已过期但仍在可续期保留窗口内时也可以删除。

Path 参数

参数	类型	必填	说明
`email`	string	是	完整邮箱地址，需要 URL encode，例如 `test123%40mail.tempbox.cn`。

成功响应

json

{
  "status": "ok",
  "message": "Mailbox deleted"
}

错误响应

以下情况会返回 404：邮箱不存在、已被删除，或已超过可续期保留窗口被清理。

json

{
  "detail": "Mailbox not found"
}

调用示例

生成随机邮箱

bash

curl "http://mail.tempbox.cn/api/generate"

生成自定义前缀邮箱

bash

curl "http://mail.tempbox.cn/api/generate?prefix=test123"

查询邮件

bash

curl "http://mail.tempbox.cn/api/messages/test123%40mail.tempbox.cn"

检查状态

bash

curl "http://mail.tempbox.cn/api/check/test123%40mail.tempbox.cn"

续期邮箱

bash

curl -X POST "http://mail.tempbox.cn/api/extend/test123%40mail.tempbox.cn"

删除邮箱

bash

curl -X DELETE "http://mail.tempbox.cn/api/delete/test123%40mail.tempbox.cn"

注意事项

普通临时邮箱默认有效期为 10 分钟。
普通临时邮箱到期后停止接收新邮件，但在可续期保留窗口内仍可续期。
超过有效期和可续期保留窗口后，邮箱及相关邮件会被清理。
查询、检查、续期、删除接口中的邮箱地址需要 URL encode。
GET /api/messages/{email} 和 GET /api/check/{email} 不用 404 表示邮箱不存在；请分别根据空数组和 valid: false 判断业务状态。
如果用于正式项目，建议使用 HTTPS 地址。