docs: clarify Address JWT vs User JWT and reorganize API menu (#914)

- Add warning notes in new-address-api and mail-api docs - Explain the difference between Address JWT and User JWT - Create dedicated 'API Endpoints' section in sidebar - Update both zh and en documentation Refs #910
2026-05-07 06:12:50 +08:00 · 2026-03-26 02:10:04 +08:00
parent a45d01f9fd
commit c97a9a278b
8 changed files with 64 additions and 6 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,7 @@

 ### Docs

+- docs: |API| 新增地址 JWT 与用户 JWT 的区分说明，避免混淆两种认证方式；调整文档菜单结构，将 API 接口文档归类到独立分组（#910）
 - docs: |Telegram| 新增每用户邮件推送和全局推送功能说明文档（#769）
 - docs: |Webhook| 新增 Telegram Bot、企业微信、Discord 等常用推送平台的 Webhook 模板示例
 - feat: |Webhook| 前端预设模板新增 Telegram Bot、企业微信、Discord 三个模板
--- a/CHANGELOG_EN.md
+++ b/CHANGELOG_EN.md
@@ -27,6 +27,7 @@

 ### Docs

+- docs: |API| Add clarification between Address JWT and User JWT to avoid confusion; reorganize documentation menu structure with dedicated API Endpoints section (#910)
 - docs: |Telegram| Add per-user mail push and global push documentation (#769)
 - docs: |Webhook| Add webhook template examples for Telegram Bot, WeChat Work, Discord and other common push platforms
 - feat: |Webhook| Add Telegram Bot, WeChat Work, Discord preset templates to frontend webhook settings
--- a/vitepress-docs/docs/.vitepress/en.ts
+++ b/vitepress-docs/docs/.vitepress/en.ts
@@ -149,19 +149,25 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
            items: [
                { text: 'AI Email Recognition', link: 'feature/ai-extract' },
                { text: 'Configure SMTP IMAP Proxy', link: 'feature/config-smtp-proxy' },
-                { text: 'Send Email API', link: 'feature/send-mail-api' },
-                { text: 'View Email API', link: 'feature/mail-api' },
                { text: 'Configure Subdomain Email', link: 'feature/subdomain' },
                { text: 'Configure Telegram Bot', link: 'feature/telegram' },
                { text: 'Configure S3 Attachments', link: 'feature/s3-attachment' },
                { text: 'Configure WASM Email Parser', link: 'feature/mail_parser_wasm_worker' },
                { text: 'Configure Webhook', link: 'feature/webhook' },
-                { text: 'New Address API', link: 'feature/new-address-api' },
                { text: 'OAuth2 Third-party Login', link: 'feature/user-oauth2' },
                { text: 'Enhance with Other Workers', link: 'feature/another-worker-enhanced' },
                { text: 'Add Google Ads', link: 'feature/google-ads.md' },
            ]
        },
+        {
+            text: 'API Endpoints',
+            collapsed: false,
+            items: [
+                { text: 'New Address API', link: 'feature/new-address-api' },
+                { text: 'View Email API', link: 'feature/mail-api' },
+                { text: 'Send Email API', link: 'feature/send-mail-api' },
+            ]
+        },
        {
            text: 'Feature Overview',
            collapsed: false,
--- a/vitepress-docs/docs/.vitepress/zh.ts
+++ b/vitepress-docs/docs/.vitepress/zh.ts
@@ -149,19 +149,25 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
            items: [
                { text: 'AI 邮件识别', link: 'feature/ai-extract' },
                { text: '配置 SMTP IMAP 代理服务', link: 'feature/config-smtp-proxy' },
-                { text: '发送邮件 API', link: 'feature/send-mail-api' },
-                { text: '查看邮件 API', link: 'feature/mail-api' },
                { text: '配置子域名邮箱', link: 'feature/subdomain' },
                { text: '配置 Telegram Bot', link: 'feature/telegram' },
                { text: '配置 S3 附件', link: 'feature/s3-attachment' },
                { text: '配置 worker 使用 wasm 解析邮件', link: 'feature/mail_parser_wasm_worker' },
                { text: '配置 webhook', link: 'feature/webhook' },
-                { text: '新建邮箱地址 API', link: 'feature/new-address-api' },
                { text: 'Oauth2 第三方登录', link: 'feature/user-oauth2' },
                { text: '配置其他worker增强', link: 'feature/another-worker-enhanced' },
                { text: '给网页增加 Google Ads', link: 'feature/google-ads.md' },
            ]
        },
+        {
+            text: 'API 接口',
+            collapsed: false,
+            items: [
+                { text: '新建邮箱地址 API', link: 'feature/new-address-api' },
+                { text: '查看邮件 API', link: 'feature/mail-api' },
+                { text: '发送邮件 API', link: 'feature/send-mail-api' },
+            ]
+        },
        {
            text: '功能简介',
            collapsed: false,
--- a/vitepress-docs/docs/en/guide/feature/mail-api.md
+++ b/vitepress-docs/docs/en/guide/feature/mail-api.md
@@ -131,6 +131,14 @@ print(response.json())

 ## User Mail API

+::: warning Note: User JWT vs Address JWT
+This endpoint uses **User JWT** (obtained via `/user_api/login` or `/user_api/register`), with `x-user-token` header.
+
+**Do not confuse with Address JWT**:
+- Address JWT uses `Authorization: Bearer <jwt>` to access `/api/*` endpoints
+- User JWT uses `x-user-token: <jwt>` to access `/user_api/*` endpoints
+:::
+
 Supports `address` filter

 ```python
--- a/vitepress-docs/docs/en/guide/feature/new-address-api.md
+++ b/vitepress-docs/docs/en/guide/feature/new-address-api.md
@@ -1,5 +1,19 @@
 # Create New Email Address API

+::: warning Note: Address JWT vs User JWT
+This page describes **Address JWT**, which is different from **User JWT**:
+
+- **Address JWT**: Returned when creating a mailbox via `/api/new_address` or `/admin/new_address`
+  - Use `Authorization: Bearer <jwt>` header
+  - Access `/api/*` endpoints (view mails, delete mails, etc.)
+
+- **User JWT**: Obtained via `/user_api/login` or `/user_api/register`
+  - Use `x-user-token: <jwt>` header
+  - Access `/user_api/*` endpoints (user account management)
+
+**Do not confuse these two JWT types!**
+:::
+
 ## Create Email Address via Admin API

 This is a `python` example using the `requests` library to send emails.
--- a/vitepress-docs/docs/zh/guide/feature/mail-api.md
+++ b/vitepress-docs/docs/zh/guide/feature/mail-api.md
@@ -131,6 +131,14 @@ print(response.json())

 ## user 邮件 API

+::: warning 注意：用户 JWT vs 地址 JWT
+此接口使用**用户 JWT**（通过 `/user_api/login` 或 `/user_api/register` 获得），使用 `x-user-token` header。
+
+**请勿与地址 JWT 混淆**：
+- 地址 JWT 使用 `Authorization: Bearer <jwt>` 访问 `/api/*` 接口
+- 用户 JWT 使用 `x-user-token: <jwt>` 访问 `/user_api/*` 接口
+:::
+
 支持 `address` 过滤

 ```python
--- a/vitepress-docs/docs/zh/guide/feature/new-address-api.md
+++ b/vitepress-docs/docs/zh/guide/feature/new-address-api.md
@@ -1,5 +1,19 @@
 # 新建邮箱地址 API

+::: warning 注意：地址 JWT vs 用户 JWT
+本页面介绍的是**地址 JWT**，与**用户 JWT** 是两种不同的认证方式：
+
+- **地址 JWT**：通过 `/api/new_address` 或 `/admin/new_address` 创建邮箱时返回
+  - 使用 `Authorization: Bearer <jwt>` header
+  - 用于访问 `/api/*` 接口（查看邮件、删除邮件等）
+
+- **用户 JWT**：通过 `/user_api/login` 或 `/user_api/register` 获得
+  - 使用 `x-user-token: <jwt>` header
+  - 用于访问 `/user_api/*` 接口（用户账户管理）
+
+**请勿混淆两种 JWT 的使用方式！**
+:::
+
 ## 通过 admin API 新建邮箱地址

 这是一个 `python` 的例子，使用 `requests` 库发送邮件。