feat: add extensible mail flags

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

@@ -19,6 +19,30 @@ res = requests.get(
 
 **Note**: `/api/mails` returns raw RFC822 data by design (for example `source`/`raw`), and it does not guarantee parsed fields such as `subject`, `text`, or `html`. Parse the raw source on the client side (for example with `mail-parser-wasm` or `postal-mime`) if you need readable message content.
 
+## Mail Flags API
+
+After enabling `ENABLE_MAIL_FLAGS` and running the database migration, each mail response includes an integer `flags` bitmask. Bit 0 currently means `UNREAD`: `1` is unread, while `NULL` or `0` is treated as read.
+
+With an Address JWT, use `PATCH /api/mails/flags` to add or remove flags for up to 100 mail IDs. Only the `UNREAD` bit is currently mutable.
+
+```python
+requests.patch(
+    "https://<your-worker-address>/api/mails/flags",
+    headers={"Authorization": f"Bearer {your-JWT-password}"},
+    json={"ids": [1, 2], "add": 0, "remove": 1}
+)
+```
+
+With a User JWT, send the same body to `PATCH /user_api/mails/flags`. Only mail belonging to addresses bound to that user can be changed. Other flag bits are always preserved.
+
+Mail-list endpoints accept generic flag filters: `flag` is the bit position (`0-30`), and `flag_state` is either `set` or `unset`. For example, list unread mail with:
+
+```text
+GET /api/mails?limit=20&offset=0&flag=0&flag_state=set
+```
+
+Use `flag=0&flag_state=unset` for read mail. `/user_api/mails` accepts the same parameters, and future custom flags can use bits 10 through 19 directly.
+
 ## Admin Mail API
 
 Supports `address` filter