feat: add extensible mail flags

vitepress-docs/docs/zh/guide/feature/mail-api.md

@@ -19,6 +19,30 @@ res = requests.get(
 
 **注意**：`/api/mails` 按设计返回的是原始 RFC822 数据（如 `source`/`raw`），不保证直接包含 `subject`、`text`、`html` 等已解析字段。若要直接读取正文，请在客户端侧解析 `raw`（例如 `mail-parser-wasm`、`postal-mime`）。
 
+## 邮件 Flag API
+
+启用 `ENABLE_MAIL_FLAGS` 并完成数据库迁移后，邮件响应中的 `flags` 为整数位掩码。当前 bit 0 表示 `UNREAD`：值为 `1` 时未读，`NULL` 或 `0` 按已读处理。
+
+地址 JWT 使用 `PATCH /api/mails/flags` 批量增删状态位。每次最多传入 100 个邮件 ID；当前仅允许修改 `UNREAD` 位。
+
+```python
+requests.patch(
+    "https://<你的worker地址>/api/mails/flags",
+    headers={"Authorization": f"Bearer {你的JWT密码}"},
+    json={"ids": [1, 2], "add": 0, "remove": 1}
+)
+```
+
+用户 JWT 使用相同请求体访问 `PATCH /user_api/mails/flags`，只能修改该用户已绑定地址的邮件。服务端始终保留请求未涉及的其他 Flag 位。
+
+邮件列表接口支持通用 Flag 查询参数：`flag` 为 bit 位置（`0-30`），`flag_state` 为 `set` 或 `unset`。例如查询未读邮件：
+
+```text
+GET /api/mails?limit=20&offset=0&flag=0&flag_state=set
+```
+
+查询已读邮件则使用 `flag=0&flag_state=unset`。`/user_api/mails` 支持相同参数，后续自定义 Flag 可以直接使用 bit 10～19。
+
 ## admin 邮件 API
 
 支持 `address` 过滤

vitepress-docs/docs/zh/guide/worker-vars.md

@@ -97,6 +97,7 @@
 | `REMOVE_EXCEED_SIZE_ATTACHMENT` | 文本/JSON | 如果附件大小超过 2MB，则删除附件，邮件可能由于解析而丢失一些信息           | `true`                     |
 | `REMOVE_ALL_ATTACHMENT`         | 文本/JSON | 移除所有附件，邮件可能由于解析而丢失一些信息                               | `true`                     |
 | `ENABLE_MAIL_GZIP`             | 文本/JSON | 启用后新邮件将 Gzip 压缩存储到 `raw_blob` 字段，可节省 D1 数据库空间。已有明文 `raw` 数据自动兼容读取。**启用前请先执行数据库迁移（`Admin -> 快速设置 -> 数据库 -> 升级数据库 Schema` 或 `POST /admin/db_migration`），确保 `raw_blob` 列已创建。该功能会增加压缩/解压 CPU 开销，建议使用 Cloudflare Worker 付费 Plan 再开启。** | `true`                     |
+| `ENABLE_MAIL_FLAGS`            | 文本/JSON | 启用网页邮件状态功能。新邮件默认未读，支持打开自动已读、手动切换、按状态筛选及本页全部已读。历史邮件的 `NULL`/`0` 状态默认按已读处理。**启用前必须先执行数据库迁移，确保 `raw_mails.flags` 列已创建。** | `true`                     |
 | `CLEANUP_BATCH_SIZE`           | 数字      | 邮件、发件箱及按创建/活跃时间清理地址时的单次处理上限，默认 `3000`，有效范围 `1-5000`。较小值可降低单次 D1 压力，较大值可加快积压数据清理 | `3000` |
 
 > [!NOTE]