/api/VMEmail_mailcx/domains
累计调用 73 次
获取可用域名列表
获取当前可用的全部后缀域名，用于生成邮箱时指定 domain。
邮箱服务
虚拟邮箱（临时邮箱）能力：随机生成一个邮箱地址并接收来信，常用于注册验证、接口联调与自动化测试。
/api/VMEmail_mailcx/
服务说明
邮箱服务提供虚拟邮箱（临时邮箱）能力：本地随机生成一个邮箱地址、无需注册，该地址即可接收来信，适合注册验证、接口联调、自动化测试等需要一次性邮箱的场合。（原「发送邮件」能力已并入消息推送服务：POST /api/push/email/send。）
本服务需项目签名调用。
临时邮箱的收件是长轮询：没有新邮件时请求会挂起约 25 秒后返回空列表，属正常行为，请不要按短超时判定为失败；邮件有留存期限，重要内容请及时取回。
响应格式
所有接口返回同一个 JSON 信封，业务数据都在 data 里：
{
"code": 10000,
"msg": "成功",
"data": { ... }
}
- code：业务状态码，10000 表示成功；其余为各类错误，完整清单见「错误码」页。
- msg：给人看的提示文案，可直接展示给终端用户，但不要用它做逻辑判断。
- data：业务数据；出错时通常为 null。各接口 data 的具体字段见该接口的「响应说明」。
判断成功与否请看 code，不要依赖 HTTP 状态码。 查看完整错误码
VMEmail(mail.cx)
VMEmail（mail.cx）临时邮箱（仅收信） 需签名mail.cx 临时邮箱：地址本地随机生成、无需注册，地址即唯一标识（邮件保留约 1 小时）；服务端不保存会话，查询邮件需回传 address。需项目签名调用。
/api/VMEmail_mailcx/generate
累计调用 147 次
生成临时邮箱
生成一个临时邮箱地址（仅收信），返回邮箱地址与客户端标识。
选填：指定后缀域名，缺省使用默认域名 uqu.me
选填：客户端标识（X-Client-ID）；不传由服务端随机生成，传已有值可复用同一身份
- 请求体为 application/x-www-form-urlencoded 表单。
响应说明
外层统一格式
| 字段 | 类型 | 说明 |
|---|---|---|
| address | string | 临时邮箱地址 |
| domain | string | 后缀域名 |
| client_id | string | 客户端标识，查询邮件时回传 |
返回示例
{"address": "[email protected]", "domain": "uqu.me", "client_id": "0f8b2e1c-3a4d-4f6e-9c12-7d5a8b3e2f01"}
/api/VMEmail_mailcx/emails
累计调用 1157 次
获取邮件列表
拉取指定邮箱的邮件摘要列表（长轮询，无新邮件时挂起约 25 秒后返回空列表）。
必填：邮箱地址，来自「生成临时邮箱」的返回值
选填：非负整数时间戳（秒）；不传返回当前全部邮件，传入后仅返回该时间之后的新邮件
选填：与生成邮箱时的 client_id 保持一致
- 上游为长轮询：无新邮件时会挂起约 25 秒后返回空列表，客户端 HTTP 超时应大于 35 秒。
- 完整正文用列表里的 id 查「获取邮件详情」。
响应说明
外层统一格式
data 为上游 mail.cx 的邮件摘要列表，每项含 id / from_name / from_email / subject / preview_text / preview_status / size / created_at 等字段，以实际返回为准。
/api/VMEmail_mailcx/email_detail
累计调用 67 次
获取邮件详情
按邮件 id 获取完整详情（含完整正文与附件）。
必填：邮件唯一标识（长度上限 128）
选填：与生成邮箱时的 client_id 保持一致
- 邮件不存在（或已过期，保留约 1 小时）返回 20030。
响应说明
外层统一格式
data 为上游 mail.cx 返回的邮件详情原始 JSON，含 id / from / from_email / from_name / to / subject / text_body / html_body / attachments / date / created_at 等字段，以实际返回为准。
邮箱服务 API 常见问题
临时邮箱 API 能做什么？
随机生成一个可用邮箱地址并接收来信，共 4 个端点：可用域名列表 domains、生成邮箱 generate、邮件列表 emails、邮件详情 email_detail。适合「注册验证、接口联调、自动化测试」这类临时需要收一封邮件的场景。
怎么用它自动接收注册验证码？
先调 generate 拿一个地址并提交给目标站，然后每 2~3 秒轮询 emails 看是否到信；命中后调 email_detail 取正文，从正文里提取验证码或激活链接。全程不需要邮件客户端，脚本里加个超时（例如 60 秒）避免死等。
生成的邮箱能长期使用吗？
不建议。它本质是上游临时邮箱线路（VMEmail / mail.cx）的会话邮箱，适合一次性任务；长期收信请用自己的正式邮箱。脚本里建议每次任务重新生成，避免多个任务串信。
可以指定邮箱域名吗？
可以，domains 返回当前可用域名列表，生成时从中选择；不传则使用线路默认域名。
邮箱服务接口怎么接入？需要签名吗？
邮箱服务挂在 /api/VMEmail_mailcx/ 前缀下：需签名的端点按 app_id + timestamp + nonce + sign（HMAC-SHA256，密钥为 APPSECRET）调用，开放端点直接请求即可。拿不准时用本页右侧的「在线调试」—— 它会代签并把你实际发出的请求与真实响应都回显出来。
邮箱服务的返回结构和错误码怎么看？
全部接口统一返回 {code, msg, data}：code=10000 表示成功，2xxxx 为业务错误，3xxxx / 4xxxx / 5xxxx 分别为外部依赖、客户端与系统错误。完整含义与处理建议见「错误码总表」（/docs/errors/）。