feat(sharing): add email and message sharing functionality

2026-06-02 22:20:14 +08:00 · 2025-10-18 20:08:42 +08:00
parent 47d555eaf5
commit dbe8c42b11
45 changed files with 5669 additions and 38 deletions
--- a/README.md
+++ b/README.md
@@ -566,6 +566,159 @@ GET /api/emails/{emailId}/{messageId}
 - `html`: 邮件HTML内容
 - `received_at`: 接收时间（时间戳）

+#### 创建邮箱分享链接
+```http
+POST /api/emails/{emailId}/share
+Content-Type: application/json
+
+{
+  "expiresIn": 86400000
+}
+```
+参数说明：
+- `emailId`: 邮箱的唯一标识符，必填
+- `expiresIn`: 分享链接有效期（毫秒），0 表示永久有效，可选
+
+返回响应：
+```json
+{
+  "id": "share-uuid-123",
+  "emailId": "email-uuid-123",
+  "token": "abc123def456",
+  "expiresAt": "2024-01-02T12:00:00.000Z",
+  "createdAt": "2024-01-01T12:00:00.000Z"
+}
+```
+响应字段说明：
+- `id`: 分享记录的唯一标识符
+- `emailId`: 关联的邮箱 ID
+- `token`: 分享链接的访问令牌
+- `expiresAt`: 分享链接过期时间，null 表示永久有效
+- `createdAt`: 创建时间
+
+分享链接访问地址：`https://your-domain.com/shared/{token}`
+
+#### 获取邮箱的所有分享链接
+```http
+GET /api/emails/{emailId}/share
+```
+参数说明：
+- `emailId`: 邮箱的唯一标识符，必填
+
+返回响应：
+```json
+{
+  "shares": [
+    {
+      "id": "share-uuid-123",
+      "emailId": "email-uuid-123",
+      "token": "abc123def456",
+      "expiresAt": "2024-01-02T12:00:00.000Z",
+      "createdAt": "2024-01-01T12:00:00.000Z"
+    }
+  ],
+  "total": 1
+}
+```
+响应字段说明：
+- `shares`: 分享链接列表数组
+- `total`: 分享链接总数
+
+#### 删除邮箱分享链接
+```http
+DELETE /api/emails/{emailId}/share/{shareId}
+```
+参数说明：
+- `emailId`: 邮箱的唯一标识符，必填
+- `shareId`: 分享记录的唯一标识符，必填
+
+返回响应：
+```json
+{
+  "success": true
+}
+```
+响应字段说明：
+- `success`: 删除操作是否成功
+
+#### 创建邮件分享链接
+```http
+POST /api/emails/{emailId}/messages/{messageId}/share
+Content-Type: application/json
+
+{
+  "expiresIn": 86400000
+}
+```
+参数说明：
+- `emailId`: 邮箱的唯一标识符，必填
+- `messageId`: 邮件的唯一标识符，必填
+- `expiresIn`: 分享链接有效期（毫秒），0 表示永久有效，可选
+
+返回响应：
+```json
+{
+  "id": "share-uuid-456",
+  "messageId": "message-uuid-789",
+  "token": "xyz789ghi012",
+  "expiresAt": "2024-01-02T12:00:00.000Z",
+  "createdAt": "2024-01-01T12:00:00.000Z"
+}
+```
+响应字段说明：
+- `id`: 分享记录的唯一标识符
+- `messageId`: 关联的邮件 ID
+- `token`: 分享链接的访问令牌
+- `expiresAt`: 分享链接过期时间，null 表示永久有效
+- `createdAt`: 创建时间
+
+分享链接访问地址：`https://your-domain.com/shared/message/{token}`
+
+#### 获取邮件的所有分享链接
+```http
+GET /api/emails/{emailId}/messages/{messageId}/share
+```
+参数说明：
+- `emailId`: 邮箱的唯一标识符，必填
+- `messageId`: 邮件的唯一标识符，必填
+
+返回响应：
+```json
+{
+  "shares": [
+    {
+      "id": "share-uuid-456",
+      "messageId": "message-uuid-789",
+      "token": "xyz789ghi012",
+      "expiresAt": "2024-01-02T12:00:00.000Z",
+      "createdAt": "2024-01-01T12:00:00.000Z"
+    }
+  ],
+  "total": 1
+}
+```
+响应字段说明：
+- `shares`: 分享链接列表数组
+- `total`: 分享链接总数
+
+#### 删除邮件分享链接
+```http
+DELETE /api/emails/{emailId}/messages/{messageId}/share/{shareId}
+```
+参数说明：
+- `emailId`: 邮箱的唯一标识符，必填
+- `messageId`: 邮件的唯一标识符，必填
+- `shareId`: 分享记录的唯一标识符，必填
+
+返回响应：
+```json
+{
+  "success": true
+}
+```
+响应字段说明：
+- `success`: 删除操作是否成功
+
 ### 使用示例

 使用 curl 创建临时邮箱：
@@ -590,6 +743,32 @@ const res = await fetch('https://your-domain.com/api/emails/your-email-id', {
 const data = await res.json();
 ```

+使用 curl 创建邮箱分享链接：
+```bash
+curl -X POST https://your-domain.com/api/emails/your-email-id/share \
+  -H "X-API-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "expiresIn": 86400000
+  }'
+```
+
+使用 JavaScript 创建邮件分享链接：
+```javascript
+const res = await fetch('https://your-domain.com/api/emails/your-email-id/messages/your-message-id/share', {
+  method: 'POST',
+  headers: {
+    'X-API-Key': 'YOUR_API_KEY',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    expiresIn: 0  // 永久有效
+  })
+});
+const data = await res.json();
+console.log('分享链接:', `https://your-domain.com/shared/message/${data.token}`);
+```
+
 ## 环境变量

 本项目使用以下环境变量：