emall-api/.trae/rules/seed.md

发送至未来功能 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	否	事件类型

请求示例

{
  "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格式时间字符串

响应示例

{
  "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	每页数量

响应示例

{
  "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	倒计时秒数

响应示例

{
  "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格式时间字符串

响应示例

{
  "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. 加密邮件需要额外验证才能查看内容