307 lines
8.6 KiB
Markdown
307 lines
8.6 KiB
Markdown
# 发送至未来功能 API 文档
|
||
|
||
## 概述
|
||
发送至未来功能允许用户将邮件设置为在未来特定时间自动发送，邮件状态将变为待投递(PENDING)，系统会在指定时间自动处理发送。
|
||
|
||
## API 接口
|
||
|
||
### 发送至未来
|
||
|
||
**接口地址：** `POST /api/v1/mails/send-to-future`
|
||
|
||
**接口描述：** 将草稿状态的邮件设置为在未来特定时间自动发送
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| mailId | string | 是 | 邮件ID |
|
||
| sendTime | string | 是 | 发送时间，ISO格式时间字符串（如：2025-12-31T23:59:59Z） |
|
||
| triggerType | string | 否 | 触发类型：TIME（时间）、LOCATION（地点）、EVENT（事件），默认为TIME |
|
||
| triggerCondition | object | 否 | 触发条件 |
|
||
| triggerCondition.location | object | 否 | 地点触发条件 |
|
||
| triggerCondition.location.latitude | number | 否 | 纬度 |
|
||
| triggerCondition.location.longitude | number | 否 | 经度 |
|
||
| triggerCondition.location.city | string | 否 | 城市 |
|
||
| triggerCondition.event | object | 否 | 事件触发条件 |
|
||
| triggerCondition.event.keywords | array | 否 | 关键词列表 |
|
||
| triggerCondition.event.type | string | 否 | 事件类型 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"mailId": "mail_1234567890",
|
||
"sendTime": "2025-12-31T23:59:59Z",
|
||
"triggerType": "TIME",
|
||
"triggerCondition": {}
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 响应状态码，200表示成功 |
|
||
| message | string | 响应消息 |
|
||
| data | object | 响应数据 |
|
||
| data.mailId | string | 邮件ID |
|
||
| data.capsuleId | string | 胶囊ID |
|
||
| data.status | string | 邮件状态：PENDING |
|
||
| data.sendTime | string | 发送时间 |
|
||
| data.countdown | number | 倒计时秒数 |
|
||
| data.updatedAt | string | 更新时间，ISO格式时间字符串 |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "mail_1234567890",
|
||
"capsuleId": "capsule_1234567890",
|
||
"status": "PENDING",
|
||
"sendTime": "2025-12-31T23:59:59Z",
|
||
"countdown": 94608000,
|
||
"updatedAt": "2023-07-20T10:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取待发送邮件列表
|
||
|
||
**接口地址：** `GET /api/v1/mails`
|
||
|
||
**接口描述：** 获取用户的待发送邮件列表
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| type | string | 否 | 邮件类型：INBOX、SENT、DRAFT，获取待发送时使用SENT |
|
||
| status | string | 否 | 状态筛选：PENDING、DELIVERING、DELIVERED、DRAFT，获取待发送时使用PENDING |
|
||
| page | number | 否 | 页码，默认为1 |
|
||
| size | number | 否 | 每页数量，默认为10 |
|
||
|
||
#### 请求示例
|
||
|
||
```
|
||
GET /api/v1/mails?type=SENT&status=PENDING&page=1&size=10
|
||
```
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 响应状态码，200表示成功 |
|
||
| message | string | 响应消息 |
|
||
| data | object | 响应数据 |
|
||
| data.list | array | 邮件列表 |
|
||
| data.list[].mailId | string | 邮件ID |
|
||
| data.list[].title | string | 邮件标题 |
|
||
| data.list[].sender | object | 发件人信息 |
|
||
| data.list[].recipient | object | 收件人信息 |
|
||
| data.list[].sendTime | string | 发送时间 |
|
||
| data.list[].deliveryTime | string | 送达时间 |
|
||
| data.list[].status | string | 邮件状态 |
|
||
| data.list[].hasAttachments | boolean | 是否有附件 |
|
||
| data.list[].isEncrypted | boolean | 是否加密 |
|
||
| data.list[].capsuleStyle | string | 胶囊样式 |
|
||
| data.list[].countdown | number | 倒计时秒数 |
|
||
| data.total | number | 总数量 |
|
||
| data.page | number | 当前页码 |
|
||
| data.size | number | 每页数量 |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"mailId": "mail_1234567890",
|
||
"title": "写给未来的自己",
|
||
"sender": {
|
||
"userId": "user_123",
|
||
"username": "张三",
|
||
"avatar": "https://example.com/avatar.jpg"
|
||
},
|
||
"recipient": {
|
||
"userId": "user_123",
|
||
"username": "张三",
|
||
"avatar": "https://example.com/avatar.jpg"
|
||
},
|
||
"sendTime": "2025-12-31T23:59:59Z",
|
||
"deliveryTime": null,
|
||
"status": "PENDING",
|
||
"hasAttachments": true,
|
||
"isEncrypted": false,
|
||
"capsuleStyle": "default",
|
||
"countdown": 94608000
|
||
}
|
||
],
|
||
"total": 1,
|
||
"page": 1,
|
||
"size": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取待发送邮件详情
|
||
|
||
**接口地址：** `GET /api/v1/mails/{mailId}`
|
||
|
||
**接口描述：** 获取指定待发送邮件的详细信息
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| mailId | string | 是 | 邮件ID |
|
||
|
||
#### 请求示例
|
||
|
||
```
|
||
GET /api/v1/mails/mail_1234567890
|
||
```
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 响应状态码，200表示成功 |
|
||
| message | string | 响应消息 |
|
||
| data | object | 响应数据 |
|
||
| data.mailId | string | 邮件ID |
|
||
| data.title | string | 邮件标题 |
|
||
| data.content | string | 邮件内容 |
|
||
| data.sender | object | 发件人信息 |
|
||
| data.recipient | object | 收件人信息 |
|
||
| data.sendTime | string | 发送时间 |
|
||
| data.createdAt | string | 创建时间 |
|
||
| data.deliveryTime | string | 送达时间 |
|
||
| data.status | string | 邮件状态 |
|
||
| data.triggerType | string | 触发类型 |
|
||
| data.triggerCondition | object | 触发条件 |
|
||
| data.attachments | array | 附件列表 |
|
||
| data.isEncrypted | boolean | 是否加密 |
|
||
| data.capsuleStyle | string | 胶囊样式 |
|
||
| data.canEdit | boolean | 是否可编辑（待发送状态为false） |
|
||
| data.canRevoke | boolean | 是否可撤销（待发送状态为true） |
|
||
| data.countdown | number | 倒计时秒数 |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "mail_1234567890",
|
||
"title": "写给未来的自己",
|
||
"content": "亲爱的未来的我，当你读到这封信时，希望你已经实现了现在的梦想...",
|
||
"sender": {
|
||
"userId": "user_123",
|
||
"username": "张三",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"email": "zhangsan@example.com"
|
||
},
|
||
"recipient": {
|
||
"userId": "user_123",
|
||
"username": "张三",
|
||
"avatar": "https://example.com/avatar.jpg",
|
||
"email": "zhangsan@example.com"
|
||
},
|
||
"sendTime": "2025-12-31T23:59:59Z",
|
||
"createdAt": "2023-07-20T10:30:00Z",
|
||
"deliveryTime": null,
|
||
"status": "PENDING",
|
||
"triggerType": "TIME",
|
||
"triggerCondition": {},
|
||
"attachments": [
|
||
{
|
||
"id": "attach_123",
|
||
"type": "IMAGE",
|
||
"url": "https://example.com/image.jpg",
|
||
"thumbnail": "https://example.com/thumb.jpg",
|
||
"size": 1024000
|
||
}
|
||
],
|
||
"isEncrypted": false,
|
||
"capsuleStyle": "default",
|
||
"canEdit": false,
|
||
"canRevoke": true,
|
||
"countdown": 94608000
|
||
}
|
||
}
|
||
```
|
||
|
||
### 撤销待发送邮件
|
||
|
||
**接口地址：** `POST /api/v1/mails/{mailId}/revoke`
|
||
|
||
**接口描述：** 撤销待发送的邮件，将状态改回草稿
|
||
|
||
#### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| mailId | string | 是 | 邮件ID（路径参数） |
|
||
|
||
#### 请求示例
|
||
|
||
```
|
||
POST /api/v1/mails/mail_1234567890/revoke
|
||
```
|
||
|
||
#### 响应参数
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| code | number | 响应状态码，200表示成功 |
|
||
| message | string | 响应消息 |
|
||
| data | object | 响应数据 |
|
||
| data.mailId | string | 邮件ID |
|
||
| data.status | string | 邮件状态：DRAFT |
|
||
| data.revokedAt | string | 撤销时间，ISO格式时间字符串 |
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"mailId": "mail_1234567890",
|
||
"status": "DRAFT",
|
||
"revokedAt": "2023-07-21T14:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未授权，需要登录 |
|
||
| 403 | 权限不足 |
|
||
| 404 | 资源不存在 |
|
||
| 422 | 验证失败 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
## 注意事项
|
||
|
||
1. 发送至未来的邮件状态为PENDING，表示等待系统在未来指定时间自动发送
|
||
2. 只有草稿状态(DRAFT)的邮件可以设置为发送至未来
|
||
3. 发送时间必须晚于当前时间至少1小时
|
||
4. 待发送状态的邮件不能编辑内容，但可以撤销发送
|
||
5. 撤销后的邮件状态将变回草稿(DRAFT)，可以重新编辑或设置发送时间
|
||
6. 系统会在发送时间到达前10分钟进入投递中状态(DELIVERING)
|
||
7. 免费用户每月最多可设置5封邮件发送至未来
|
||
8. 附件大小限制为10MB
|
||
9. 加密邮件需要额外验证才能查看内容 |