
AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载本指南基于 Botpress 官方 Hub 中的 Email 集成文档integrations/email/hub.md及其源码展开介绍如何通过 IMAP 读取邮件、通过 SMTP 发送邮件将邮件通道接入 Botpress Agent。读完本文你将掌握该集成的完整配置方法、四个核心 Action 的调用方式、邮件同步机制的底层原理以及如何基于源码调试与扩展。一、集成概览IMAP 读、SMTP 发Email 集成是 Botpress 官方提供的邮件通道解决方案它把两种成熟的互联网邮件协议封装成 Agent 可用的 Action 与 ChannelIMAPInternet Message Access Protocol负责读取收件箱中的邮件将新邮件转成 Botpress 消息事件推送给 AgentSMTPSimple Mail Transfer Protocol负责发送邮件让 Agent 可以直接回复用户或主动外发邮件。从集成定义integrations/email/integration.definition.ts可以看出官方对它的定位是使用 IMAP 和 SMTP 协议发送和接收电子邮件Send and receive emails using IMAP and SMTP protocols当前版本为0.1.4归属营销与邮件Marketing Email分类。需要特别注意的一个能力边界该集成目前不支持 HTML 邮件内容收发双方都只处理纯文本。这意味着在 Agent 端构造邮件时应使用纯文本描述内容避免依赖富文本排版。二、快速开始配置文件与参数详解2.1 官方文档给出的最小配置在 Botpress Hub 中安装 Email 集成后需要在集成配置中填写邮箱凭据。官方文档给出了如下示例user: yourEmailAccountgmail.com password: yourAccountPassword host: imap.gmail.com #for gmail2.2 完整的四个配置字段以源码为准对照 integration.definition.ts 中的configuration.schema定义实际配置共包含4 个必填字段比文档示例多出smtpHost字段类型说明示例userstring用于收发邮件的邮箱账号examplegmail.compasswordstring该邮箱账号的密码或应用专用密码yourAccountPasswordimapHoststring要连接的 IMAP 服务器地址imap.gmail.comsmtpHoststring要连接的 SMTP 服务器地址smtp.gmail.com四个字段全部为必填.required()。对于 Gmail 等主流邮箱服务商常见的配置组合是imapHost: imap.gmail.comsmtpHost: smtp.gmail.com对于 QQ 邮箱则为imap.qq.comsmtp.qq.com。若使用企业邮箱或自建邮件服务器请替换为对应的 IMAP/SMTP 主机名。提示多数主流邮箱要求为第三方应用开启 IMAP/SMTP 访问权限并生成应用专用密码App Password直接使用邮箱登录密码往往会被服务器拒绝。若注册集成时报连接错误请优先检查这一点。三、集成生命周期注册时如何校验配置Email 集成通过register与unregister两个生命周期钩子管理自身的启停见 index.ts 与 setup.tsregister注册设置初始lastSyncTimestamp状态并立即发起一次 IMAP 连接取 1 条消息来验证配置正确性。若连接失败会抛出运行时错误注册集成时发生错误... 请验证你的配置从源头拦截错误凭据unregister注销无额外清理逻辑源码注释// nothing to unregister。// integrations/email/src/setup.ts 中的校验逻辑示意 try { await getMessages({ page: 0, perPage: 1 }, props) } catch (thrown: unknown) { throw new sdk.RuntimeError( An error occured when registering the integration: ${err.message} Verify your configuration. ) }从 imap.ts 的_getConfig可以看到IMAP 连接固定使用端口 993 TLS 加密并设置了rejectUnauthorized: false跳过证书校验便于连接部分自签名证书的邮件服务器const _getConfig function (config: bp.configuration.Configuration) { return { user: config.user, password: config.password, host: config.imapHost, port: 993, tls: true, tlsOptions: { rejectUnauthorized: false }, } }四、四大 ActionAgent 的邮件工具箱集成对外暴露了 4 个 Action定义见 integration.definition.ts实现见 actions.tsAgent 工作流中可直接调用4.1 listEmails分页列出收件箱邮件输入nextToken可选页号从 0 开始输出messages邮件数组nextToken下一页令牌无更多页时为 undefined实现要点每页固定50 封ELEMENTS_PER_PAGE 50见 actions.tsnextToken不能为负数否则抛出RuntimeError仅拉取邮件头HEADER不包含正文适合快速扫描收件箱。4.2 getEmail按 ID 获取单封邮件输入id邮件的唯一标识即 IMAP 服务器返回的message-id输出完整的emailSchema字段 body邮件正文实现要点通过 IMAPsearch按MESSAGE-ID头搜索邮件见 imap.ts找不到时返回 undefined 并抛出找不到对应 ID 的邮件错误。注意搜索使用的 ID 是邮件头中的message-id并非 IMAP 序号跨会话稳定。4.3 syncEmails增量同步新邮件输入/输出均为空对象作用把未读过的邮件作为新消息推送给 Agent需要周期性调用才能让 Bot 持续收到新邮件实现要点这是接收邮件链路上最关键的 Action下一节详细展开。4.4 sendEmail通过 SMTP 发送邮件输入to必填收件人邮箱subject可选邮件主题text可选邮件正文纯文本inReplyTo可选要回复的邮件 ID用于构造回复线程replyTo可选收件人回复时应使用的地址允许与发件人不同输出空对象实现要点底层使用nodemailer创建 transporter 并调用sendMail见 smtp.tsfrom固定为配置中的user同时把inReplyTo写入邮件的references头以维护线程const transporter nodemailer.createTransport({ host: config.smtpHost, auth: { user: config.user, pass: config.password }, }) await transporter.sendMail({ from: config.user, ...props, references: props.inReplyTo, })五、邮件同步的底层机制状态、锁与去重syncEmails是收件的核心其实现逻辑actions.ts值得细读它由三块机制协同完成5.1 同步锁防止并发同步locking.ts 中的LockHandler利用集成的syncLock状态见 integration.definition.ts实现互斥const currentlySyncing await lock.readLock() if (currentlySyncing) throw new sdk.RuntimeError(The bot is still syncing the messages. Try again later.) await lock.setLock(true) // ... 同步逻辑 ... await lock.setLock(false)如果上一次同步尚未结束再次调用syncEmails会直接报错Bot 仍在同步消息请稍后再试避免两个同步任务同时抢占 IMAP 连接。5.2 时间戳状态增量去重lastSyncTimestamp状态记录了上一次成功同步的时间integration.definition.ts。同步时逐封对比邮件日期const messageAlreadySeen message.date lastSyncTimestamp new Date(message.date) new Date(lastSyncTimestamp.lastSyncTimestamp) if (messageAlreadySeen) continue日期不晚于上次同步时间的邮件视为已处理直接跳过同步完成后将当前时间写入状态。这样既避免重复推送又能在 Bot 重启后从断点继续。5.3 消息通知链路从邮件到对话未被跳过的邮件会进入_notifyNewMessageactions.ts完整链路为用户映射以发件人邮箱为email标签getOrCreateUser创建或复用 Botpress 用户会话映射以firstMessageId取邮件references头中最早的 message-id否则回退为自身 id为区分标签getOrCreateConversation创建或复用会话同时把subject、to、latestEmail写入会话标签integration.definition.ts消息落库createMessage以纯文本形式把邮件正文message.body ?? 写入会话并打上邮件id标签。发件人为配置中的user自己的邮件会被直接跳过if (message.sender props.ctx.configuration.user) continue避免把 Bot 自己发出的邮件又当成新消息回灌。六、Channel 视角Bot 如何回复邮件集成定义了default通道integration.definition.ts实现见 channels.ts支持text类型消息。当 Agent 决定回复某封邮件时通道处理器自动完成回复拼接await smtp.sendNodemailerMail( props.ctx.configuration, { to: props.conversation.tags.to, subject: Sent from botpress email integration, text: props.payload.text, inReplyTo: props.conversation.tags.latestEmail, replyTo: props.ctx.configuration.user, }, props.logger )几个值得注意的细节收件人取自会话标签to即原邮件的收件人若会话缺少该标签会抛出尝试在没有 to 头的情况下发送邮件错误inReplyTo使用会话标签latestEmail即该会话最新一封邮件的 ID确保回复挂到正确的邮件线程上replyTo固定为配置中的user收件人回复时会回到 Bot 的邮箱账号主题固定为 Sent from botpress email integration如需自定义主题应通过sendEmailAction 而非通道回复。七、分页算法的实现细节与测试验证listEmails的分页并非简单偏移量而是基于 IMAP 序列号区间实现paging.tsexport const pageToSpan (props: PageToSpanProps): Span { if (props.totalElements 0) { throw new sdk.RuntimeError(Could not read the inbox: the number of messages in the inbox is 0) } const lastElementIndex Math.max(1, props.totalElements - props.page * props.perPage) const firstElementIndex Math.max(1, lastElementIndex - props.perPage 1) return { firstElementIndex, lastElementIndex } } export const getNextToken (props: NextTokenProps): number | undefined { if (props.firstElementIndex 1) return undefined return props.page 1 }其语义为第 0 页取最新 50 封收件箱末尾页码越大越往旧邮件方向翻当某一页已经覆盖到第 1 封最旧邮件时getNextToken返回undefined表示没有下一页了。该算法有配套的单测覆盖paging.test.ts包括空收件箱抛错、单封邮件、不足一页、满页、翻页与 token 边界等场景例如test(pageToSpan with full page returns first page, () { expect(pageToSpan({ page: 0, perPage: 50, totalElements: 300 })).toEqual({ firstElementIndex: 251, lastElementIndex: 300, } satisfies Span) })八、本地开发与调试该集成位于integrations/email/目录下package.json提供了完整的开发脚本{ name: botpresshub/email, scripts: { check:type: tsc --noEmit, check:bplint: bp lint, build: bp build, test: vitest --run }, dependencies: { botpress/client: workspace:*, botpress/sdk: workspace:*, imap: ^0.8.17, nodemailer: ^6.7.2 } }类型检查tsc --noEmit确认类型定义与.botpress生成代码一致集成规范检查bp lint使用 Botpress CLI 校验集成定义是否符合平台规范单元测试vitest --run目前覆盖分页算法构建bp build产出可部署的集成包。IMAP 相关错误在源码中均被包装为RuntimeError并附带原因排查问题时重点关注两类报错注册阶段的验证你的配置多半是凭据或主机名问题与同步阶段的验证集成配置参数可能是网络或服务器权限问题。九、使用建议与限制总结场景推荐做法接收新邮件周期性如每分钟调用syncEmails或在定时任务中触发扫描收件箱调用listEmails分页浏览邮件头配合nextToken翻页读取邮件全文用listEmails得到的id调用getEmail获取body主动发信调用sendEmail可自定义收件人、主题、正文与回复线程会话式回复让 Agent 在邮件会话上下文中回复走default通道自动挂线程当前版本的能力边界与已知限制包括不支持 HTML 内容收发双方均为纯文本IMAP 固定使用 993 端口 TLS且跳过证书校验rejectUnauthorized: false在安全性要求极高的内网环境需注意syncEmails每次同步只处理最新一页50 封内的新邮件超过 50 封的积压需要多次同步才能全部拉取同步为互斥操作并发调用会直接报错默认仅处理收件箱INBOX不涉及其他 IMAP 文件夹。参考文件索引官方文档integrations/email/hub.md集成定义配置/状态/Action/通道 Schemaintegrations/email/integration.definition.ts入口与生命周期注册integrations/email/src/index.ts、integrations/email/src/setup.tsAction 实现含同步机制integrations/email/src/actions.tsIMAP 实现integrations/email/src/imap.tsSMTP 实现integrations/email/src/smtp.ts通道处理integrations/email/src/channels.ts同步锁与分页integrations/email/src/locking.ts、integrations/email/src/paging.ts分页单测integrations/email/src/paging.test.ts赞分享AI 应用后端【免费下载链接】botpressThe open-source hub to build deploy GPT/LLM Agents ⚡️项目地址https://gitcode.com/gh_mirrors/bo/botpress点击查看免费下载相关推荐Agent Zero Email Integration 插件邮件收件箱轮询、智能路由分发与 SMTP 线程化回复的实现机制Agent Zero Email Integration 插件邮件收件箱轮询、智能路由分发与 SMTP 线程化回复的实现机制 本文基于 Agent Zero人工智能大模型AI AgentAgent 框架自主智能体多智能体工具调用MCP 服务浏览器控制OpenClaw Mastery Day 6 实战用 imap-smtp-email 技能驯服 Gmail 收件箱IMAP 只读 邮件分诊 提示注入防护OpenClaw Mastery Day 6 实战用 imap smtp email 技能驯服 Gmail 收件箱IMAP 只读 邮件分诊 提示注入文档教程人工智能大模型OpenClaw Mastery Day 6用 imap-smtp-email 技能驯服收件箱——IMAP 只读接入、邮件分诊与提示注入防护OpenClaw Mastery Day 6用 imap smtp email 技能驯服收件箱——IMAP 只读接入、邮件分诊与提示注入防护 本篇文章是 aw文档教程人工智能大模型创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考