From 53c35062c86811e1e1e495851a97e131e3537bd5 Mon Sep 17 00:00:00 2001
From: Dream Hunter <dreamhunter2333@gmail.com>
Date: Sat, 4 Apr 2026 18:33:56 +0800
Subject: [PATCH] docs: add delete-address api docs (#936)

---
 vitepress-docs/docs/.vitepress/en.ts          |  1 +
 vitepress-docs/docs/.vitepress/zh.ts          |  1 +
 .../docs/en/guide/feature/delete-address.md   | 42 +++++++++++++++++++
 .../docs/zh/guide/feature/delete-address.md   | 42 +++++++++++++++++++
 4 files changed, 86 insertions(+)
 create mode 100644 vitepress-docs/docs/en/guide/feature/delete-address.md
 create mode 100644 vitepress-docs/docs/zh/guide/feature/delete-address.md

diff --git a/vitepress-docs/docs/.vitepress/en.ts b/vitepress-docs/docs/.vitepress/en.ts
index c36d2526..1fe1f842 100644
--- a/vitepress-docs/docs/.vitepress/en.ts
+++ b/vitepress-docs/docs/.vitepress/en.ts
@@ -166,6 +166,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
                 { 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: 'Delete Address API', link: 'feature/delete-address' },
             ]
         },
         {
diff --git a/vitepress-docs/docs/.vitepress/zh.ts b/vitepress-docs/docs/.vitepress/zh.ts
index 5048f0dd..7df7a648 100644
--- a/vitepress-docs/docs/.vitepress/zh.ts
+++ b/vitepress-docs/docs/.vitepress/zh.ts
@@ -166,6 +166,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
                 { text: '新建邮箱地址 API', link: 'feature/new-address-api' },
                 { text: '查看邮件 API', link: 'feature/mail-api' },
                 { text: '发送邮件 API', link: 'feature/send-mail-api' },
+                { text: '删除邮箱地址 API', link: 'feature/delete-address' },
             ]
         },
         {
diff --git a/vitepress-docs/docs/en/guide/feature/delete-address.md b/vitepress-docs/docs/en/guide/feature/delete-address.md
new file mode 100644
index 00000000..92fc90ee
--- /dev/null
+++ b/vitepress-docs/docs/en/guide/feature/delete-address.md
@@ -0,0 +1,42 @@
+# Delete Address API
+
+## Admin Delete Address API
+
+Delete an address by address ID. This endpoint requires admin auth and deletes related data (mails, sender settings, bindings, etc.).
+
+```bash
+DELETE /admin/delete_address/:id
+```
+
+Header:
+
+- `x-admin-auth: <admin_password>`
+
+Example response:
+
+```json
+{ "success": true }
+```
+
+## User Delete Address API
+
+Delete mailbox by address JWT. The request needs address token permission and deletes related data (received mails, sent items, auto reply data, sender bindings, user bindings, telegram bind records).
+
+```bash
+DELETE /api/delete_address
+```
+
+Headers:
+
+- `Authorization: Bearer <address_jwt>`
+
+Notes:
+
+- `ENABLE_USER_DELETE_EMAIL` must be enabled.
+- Address credential can be obtained from `/api/new_address` or `/admin/new_address`.
+
+Example response:
+
+```json
+{ "success": true }
+```
diff --git a/vitepress-docs/docs/zh/guide/feature/delete-address.md b/vitepress-docs/docs/zh/guide/feature/delete-address.md
new file mode 100644
index 00000000..52468762
--- /dev/null
+++ b/vitepress-docs/docs/zh/guide/feature/delete-address.md
@@ -0,0 +1,42 @@
+# 删除邮箱地址 API
+
+## 管理员删除地址 API
+
+使用地址 ID 删除邮箱地址。该接口需要管理员鉴权，并会同时清理关联数据（收件、发件来源授权、用户绑定等）。
+
+```bash
+DELETE /admin/delete_address/:id
+```
+
+请求头：
+
+- `x-admin-auth: <admin_password>`
+
+返回示例：
+
+```json
+{ "success": true }
+```
+
+## 普通地址删除 API
+
+使用地址 JWT 删除当前邮箱。该接口会清理关联数据（收件、发件、自动回复、sender 绑定、用户绑定、Telegram 绑定等）。
+
+```bash
+DELETE /api/delete_address
+```
+
+请求头：
+
+- `Authorization: Bearer <address_jwt>`
+
+说明：
+
+- 需开启 `ENABLE_USER_DELETE_EMAIL = true`
+- 地址凭证来自 `/api/new_address` 或 `/admin/new_address`
+
+返回示例：
+
+```json
+{ "success": true }
+```