koishi-plugin-mail

插件介绍

koishi-plugin-mail 是一个为 Koishi 框架提供邮件服务的插件，主要用于离线留言与公告发布。该插件支持多种邮件类型，包括系统公告、重要公告、普通公告和私信，并提供了完整的邮件管理功能。

前置依赖

• 需要 Koishi v4.17.11 或更高版本
• 需要数据库支持（database 服务）

邮件类型说明

插件支持以下几种邮件类型：

• 系统公告（类型值：0）：所有人可见，所有人不可标记已读与删除
• 重要公告（类型值：2）：所有人可见，所有人可标记已读但不可删除
• 普通公告（类型值：3）：所有人可见，所有人可标记已读可删除
• 私信（类型值：8）：仅收件人可见，收件人可标记已读可删除

API 接口

创建邮件

创建一封新邮件并发送给指定用户。

ctx.mail.create({
  type: MailType.PrivateMessage,  // 邮件类型
  from: 'sender_id',              // 发件人ID
  to: 'recipient_id',             // 收件人ID
  title: '邮件标题',               // 邮件标题
  content: '邮件内容',             // 邮件内容
  attach: {                       // 可选的附件
    filename: '文件名.jpg',
    url: 'https://example.com/file.jpg',
    size: 1024,
    type: 'image/jpeg'
  }
})

获取邮件列表

获取指定用户的邮件列表。

ctx.mail.list('user_id', {
  type: MailType.PrivateMessage,  // 可选，筛选邮件类型
  seen: false,                    // 可选，筛选未读邮件
  visible: false,                 // 可选，筛选未删除邮件
  limit: 20,                      // 可选，限制返回数量
  offset: 0                       // 可选，分页偏移量
})

删除邮件

删除指定ID的邮件。

ctx.mail.remove('user_id', mail_id)

标记邮件为已读

将邮件标记为已读状态。

ctx.mail.markAsSeen('user_id', mail_id)

移动邮件到回收箱

将邮件移动到回收箱（设置 visible 为 true）。

ctx.mail.moveToTrash('user_id', mail_id)

从回收箱恢复邮件

从回收箱恢复邮件（设置 visible 为 false）。

ctx.mail.restoreFromTrash('user_id', mail_id)

发送系统公告

发送一条系统公告给所有用户。

ctx.mail.sendSystemAnnouncement({
  from: 'admin_id',                       // 发件人ID
  title: '系统公告标题',                    // 公告标题
  content: '系统公告内容',                  // 公告内容
  type: MailType.SystemAnnouncement,      // 可选，公告类型
  attach: {                               // 可选，附件
    filename: '附件.pdf',
    url: 'https://example.com/file.pdf'
  }
})

获取公告列表

获取系统公告列表。

ctx.mail.getAnnouncements({
  type: MailType.ImportantAnnouncement,   // 可选，筛选公告类型
  limit: 10,                              // 可选，限制返回数量
  offset: 0                               // 可选，分页偏移量
})

返回值说明

所有方法都会返回一个包含以下字段的对象：

• code: 状态码
  • 0: 操作成功
  • -1: 操作失败（通常是服务器错误）
  • 1: 权限不足或操作不允许
  • 2: 无权操作他人邮件
  • 3: 邮件不存在
• msg: 状态消息
• data: 返回的数据（如果有）
• error: 错误信息（如果有）

使用示例

发送私信

// 发送私信给用户
const result = await ctx.mail.create({
  type: MailType.PrivateMessage,
  from: 'admin',
  to: 'user123',
  title: '欢迎加入',
  content: '欢迎加入我们的社区！如有问题请随时联系管理员。'
})

if (result.code === 0) {
  console.log('私信发送成功')
} else {
  console.error('私信发送失败:', result.msg)
}

发布系统公告

// 发布重要公告
const result = await ctx.mail.sendSystemAnnouncement({
  from: 'system',
  title: '系统维护通知',
  content: '系统将于明日凌晨2点进行维护，预计持续2小时。',
  type: MailType.ImportantAnnouncement
})

if (result.code === 0) {
  console.log('公告发布成功')
} else {
  console.error('公告发布失败:', result.msg)
}

获取用户未读邮件

// 获取用户未读邮件
const result = await ctx.mail.list('user123', { seen: false })

if (result.code === 0) {
  const unreadCount = result.data.length
  console.log(`用户有 ${unreadCount} 封未读邮件`)
} else {
  console.error('获取邮件失败:', result.msg)
}

注意事项

1. 系统公告（类型0）和重要公告（类型2）不可被用户删除
2. 邮件删除后实际上是移动到回收箱（visible 设为 true），可以通过 restoreFromTrash 恢复
3. 公告的收件人字段设置为 '*'，表示所有人可见
4. 确保在使用前已正确配置数据库服务

数据库结构

插件会在数据库中创建 mail 表，包含以下字段：

• id: 邮件ID（自增）
• type: 邮件类型
• from: 发件人ID
• to: 收件人ID（'*' 表示所有人）
• time: 发送时间
• title: 邮件标题
• content: 邮件内容
• seen: 是否已读
• visible: 是否可见（false 表示正常，true 表示在回收箱）
• attach: 附件信息（JSON格式）