0.0.5 • Published 4 months ago

koishi-plugin-mail v0.0.5

Weekly downloads
-
License
GPL-3.0-only
Repository
-
Last release
4 months ago

koishi-plugin-mail

npm

插件介绍

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格式)
0.0.5

4 months ago

0.0.3

10 months ago

0.0.2

10 months ago

0.0.1

10 months ago