0.0.5 • Published 4 months ago
koishi-plugin-mail v0.0.5
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)
}
注意事项
- 系统公告(类型0)和重要公告(类型2)不可被用户删除
- 邮件删除后实际上是移动到回收箱(visible 设为 true),可以通过 restoreFromTrash 恢复
- 公告的收件人字段设置为 '*',表示所有人可见
- 确保在使用前已正确配置数据库服务
数据库结构
插件会在数据库中创建 mail
表,包含以下字段:
id
: 邮件ID(自增)type
: 邮件类型from
: 发件人IDto
: 收件人ID('*' 表示所有人)time
: 发送时间title
: 邮件标题content
: 邮件内容seen
: 是否已读visible
: 是否可见(false 表示正常,true 表示在回收箱)attach
: 附件信息(JSON格式)