2026-03-28 上线更新与 API 兼容性说明
第一，最新版本已经正式上线，核心服务当前处于正常接流量状态。
第二，日志里看到的部分404 / 旧路径请求，不代表这次上线失败，更像是历史脚本、旧客户端或早期接入方仍在沿用旧接口习惯。
2026-03-28 上线更新与 API 兼容性说明
这次发布已经完成线上部署，API 与 Web 均已切到新版本。
如果你现在主要通过官方网页使用 YYDS Mail，这次上线本身不会带来额外操作负担；对大多数用户来说，服务已经处于正常可用状态。
如果你是开发者，或者你维护过基于 YYDS Mail 的旧脚本、旧 worker、旧内部工具，那么这篇说明更重要。当前线上日志里确实还能看到一些请求仍在访问历史路径，但这类现象和“本次部署失败”不是一回事，它更像是外部调用方还没有把接口使用习惯迁到当前公开 API 上。
一、当前线上状态
本次发布后，线上已经确认到以下事实：
- API 服务已完成更新，并通过健康检查
- Web 服务已完成更新，并在正常响应请求
- 核心服务已经在正常接流量
- 本次发布没有出现“容器起不来”“健康检查不过”“服务无法访问”这一类部署级故障
二、感知到什么
- API 邮箱的实时提醒链路做了补强，新邮箱纳入订阅和提醒的速度更快
- API 邮箱提醒现在支持静音，但未读 / 已读状态仍会保留，不会因为关掉弹窗就丢失状态
三、为什么日志里还会看到旧路径请求
本次上线后，日志里仍然能看到一些请求访问这类路径：
/v1/accounts/.../mails/v1/accounts/.../emails/v1/mails?...
这类请求的存在，本身并不说明本次发布失败。更合理的解释通常是：
- 某些已经在用的外部脚本还保留着旧版本的接口路径
- 早期接入过的客户端、worker 或内部工具没有一起升级
- 个别调用方曾经基于旧接口习惯做过本地封装，现在仍在沿用
四、旧路径和当前公开接口该怎么对应
当前公开 API 的消息读取能力已经收口到统一路径，不再建议继续使用早期的 mails / emails 这一套命名。
| 历史调用习惯 | 当前建议路径 | 说明 |
|---|---|---|
GET /v1/accounts/{id}/mails | GET /v1/messages?address=<邮箱地址> | 当前消息列表统一走 /v1/messages，JWT / API Key 需要显式传 address |
GET /v1/accounts/{id}/emails | GET /v1/messages?address=<邮箱地址> | emails 这套旧命名不再是当前公开集成面的一部分 |
GET /v1/mails?... | GET /v1/messages?... | 统一迁移到 messages 命名空间 |
这里有一个非常容易踩坑的点：
当前公开消息接口更强调“按邮箱地址定位消息”，而不是继续围绕旧的 mails 路径族做兼容包装。所以如果你的旧脚本只保存了 inbox ID，没有保存邮箱地址，那这条脚本本身也应该一起调整，而不是只改 URL 文本。
五、给已经在用的用户和接入方的建议
如果你维护过调用 YYDS Mail 的代码，建议尽快做一轮最小迁移：
- 检查是否还在使用
mails/emails相关旧路径 - 把消息查询统一迁到
/v1/messages - 对 JWT / API Key 调用，确认已经显式传入
address - 用当前公开文档重新对一次接口，而不是继续参考历史脚本注释或旧截图
如果你只是普通网页用户，不需要因为这条兼容性提示额外做什么。它主要影响的是历史接入代码，不影响官方网页本身的正常使用。
六、这次还需要特别说明的已知情况
为了避免误解，这里把“当前值得关注，但不应该被误判为上线失败”的几件事写清楚。
1. 接口文档才是当前公开集成面的准绳
如果你手里还有更早期的脚本、私下流转的示例片段、旧截图、历史 Postman 集合，优先级都应该低于当前公开文档。
建议直接以这两处为准：