emall/emall-api

Fork 0

Files

XCool e287d7bbde 初始化

2025-10-18 16:18:20 +08:00

10 KiB

Raw Blame History

存入胶囊功能 API 文档

概述

存入胶囊功能允许用户将邮件保存为时光胶囊状态，邮件将以草稿形式保存，用户可以随时编辑或发送。

API 接口

创建胶囊邮件

接口地址： POST /api/v1/mails

接口描述： 创建一个新邮件并将其保存为时光胶囊状态（草稿）

请求参数

参数名	类型	必填	说明
title	string	是	邮件标题
content	string	是	邮件内容
recipientType	string	是	收件人类型：SELF（自己）、SPECIFIC（指定收件人）、PUBLIC（公开信）
recipientEmail	string	否	指定收件人邮箱（当recipientType为SPECIFIC时必填）
sendTime	string	否	发送时间，ISO格式时间字符串（如：2025-12-31T23:59:59Z）
triggerType	string	否	触发类型：TIME（时间）、LOCATION（地点）、EVENT（事件）
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	否	事件类型
attachments	array	否	附件列表
attachments[].type	string	否	附件类型：IMAGE、VOICE、VIDEO
attachments[].url	string	否	附件URL
attachments[].thumbnail	string	否	缩略图URL
isEncrypted	boolean	否	是否加密
capsuleStyle	string	否	胶囊样式
status	string	是	邮件状态，存入胶囊时固定为：DRAFT

请求示例

{
  "title": "写给未来的自己",
  "content": "亲爱的未来的我，当你读到这封信时，希望你已经实现了现在的梦想...",
  "recipientType": "SELF",
  "sendTime": "2025-12-31T23:59:59Z",
  "triggerType": "TIME",
  "attachments": [
    {
      "type": "IMAGE",
      "url": "https://example.com/image.jpg",
      "thumbnail": "https://example.com/thumb.jpg"
    }
  ],
  "isEncrypted": false,
  "capsuleStyle": "default",
  "status": "DRAFT"
}

响应参数

参数名	类型	说明
code	number	响应状态码，200表示成功
message	string	响应消息
data	object	响应数据
data.mailId	string	邮件ID
data.capsuleId	string	胶囊ID
data.status	string	邮件状态：DRAFT、PENDING、DELIVERING、DELIVERED
data.createdAt	string	创建时间，ISO格式时间字符串

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "mail_1234567890",
    "capsuleId": "capsule_1234567890",
    "status": "DRAFT",
    "createdAt": "2023-07-20T10:30:00Z"
  }
}

获取胶囊列表

接口地址： GET /api/v1/mails

接口描述： 获取用户的胶囊邮件列表

请求参数

参数名	类型	必填	说明
type	string	否	邮件类型：INBOX、SENT、DRAFT，获取胶囊时使用DRAFT
status	string	否	状态筛选：PENDING、DELIVERING、DELIVERED、DRAFT
page	number	否	页码，默认为1
size	number	否	每页数量，默认为10

请求示例

GET /api/v1/mails?type=DRAFT&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.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": "DRAFT",
        "hasAttachments": true,
        "isEncrypted": false,
        "capsuleStyle": "default"
      }
    ],
    "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	是否可编辑（草稿状态为true）
data.canRevoke	boolean	是否可撤销（待投递状态为true）

响应示例

{
  "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": "DRAFT",
    "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": true,
    "canRevoke": false
  }
}

更新胶囊邮件

接口地址： PUT /api/v1/mails/{mailId}

接口描述： 更新胶囊邮件内容（仅草稿状态可更新）

请求参数

参数名	类型	必填	说明
mailId	string	是	邮件ID（路径参数）
title	string	否	邮件标题
content	string	否	邮件内容
recipientType	string	否	收件人类型：SELF、SPECIFIC、PUBLIC
recipientEmail	string	否	指定收件人邮箱（当recipientType为SPECIFIC时必填）
sendTime	string	否	发送时间，ISO格式时间字符串
triggerType	string	否	触发类型：TIME、LOCATION、EVENT
triggerCondition	object	否	触发条件
attachments	array	否	附件列表
isEncrypted	boolean	否	是否加密
capsuleStyle	string	否	胶囊样式

请求示例

{
  "title": "更新后的标题",
  "content": "更新后的内容...",
  "sendTime": "2026-12-31T23:59:59Z"
}

响应参数

参数名	类型	说明
code	number	响应状态码，200表示成功
message	string	响应消息
data	object	响应数据
data.mailId	string	邮件ID
data.capsuleId	string	胶囊ID
data.status	string	邮件状态
data.updatedAt	string	更新时间，ISO格式时间字符串

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "mail_1234567890",
    "capsuleId": "capsule_1234567890",
    "status": "DRAFT",
    "updatedAt": "2023-07-21T14:30:00Z"
  }
}

删除胶囊邮件

接口地址： DELETE /api/v1/mails/{mailId}

接口描述： 删除指定的胶囊邮件

请求参数

参数名	类型	必填	说明
mailId	string	是	邮件ID（路径参数）

请求示例

DELETE /api/v1/mails/mail_1234567890

响应参数

参数名	类型	说明
code	number	响应状态码，200表示成功
message	string	响应消息
data	object	响应数据
data.mailId	string	已删除的邮件ID

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "mailId": "mail_1234567890"
  }
}

错误码

错误码	说明
200	成功
400	请求参数错误
401	未授权，需要登录
403	权限不足
404	资源不存在
422	验证失败
500	服务器内部错误

注意事项

存入胶囊的邮件状态为DRAFT，可以在任何时候编辑或发送
只有草稿状态的邮件可以编辑或删除
发送时间必须晚于当前时间
附件大小限制为10MB
免费用户每月最多可创建10个胶囊邮件
加密邮件需要额外验证才能查看内容

10 KiB Raw Blame History Unescape Escape

存入胶囊功能 API 文档

概述

API 接口

创建胶囊邮件

请求参数

请求示例

响应参数

响应示例

获取胶囊列表

请求参数

请求示例

响应参数

响应示例

获取胶囊详情

请求参数

请求示例

响应参数

响应示例

更新胶囊邮件

请求参数

请求示例

响应参数

响应示例

删除胶囊邮件

请求参数

请求示例

响应参数

响应示例

错误码

注意事项

10 KiB

Raw Blame History