ZoneMTA 插件开发入门10 分钟编写你的第一个自定义插件【免费下载链接】zone-mta Modern outbound MTA cross platform and extendable server application项目地址: https://gitcode.com/gh_mirrors/zo/zone-mta如果你想给 ZoneMTA 增加自定义行为比如拦截特定发件人、自动添加邮件头、改写收件地址那么ZoneMTA 插件开发就是你必须掌握的核心技能。ZoneMTA 是一款基于 Node.js 和 MongoDB 构建的现代出站邮件服务器Outbound MTA跨平台且高度可扩展而它的插件系统正是这种扩展能力的灵魂。本文将用 10 分钟带你入门ZoneMTA 自定义插件从零写出第一个可运行的插件并成功挂载到邮件收发流程中。什么是 ZoneMTA 插件系统为什么值得学ZoneMTA 是专门用于发信的邮件中继服务器MTA/MSA它把消息投递的各个环节都设计成了可插拔的钩子Hook。与内置功能写死不同ZoneMTA 插件开发允许你在不修改核心源码的前提下精准地介入邮件从接收到投递的每一步。比如官方自带的 plugins/core/delivery-loop.js 插件就是通过一个简单的 Hook 检查 Received 头数量从而识别并拦截邮件循环。你可以照葫芦画瓢实现任何自定义逻辑。插件的基本结构只有两个必备要素一个 ZoneMTA 插件本质上就是一个普通的 Node.js 模块文件放在应用目录的plugins文件夹下。它只需要暴露两个东西title插件名称用于日志识别不写则用文件名代替init初始化方法在这里注册各种 Hook以最简单的 plugins/core/example-plugin.js 为例module.exports.title ExamplePlugin; module.exports.init (app, done) { // 在这里注册你的钩子 app.addHook(smtp:mail_from, (address, session, next) { let mailFrom (address address.address) || ; if (mailFrom.length 2048) { let err new Error(Sender address is too long); err.responseCode 452; return next(err); } next(); }); done(); }; 提示ZoneMTA 3.0 以上版本还支持async写法init async app {...}返回值取代了done()回调。核心概念Hook钩子机制插件的灵魂ZoneMTA 自定义插件的能力全部来自app.addHook(name, handler)。理解 Hook 就理解了插件开发的 80%。常见的钩子按生命周期分为三组阶段常用 Hook作用接收阶段receiversmtp:auth、smtp:mail_from、smtp:rcpt_to、smtp:data、message:headers、message:store鉴权、校验发件人/收件人、处理邮件头、决定是否入库投递阶段sendersender:fetch、sender:headers、sender:connection、sender:delivered取出队列、发送前改头、连接复用、投递成功回调全局/主进程mainapi:mail、queue:bounce、queue:route处理 HTTP API 入信、退信通知、路由改写完整列表见官方文档 plugins/README.md。在 Hook 中抛出的错误会直接变成 SMTP 响应码返回给客户端这是拦截邮件最优雅的方式。实战演练10 分钟写出第一个插件接下来我们写一个真实的ZoneMTA 自定义插件拦截来自特定发件人的邮件并给通过的消息自动加上一个标记头。第 1 步在应用的plugins/目录下新建plugins/user/block-sender.jsmodule.exports.title Block Sender; module.exports.init async app { // 拦截黑名单发件人 app.addHook(smtp:mail_from, async (address, session) { if (address.address spamexample.com) { let err new Error(Sender is blacklisted); err.responseCode 550; throw err; // 直接拒绝该发件人 } }); // 给合法邮件打上自定义标记 app.addHook(message:headers, async (envelope, messageInfo) { envelope.headers.add(X-Processed-By, zone-mta-plugin); }); };第 2 步编辑应用配置参考 config/default.js 中的plugins段启用插件并指定运行上下文{ plugins: { user/block-sender: { enabled: [receiver, sender] } } }第 3 步重启 ZoneMTA用 SMTP 客户端发一封来自spamexample.com的邮件会收到 550 拒绝其他邮件则会带着X-Processed-By头正常投递。 你的第一个插件已经上线⚠️ 注意插件的enabled值决定了它在哪个上下文加载——true或receiver只在收信阶段生效sender才能使用投递类钩子需要两者都用就写成数组。插件的三种上下文main / receiver / sender这是新手最容易踩的坑。ZoneMTA 采用多进程架构插件会在不同进程里加载receiver接收邮件并入队的进程可用smtp:*和message:*钩子sender真正连接对方 MX 服务器投递的进程可用sender:*钩子main主进程可注册 HTTP API、处理退信三个上下文之间无法直接共享内存数据只能通过envelope对象传递自定义字段必须是可 JSON 序列化的值。例如在smtp:data钩子里写入envelope.my_custom_value 123在sender:fetch里就能读出来这个技巧在官方文档里有详细说明。更多高级玩法不止于 Hook掌握了基础后ZoneMTA 插件开发还有三板斧可以玩1. 注册自己的 HTTP 接口需 main 上下文app.addAPI(GET, /ping, (req, res, next) { res.end(my awesome plugin); next(); });访问路径是/plugin/插件key/ping。2. 消息分析器 addAnalyzerHook直接处理客户端传来的原始字节流可以做内容过滤、哈希计算参考 example-plugin.js 里的 MD5 示例。3. 消息重写器 addRewriteHook针对 MIME 树中的特定节点如所有image/jpeg附件做流式改写甚至能把 JPG 打包成 ZIP——官方示例插件 plugins/core/example-plugin.js 里就有完整代码。快速排错与最佳实践插件加载顺序由config.plugins对象的键顺序决定依赖其他插件的功能时注意先后插件代码只在当前用户从 root 降权之后加载别在插件里做需要 root 的操作用app.logger.info(PluginName, message)输出日志方便在日志里定位写投递相关逻辑时优先用sender:headers连接已打开动作要快耗时操作放sender:connection想验证插件是否加载成功可以直接console.log然后看进程输出结语到这里你已经完成了ZoneMTA 插件开发的入门闭环理解了插件结构、Hook 机制、三种上下文并亲手写出了第一个ZoneMTA 自定义插件。插件系统是 ZoneMTA 最强大的扩展点官方文档 plugins/README.md 和内置插件源码如 plugins/core/dkim.js、plugins/core/default-headers.js都是绝佳的学习素材。接下来试着用同样的思路给你的邮件系统加上业务定制逻辑吧【免费下载链接】zone-mta Modern outbound MTA cross platform and extendable server application项目地址: https://gitcode.com/gh_mirrors/zo/zone-mta创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZoneMTA 插件开发入门：10 分钟编写你的第一个自定义插件
ZoneMTA 插件开发入门10 分钟编写你的第一个自定义插件【免费下载链接】zone-mta Modern outbound MTA cross platform and extendable server application项目地址: https://gitcode.com/gh_mirrors/zo/zone-mta如果你想给 ZoneMTA 增加自定义行为比如拦截特定发件人、自动添加邮件头、改写收件地址那么ZoneMTA 插件开发就是你必须掌握的核心技能。ZoneMTA 是一款基于 Node.js 和 MongoDB 构建的现代出站邮件服务器Outbound MTA跨平台且高度可扩展而它的插件系统正是这种扩展能力的灵魂。本文将用 10 分钟带你入门ZoneMTA 自定义插件从零写出第一个可运行的插件并成功挂载到邮件收发流程中。什么是 ZoneMTA 插件系统为什么值得学ZoneMTA 是专门用于发信的邮件中继服务器MTA/MSA它把消息投递的各个环节都设计成了可插拔的钩子Hook。与内置功能写死不同ZoneMTA 插件开发允许你在不修改核心源码的前提下精准地介入邮件从接收到投递的每一步。比如官方自带的 plugins/core/delivery-loop.js 插件就是通过一个简单的 Hook 检查 Received 头数量从而识别并拦截邮件循环。你可以照葫芦画瓢实现任何自定义逻辑。插件的基本结构只有两个必备要素一个 ZoneMTA 插件本质上就是一个普通的 Node.js 模块文件放在应用目录的plugins文件夹下。它只需要暴露两个东西title插件名称用于日志识别不写则用文件名代替init初始化方法在这里注册各种 Hook以最简单的 plugins/core/example-plugin.js 为例module.exports.title ExamplePlugin; module.exports.init (app, done) { // 在这里注册你的钩子 app.addHook(smtp:mail_from, (address, session, next) { let mailFrom (address address.address) || ; if (mailFrom.length 2048) { let err new Error(Sender address is too long); err.responseCode 452; return next(err); } next(); }); done(); }; 提示ZoneMTA 3.0 以上版本还支持async写法init async app {...}返回值取代了done()回调。核心概念Hook钩子机制插件的灵魂ZoneMTA 自定义插件的能力全部来自app.addHook(name, handler)。理解 Hook 就理解了插件开发的 80%。常见的钩子按生命周期分为三组阶段常用 Hook作用接收阶段receiversmtp:auth、smtp:mail_from、smtp:rcpt_to、smtp:data、message:headers、message:store鉴权、校验发件人/收件人、处理邮件头、决定是否入库投递阶段sendersender:fetch、sender:headers、sender:connection、sender:delivered取出队列、发送前改头、连接复用、投递成功回调全局/主进程mainapi:mail、queue:bounce、queue:route处理 HTTP API 入信、退信通知、路由改写完整列表见官方文档 plugins/README.md。在 Hook 中抛出的错误会直接变成 SMTP 响应码返回给客户端这是拦截邮件最优雅的方式。实战演练10 分钟写出第一个插件接下来我们写一个真实的ZoneMTA 自定义插件拦截来自特定发件人的邮件并给通过的消息自动加上一个标记头。第 1 步在应用的plugins/目录下新建plugins/user/block-sender.jsmodule.exports.title Block Sender; module.exports.init async app { // 拦截黑名单发件人 app.addHook(smtp:mail_from, async (address, session) { if (address.address spamexample.com) { let err new Error(Sender is blacklisted); err.responseCode 550; throw err; // 直接拒绝该发件人 } }); // 给合法邮件打上自定义标记 app.addHook(message:headers, async (envelope, messageInfo) { envelope.headers.add(X-Processed-By, zone-mta-plugin); }); };第 2 步编辑应用配置参考 config/default.js 中的plugins段启用插件并指定运行上下文{ plugins: { user/block-sender: { enabled: [receiver, sender] } } }第 3 步重启 ZoneMTA用 SMTP 客户端发一封来自spamexample.com的邮件会收到 550 拒绝其他邮件则会带着X-Processed-By头正常投递。 你的第一个插件已经上线⚠️ 注意插件的enabled值决定了它在哪个上下文加载——true或receiver只在收信阶段生效sender才能使用投递类钩子需要两者都用就写成数组。插件的三种上下文main / receiver / sender这是新手最容易踩的坑。ZoneMTA 采用多进程架构插件会在不同进程里加载receiver接收邮件并入队的进程可用smtp:*和message:*钩子sender真正连接对方 MX 服务器投递的进程可用sender:*钩子main主进程可注册 HTTP API、处理退信三个上下文之间无法直接共享内存数据只能通过envelope对象传递自定义字段必须是可 JSON 序列化的值。例如在smtp:data钩子里写入envelope.my_custom_value 123在sender:fetch里就能读出来这个技巧在官方文档里有详细说明。更多高级玩法不止于 Hook掌握了基础后ZoneMTA 插件开发还有三板斧可以玩1. 注册自己的 HTTP 接口需 main 上下文app.addAPI(GET, /ping, (req, res, next) { res.end(my awesome plugin); next(); });访问路径是/plugin/插件key/ping。2. 消息分析器 addAnalyzerHook直接处理客户端传来的原始字节流可以做内容过滤、哈希计算参考 example-plugin.js 里的 MD5 示例。3. 消息重写器 addRewriteHook针对 MIME 树中的特定节点如所有image/jpeg附件做流式改写甚至能把 JPG 打包成 ZIP——官方示例插件 plugins/core/example-plugin.js 里就有完整代码。快速排错与最佳实践插件加载顺序由config.plugins对象的键顺序决定依赖其他插件的功能时注意先后插件代码只在当前用户从 root 降权之后加载别在插件里做需要 root 的操作用app.logger.info(PluginName, message)输出日志方便在日志里定位写投递相关逻辑时优先用sender:headers连接已打开动作要快耗时操作放sender:connection想验证插件是否加载成功可以直接console.log然后看进程输出结语到这里你已经完成了ZoneMTA 插件开发的入门闭环理解了插件结构、Hook 机制、三种上下文并亲手写出了第一个ZoneMTA 自定义插件。插件系统是 ZoneMTA 最强大的扩展点官方文档 plugins/README.md 和内置插件源码如 plugins/core/dkim.js、plugins/core/default-headers.js都是绝佳的学习素材。接下来试着用同样的思路给你的邮件系统加上业务定制逻辑吧【免费下载链接】zone-mta Modern outbound MTA cross platform and extendable server application项目地址: https://gitcode.com/gh_mirrors/zo/zone-mta创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考