koishi-plugin-adapter-mail-pro 邮件适配器

📬 项目介绍#

koishi-plugin-adapter-mail-pro 是一款基于 @satorijs/adapter-mail 扩展开发的 Koishi 邮件适配器插件。它让 Koishi 机器人可以直接通过 SMTP 发送邮件、IMAP 接收邮件，把邮件变成机器人的一种”聊天平台”——收到的邮件会触发消息事件，发送邮件就像发私聊消息一样简单。

opwop1

koishi-plugin-adapter-mail-pro

邮件适配器增强版，支持自定义邮件主题、发件人名称、STARTTLS加密模式

—

no-license

JavaScript

⭐ 开源地址：https://github.com/opwop1/koishi-plugin-adapter-mail-pro

✨ 功能特性#

SMTP 发送：通过标准 SMTP 协议发送邮件，支持 SSL 直连与 STARTTLS
IMAP 接收：实时监听新邮件并触发 Koishi 消息事件
私聊语义：邮件被当作私聊消息处理，发件人邮箱即 userId
自定义标题：单封邮件可覆盖默认主题（subject）
自定义发件人：单封邮件可覆盖默认发件人名称（fromName）
广泛兼容：QQ 邮箱、163、Gmail、Outlook、企业邮箱等标准 SMTP/IMAP 服务均可使用

📦 安装与配置#

1. 准备邮箱信息#

在邮箱后台获取以下信息：

SMTP 服务器地址和端口（用于发送）
IMAP 服务器地址和端口（用于接收）
授权码 / 应用专用密码（大部分邮箱不允许直接使用登录密码）

2. 配置示例#

1
{
2
  "username": "your@email.com",
3
  "password": "your_authorization_code",
4
  "selfId": "your@email.com",
5
  "subject": "Koishi",
6
  "imap": {
7
    "host": "imap.example.com",
8
    "port": 993,
9
    "tls": true
10
  },
11
  "smtp": {
12
    "host": "smtp.example.com",
13
    "port": 465,
14
    "tls": true
15
  }
16
}

配置项	必填	说明
`username`	是	邮箱账号
`password`	是	密码或授权码
`selfId`	否	邮件地址（默认同 username）
`name`	否	发件人显示名称
`subject`	否	机器人发送邮件的默认主题
`imap`	-	接收服务器配置（host / port / tls）
`smtp`	-	发送服务器配置（host / port / tls）

🚀 使用方法#

发送邮件#

给邮件适配器”发私聊消息”即可发送邮件，频道格式固定为 private:对方邮箱地址：

1
const bot = ctx.bots.find((b) => b.platform === "mail");
2
await bot.sendMessage("private:someone@example.com", "你好，这是一封测试邮件");

也可以封装成指令：

1
ctx
2
  .command("sendmail <to> <content:text>")
3
  .action(async ({ session }, to, content) => {
4
    const bot = ctx.bots.find((b) => b.platform === "mail");
5
    if (!bot) return "mail 适配器未启用";
6
    await bot.sendMessage(`private:${to}`, content);
7
    return "已发送";
8
  });

自定义邮件标题与发件人#

1
import { h } from "koishi";
2

3
const bot = ctx.bots.find((b) => b.platform === "mail");
4
await bot.sendMessage(
5
  "private:someone@example.com",
6
  h("message", { subject: "这里是标题", fromName: "这里是发件人名字" }, "这里是正文内容"),
7
);

接收邮件#

开启 IMAP 后，新邮件会触发 Koishi 消息事件（私聊消息），发件人邮箱就是 session.userId：

1
ctx.on("message", async (session) => {
2
  if (session.platform !== "mail") return;
3
  // session.userId 就是发件人邮箱
4
  await session.send(`已收到你的邮件：${session.content}`);
5
});

🌐 常见邮箱服务参数#

Outlook / Microsoft 365 / Exchange Online#

协议	服务器	端口	TLS
SMTP（STARTTLS，微软官方推荐）	`smtp.office365.com`	587	`true`
SMTP（SSL 直连）	`smtp.office365.com`	465	`true`
IMAP	`outlook.office365.com`	993	`true`

端口为 587 且 smtp.tls 为 true 时会自动走 STARTTLS。若开启了双重验证，需要生成”应用专用密码”。

QQ 邮箱 / 163 等#

请在邮箱后台开启 SMTP/IMAP 服务并生成授权码，服务器地址与端口以官方文档为准。

❓ 常见问题#

一直发不出去：检查 SMTP 配置是否正确，端口是否匹配 TLS
收不到邮件：检查 IMAP 是否开启，端口和 TLS 是否正确
需要授权码：大部分邮箱不允许直接用登录密码，需在邮箱后台生成”授权码”

📄 许可证#

MIT License

音乐

音乐