From c97a9a278b5a9afb5877f515161892d4ec72cc49 Mon Sep 17 00:00:00 2001 From: Dream Hunter Date: Thu, 26 Mar 2026 02:10:04 +0800 Subject: [PATCH] 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 --- CHANGELOG.md | 1 + CHANGELOG_EN.md | 1 + vitepress-docs/docs/.vitepress/en.ts | 12 +++++++++--- vitepress-docs/docs/.vitepress/zh.ts | 12 +++++++++--- vitepress-docs/docs/en/guide/feature/mail-api.md | 8 ++++++++ .../docs/en/guide/feature/new-address-api.md | 14 ++++++++++++++ vitepress-docs/docs/zh/guide/feature/mail-api.md | 8 ++++++++ .../docs/zh/guide/feature/new-address-api.md | 14 ++++++++++++++ 8 files changed, 64 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e24c7275..11979929 100644 --- 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 三个模板 diff --git a/CHANGELOG_EN.md b/CHANGELOG_EN.md index e19298b6..40e94de8 100644 --- 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 diff --git a/vitepress-docs/docs/.vitepress/en.ts b/vitepress-docs/docs/.vitepress/en.ts index 99a3c697..c36d2526 100644 --- 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, diff --git a/vitepress-docs/docs/.vitepress/zh.ts b/vitepress-docs/docs/.vitepress/zh.ts index fb018ba4..5048f0dd 100644 --- 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, diff --git a/vitepress-docs/docs/en/guide/feature/mail-api.md b/vitepress-docs/docs/en/guide/feature/mail-api.md index b20cc887..1e95ad02 100644 --- 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 ` to access `/api/*` endpoints +- User JWT uses `x-user-token: ` to access `/user_api/*` endpoints +::: + Supports `address` filter ```python diff --git a/vitepress-docs/docs/en/guide/feature/new-address-api.md b/vitepress-docs/docs/en/guide/feature/new-address-api.md index 147700ba..cfb89333 100644 --- 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 ` header + - Access `/api/*` endpoints (view mails, delete mails, etc.) + +- **User JWT**: Obtained via `/user_api/login` or `/user_api/register` + - Use `x-user-token: ` 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. diff --git a/vitepress-docs/docs/zh/guide/feature/mail-api.md b/vitepress-docs/docs/zh/guide/feature/mail-api.md index 88dd630a..7fe06ccf 100644 --- 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 ` 访问 `/api/*` 接口 +- 用户 JWT 使用 `x-user-token: ` 访问 `/user_api/*` 接口 +::: + 支持 `address` 过滤 ```python diff --git a/vitepress-docs/docs/zh/guide/feature/new-address-api.md b/vitepress-docs/docs/zh/guide/feature/new-address-api.md index 0efe3835..1fd03369 100644 --- 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 ` header + - 用于访问 `/api/*` 接口（查看邮件、删除邮件等） + +- **用户 JWT**：通过 `/user_api/login` 或 `/user_api/register` 获得 + - 使用 `x-user-token: ` header + - 用于访问 `/user_api/*` 接口（用户账户管理） + +**请勿混淆两种 JWT 的使用方式！** +::: + ## 通过 admin API 新建邮箱地址 这是一个 `python` 的例子，使用 `requests` 库发送邮件。