# 发送至未来功能 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. 加密邮件需要额外验证才能查看内容