企业官网建设流程全解析

ToolJet SMTP 数据源接入指南：从服务器配置到邮件发送查询实战

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

SMTP 数据源是 ToolJet 内置的邮件发送通道，它允许应用通过任意标准 SMTP 邮件服务器（Gmail、Yahoo、Outlook、自建服务器等）对外发送邮件。本文以 docs/versioned_docs/version-3.0.0-LTS/data-sources/smtp.md 为主线，结合仓库中 SMTP 插件的源码实现（plugins/packages/smtp/lib/index.ts），讲解连接配置、查询创建、参数含义与底层原理，读完即可在 ToolJet 应用中独立配置 SMTP 数据源并完成邮件发送。

SMTP 数据源能做什么

SMTP（Simple Mail Transfer Protocol）数据源在 ToolJet 中扮演"邮件出口"的角色：一旦在工作区中建立了 SMTP 连接，该连接即可被工作区内的任意应用共享，用于发送事务邮件、通知提醒、报表分发等场景。它属于 ToolJet 插件体系中的type: "api"类型数据源，核心实现基于 Node.js 生态中成熟的 Nodemailer 库（见 plugins/packages/smtp/lib/index.ts 的import nodemailer from 'nodemailer'）。

数据源的整体接入方式（在查询面板或 Data Sources 页面添加、多环境切换、权限管理等）可参考 Data Sources 总览文档。

建立 SMTP 连接

要建立 SMTP 数据源连接，有两种入口：

1. 在应用编辑器底部的查询面板中，点击+ Add new Data source按钮；
2. 从 ToolJet 仪表盘的左侧导航进入Data Sources页面，选择SMTP数据源。

ToolJet 连接 SMTP 服务器需要以下四个必填参数：

从插件清单 manifest.json 可以看到这四个参数均被标记为required，且password字段带有"encrypted": true标记，意味着密码在保存时会经过加密处理，界面上以"Encrypted"形式显示。清单中还定义了如下默认值：

"defaults": { "host": { "value": "localhost" }, "port": { "value": 465 }, "user": { "value": "" }, "password": { "value": "" } }

即默认端口为 465（SSL 安全端口），Host 默认为localhost，实际使用时需按你的邮件服务商替换。

常见邮件服务商的配置参数

SMTP 的主机与端口通常由邮件服务商提供，以下是文档中列出的主流邮箱服务商通用配置：

• Gmail

  • Host：smtp.gmail.com
  • Port：587或465（SSL）
  • Username：完整 Gmail 邮箱地址
  • Password：Gmail 密码（实际使用中通常需要应用专用密码/授权码）

• Yahoo Mail

  • Host：smtp.mail.yahoo.com
  • Port：465（SSL）
  • Username：Yahoo 邮箱地址
  • Password：Yahoo 邮箱密码

• Outlook.com / Hotmail

  • Host：smtp.office365.com
  • Port：587或465（SSL）
  • Username：Outlook.com / Hotmail 邮箱地址
  • Password：Outlook.com / Hotmail 密码

配置完成后，界面会提供Test connection按钮验证连接是否可用。

连接参数的底层实现

从源码看，SMTP 连接实际上由 getConnection 方法 构建：

async getConnection(sourceOptions: SourceOptions, _options?: object): Promise<Transporter> { const { host, user, password } = sourceOptions; const port = Number(sourceOptions.port); const transport: Transporter = nodemailer.createTransport({ port, host, secure: port === 465, auth: { user, pass: password }, }); return transport; }

几个值得注意的实现细节：

• secure: port === 465：插件会根据端口号自动决定是否启用 SSL/TLS。当端口为 465 时走隐式 TLS（secure 连接）；使用 587 时则通过 STARTTLS 升级加密。这就是文档中"Port 587 或 465 (SSL)"两种写法的来源；
• 端口类型转换：配置表单中的 Port 以字符串形式传入，源码中通过Number(sourceOptions.port)显式转为数字；
• 测试连接：testConnection方法调用 Nodemailer 的transporter.verify()来验证凭据有效性，失败时统一抛出Invalid credentials错误（index.ts）。

创建 SMTP 查询发送邮件

连接建立后，即可在应用中创建查询来发送邮件，操作步骤如下：

1. 点击编辑器底部查询管理器的+ Add按钮；
2. 选择上一步添加的SMTP数据源；
3. 填写邮件发送所需的参数；
4. 点击Preview预览输出，或点击Run触发查询执行。

必填参数

可选参数

使用 File Picker 添加附件

附件字段支持两种写法（文档原文示例）：

• 引用 File Picker 组件上传的文件：

{{ components.filepicker1.file }}

• 或直接传入包含文件名与 dataURL 的对象：

{{ name: 'filename.jpg', dataURL: '......' }}

参数与源码的对应关系

查询表单的字段定义位于 operations.json，其中每个字段均为codehinter类型，意味着所有参数都支持写 JS 表达式（{{ }}模板语法）——例如 CC/BCC 字段的占位符为{{['dev@tooljet.io']}}，说明抄送/密送支持传入字符串数组；Attachments 字段占位符为{{components.filepicker1.file}}。

这些字段在运行时被映射为 types.ts 中定义的QueryOptions：

export type QueryOptions = { operation: string; from: string; from_name: string; to: string; cc: string[]; bcc: string[]; subject: string; textContent: string; htmlContent: string; attachment_array?: string | { name: string; dataURL: string }[]; };

在 run 方法 中，插件会将 Text 与 HTML 两个字段分别作为text和html传给 Nodemailer，实现"同一封邮件同时携带纯文本与 HTML 两个版本"的效果（邮件客户端会按自身能力自动选择渲染版本）。

附件处理逻辑值得留意：attachment_array可能以 JSON 字符串形式传入，源码会先尝试JSON.parse，再对每个附件执行 base64 解码后组装为 Nodemailer 的Attachment对象：

const filesData = (array: { name: string; dataURL: string }[]): Attachment[] => { const newFiles = array.map((x) => { return { filename: x.name, content: Buffer.from(x.dataURL, 'base64') }; }); return newFiles; };

邮件最终通过nodemailerTransport.sendMail(mailOptions)发送，发送失败时抛出QueryError；成功则返回{ status: 'ok', data: {} }。

发送邮件后的返回值与使用方式

SMTP 查询执行成功后返回status: 'ok'的空数据对象。在实际应用中，通常有两种使用方式：

1. 事件触发：在查询的Success事件处理器中挂接后续动作（如弹出提示"邮件已发送"、更新表单状态等），将邮件发送作为工作流中的一个环节；
2. 组件联动：从按钮的onClick事件中运行 SMTP 查询，将表单输入（例如文本输入组件的值）通过{{ }}表达式填入 From、To、Subject、Body 等字段，实现"填表即发信"的完整交互。

常见问题与排错建议

• 认证失败（Invalid credentials）：testConnection依赖transporter.verify()与邮件服务器完成一次真实握手，若用户名或密码错误、或邮箱服务商要求使用"应用专用密码"（如 Gmail 开启两步验证后的场景），连接测试会直接失败。请先在邮箱服务商处确认认证方式；
• 端口与加密不匹配：源码中secure完全由端口是否为 465 决定，若你的服务器使用 465 以外的端口但需要显式 TLS，或使用 587 且服务商不支持 STARTTLS，都可能握手异常，请以邮件服务商文档为准配置端口；
• 附件格式问题：附件对象中的dataURL应为 base64 编码内容，File Picker 组件返回的文件对象结构需与{ name, dataURL }保持一致，否则解码后内容可能为空或损坏；
• 连接超时或无法解析主机：确认 Host 填写的是可公网访问的 SMTP 地址，自建服务器场景下还需检查防火墙是否放行了对应端口。

小结

SMTP 数据源为 ToolJet 应用提供了标准、可复用的邮件发送能力：连接层只需 Host / Port / Username / Password 四项参数，查询层提供 From、To、Subject、Body 及 CC / BCC / 附件等完整邮件要素，且所有字段均支持{{ }}表达式与组件联动。底层由插件以 Nodemailer 驱动，端口 465 自动启用 SSL、密码加密存储、附件 base64 解码等细节都在 plugins/packages/smtp 中可见一斑。结合 File Picker 组件与事件处理器，即可在 ToolJet 中快速搭建通知、审批、报表分发等邮件自动化场景。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet