ToolJet 自托管 SMTP 邮件配置指南通过 GUI 与环境变量两种方式接入自定义邮件服务【免费下载链接】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/ToolJetToolJet 的 SMTP 配置功能专属于自托管self-hosted部署形态允许实例管理员接入自选邮件服务器用于发送邀请邮件、密码重置请求与各类通知。本文基于官方配置文档结合仓库中 服务端 SMTP 模块 与 邮件发送实现 的源码系统讲解在 ToolJet 中完成 SMTP 配置的两种方式GUI 与环境变量并深入说明配置项背后的校验逻辑与发送链路帮助你按需搭建可用的邮件基础设施。功能定位与适用场景SMTP 配置是自托管 ToolJet 实例的基础能力之一其核心用途是让 ToolJet 通过你自己的邮件服务器对外发信典型场景包括向新成员发送工作区邀请邮件处理密码重置请求发送平台运行相关的通知邮件。ToolJet 提供了两种等价的配置路径GUI 配置直接在 ToolJet 界面填写 SMTP 参数适合简单场景配置结果存储在实例设置中环境变量配置通过.env文件注入 SMTP 参数灵活性和安全性更高适合在生产环境管理敏感凭据。两种方式都服务于同一个目标——确保 ToolJet 实例能按需发送邮件你可以根据部署偏好与安全要求任选其一。前置条件开始配置前请确认已具备以下条件拥有 ToolJet 的Super Admin超级管理员权限已从邮件服务商处获取SMTP 服务器信息主机名、端口、账号、密码等。方式一通过 GUI 配置 SMTPGUI 方式的操作路径非常直接共 5 步进入 ToolJet 的Settings设置区域选择Email protocol (SMTP)标签页打开开关启用 Email protocol (SMTP)填写以下配置字段字段说明示例HostSMTP 服务器主机名smtp.gmail.comPortSMTP 服务器端口号587UserSMTP 账号用户名hellojohndoe.techPasswordSMTP 账号密码a13d0sd344Senders email发件人邮箱地址hellojohndoe.tech点击Save changes保存更改应用新的 SMTP 配置。GUI 配置背后的接口与校验逻辑从源码可以确认GUI 保存的配置最终落在/smtp相关的 API 上。前端实例设置服务 对/smtp读取/更新 SMTP 设置、/smtp/env切换环境变量配置开关、/smtp/status启用/停用开关三个端点发起请求对应后端 SMTP 控制器 中由JwtAuthGuard与FeatureAbilityGuard保护的四个方法。提交的数据在 SMTP DTO 中经过严格校验host、port、user、password均为必填字符串且会经过sanitizeInput清洗fromEmail可选但必须通过IsEmail校验否则返回From email is invalid。这意味着 GUI 上任意一个必填项为空保存都会失败填写时应确保五项字段完整。方式二通过环境变量配置 SMTPToolJet 允许直接用环境变量完成 SMTP 配置。你只需在 Settings 的Email protocol (SMTP)页面开启Apply configuration from environment variables开关即可让配置直接从.env文件读取。文档给出的示例环境变量如下DEFAULT_FROM_EMAILhellotooljet.io SMTP_USERNAMEyour-username SMTP_PASSWORDyour-password SMTP_DOMAINsmtp.mailgun.org SMTP_PORT587 SMTP_SSLfalse SMTP_DISABLEDfalse各变量含义与 部署环境变量文档 中的表格一致环境变量作用DEFAULT_FROM_EMAIL发件人邮箱SMTP_USERNAMESMTP 登录用户名SMTP_PASSWORDSMTP 登录密码SMTP_DOMAINSMTP 服务器域名/主机SMTP_PORTSMTP 端口SMTP_SSL是否启用 SSLSMTP_DISABLED是否停用 SMTP 发信开关行为与源码对应关系新安装实例只要.env中配置了 SMTPApply configuration from environment variables开关默认即为开启状态开关开启时UI 中的 SMTP 字段会自动填充来自环境变量的值并变为只读开关关闭时可以手动在 UI 中填写或编辑 SMTP 设置。这一行为在源码中有明确对应。实例系统设置默认值定义于 instance-settings 常量SMTP_ENV_CONFIGURED默认即为true同时SMTP_ENABLED由SMTP_DISABLED true ? false : true推导而来——即只有在.env里显式设置SMTP_DISABLEDtrue时才会停用 SMTP。当开关开启时SMTPUtilService.getSmtpEnv 会直接返回默认实例设置即环境变量中的值跳过数据库中的实例配置当开关关闭时则返回数据库中保存的 UI 配置。这正是UI 只读与手动编辑两种状态的切换机制。发送链路中的实际取用逻辑环境变量与 UI 配置的取舍在真正发信时还会再做一次判断。邮件工具服务 mailTransport 中当SMTP_ENV_CONFIGURED true时host、port、username、password全部从ConfigService读取即.env否则从实例设置UI 配置读取。一个值得注意的实现细节SMTP_SSL环境变量本身并未被直接消费transport 的secure参数是由port 465推导得出的——端口为 465 时启用 SSL/TLS其他端口如 587则走 STARTTLS 加密。配置时请确保端口与加密方式匹配邮件服务商的约定。版本升级说明v2.62.0 及之后如果你是从 v2.62.0 之前的版本升级而来旧版.env中的 SMTP 变量会被自动映射到 UI无需重新手动填写。需要注意的是参见 部署环境变量文档从 v2.62.0 起企业版Enterprise Edition的 SMTP 配置不再从.env文件读取必须通过 UI 完成配置确认 UI 配置无误后可以从.env中安全移除这些变量。而社区版Community Edition仍可通过上述环境变量完成配置。也就是说本文介绍的两种方式中环境变量方式对社区版始终有效企业版则以 GUI 方式为准。邮件发送的完整链路源码视角理解配置之后再看 ToolJet 实际如何发信有助于排查配置正确但收不到邮件的问题。核心实现在 EmailUtilService.sendEmail流程如下收件人过滤若配置了FILTERED_DOMAINS_FOR_EMAIL匹配到这些域名的收件人会被直接跳过常用于测试环境模板渲染使用 Handlebars 编译mails/base/base_template.hbs及header/footer/body局部模板生成 HTML 邮件正文发送决策测试环境NODE_ENV test直接跳过发送开发环境且 SMTP 未启用时不真正发信而是把邮件内容打印到控制台并调用preview-email在本地预览其余情况通过nodemailer的createTransport建立真实连接发送发件人组装from字段格式为白标文本 DEFAULT_FROM_EMAIL发件人地址由SMTP_FROM_EMAIL决定——当SMTP_ENV_CONFIGURED true时取DEFAULT_FROM_EMAIL否则取 UI 中保存的 Senders email默认回退为hellotooljet.io。因此排查问题时可以按序确认实例是否启用 SMTPSMTP_ENABLED、环境变量开关状态SMTP_ENV_CONFIGURED、DEFAULT_FROM_EMAIL是否被收件方过滤以及端口/加密方式是否与邮件服务商一致。常见邮件服务商参数参考为了快速上手仓库还提供了常用邮件服务商的通用参数对照详见 常用邮件服务商文档服务商HostPort用户名密码Gmailsmtp.gmail.com587 或 465 (SSL)邮箱密码Yahoo Mailsmtp.mail.yahoo.com465 (SSL)邮箱密码Outlook.com/Hotmailsmtp.office365.com587 或 465 (SSL)邮箱密码Zoho Mailsmtp.zoho.com587 或 465 (SSL)邮箱密码SendGridsmtp.sendgrid.net587 或 465 (SSL)apikeyAPI keyMailgunsmtp.mailgun.org587 或 465 (SSL)SMTP username密码两个典型特例SendGrid用户名字段固定填apikey密码字段填生成的 API Key在 SendGrid 控制台 Settings → API Keys 页面生成MailgunSMTP 用户名需从 Domain Settings 页面的 SMTP Credentials 标签页获取密码为 Mailgun 账号密码。小结ToolJet 的 SMTP 配置为自托管实例提供了 GUI 与环境变量两条等价路径前者适合快速上手与集中管理后者更适合生产环境的自动化与凭据安全从 v2.62.0 起两者通过Apply configuration from environment variables开关联动源码层面则由SMTP_ENV_CONFIGURED统一裁决。配置完成后邀请、密码重置与通知邮件即可经由你指定的邮件服务器稳定送达。若需进一步排查可重点核对SMTP_ENABLED、SMTP_ENV_CONFIGURED与端口加密匹配情况并在开发环境下利用邮件预览输出快速验证配置正确性。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ToolJet 自托管 SMTP 邮件配置指南通过 GUI 与环境变量两种方式接入自定义邮件服务【免费下载链接】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/ToolJetToolJet 的 SMTP 配置功能专属于自托管self-hosted部署形态允许实例管理员接入自选邮件服务器用于发送邀请邮件、密码重置请求与各类通知。本文基于官方配置文档结合仓库中 服务端 SMTP 模块 与 邮件发送实现 的源码系统讲解在 ToolJet 中完成 SMTP 配置的两种方式GUI 与环境变量并深入说明配置项背后的校验逻辑与发送链路帮助你按需搭建可用的邮件基础设施。功能定位与适用场景SMTP 配置是自托管 ToolJet 实例的基础能力之一其核心用途是让 ToolJet 通过你自己的邮件服务器对外发信典型场景包括向新成员发送工作区邀请邮件处理密码重置请求发送平台运行相关的通知邮件。ToolJet 提供了两种等价的配置路径GUI 配置直接在 ToolJet 界面填写 SMTP 参数适合简单场景配置结果存储在实例设置中环境变量配置通过.env文件注入 SMTP 参数灵活性和安全性更高适合在生产环境管理敏感凭据。两种方式都服务于同一个目标——确保 ToolJet 实例能按需发送邮件你可以根据部署偏好与安全要求任选其一。前置条件开始配置前请确认已具备以下条件拥有 ToolJet 的Super Admin超级管理员权限已从邮件服务商处获取SMTP 服务器信息主机名、端口、账号、密码等。方式一通过 GUI 配置 SMTPGUI 方式的操作路径非常直接共 5 步进入 ToolJet 的Settings设置区域选择Email protocol (SMTP)标签页打开开关启用 Email protocol (SMTP)填写以下配置字段字段说明示例HostSMTP 服务器主机名smtp.gmail.comPortSMTP 服务器端口号587UserSMTP 账号用户名hellojohndoe.techPasswordSMTP 账号密码a13d0sd344Senders email发件人邮箱地址hellojohndoe.tech点击Save changes保存更改应用新的 SMTP 配置。GUI 配置背后的接口与校验逻辑从源码可以确认GUI 保存的配置最终落在/smtp相关的 API 上。前端实例设置服务 对/smtp读取/更新 SMTP 设置、/smtp/env切换环境变量配置开关、/smtp/status启用/停用开关三个端点发起请求对应后端 SMTP 控制器 中由JwtAuthGuard与FeatureAbilityGuard保护的四个方法。提交的数据在 SMTP DTO 中经过严格校验host、port、user、password均为必填字符串且会经过sanitizeInput清洗fromEmail可选但必须通过IsEmail校验否则返回From email is invalid。这意味着 GUI 上任意一个必填项为空保存都会失败填写时应确保五项字段完整。方式二通过环境变量配置 SMTPToolJet 允许直接用环境变量完成 SMTP 配置。你只需在 Settings 的Email protocol (SMTP)页面开启Apply configuration from environment variables开关即可让配置直接从.env文件读取。文档给出的示例环境变量如下DEFAULT_FROM_EMAILhellotooljet.io SMTP_USERNAMEyour-username SMTP_PASSWORDyour-password SMTP_DOMAINsmtp.mailgun.org SMTP_PORT587 SMTP_SSLfalse SMTP_DISABLEDfalse各变量含义与 部署环境变量文档 中的表格一致环境变量作用DEFAULT_FROM_EMAIL发件人邮箱SMTP_USERNAMESMTP 登录用户名SMTP_PASSWORDSMTP 登录密码SMTP_DOMAINSMTP 服务器域名/主机SMTP_PORTSMTP 端口SMTP_SSL是否启用 SSLSMTP_DISABLED是否停用 SMTP 发信开关行为与源码对应关系新安装实例只要.env中配置了 SMTPApply configuration from environment variables开关默认即为开启状态开关开启时UI 中的 SMTP 字段会自动填充来自环境变量的值并变为只读开关关闭时可以手动在 UI 中填写或编辑 SMTP 设置。这一行为在源码中有明确对应。实例系统设置默认值定义于 instance-settings 常量SMTP_ENV_CONFIGURED默认即为true同时SMTP_ENABLED由SMTP_DISABLED true ? false : true推导而来——即只有在.env里显式设置SMTP_DISABLEDtrue时才会停用 SMTP。当开关开启时SMTPUtilService.getSmtpEnv 会直接返回默认实例设置即环境变量中的值跳过数据库中的实例配置当开关关闭时则返回数据库中保存的 UI 配置。这正是UI 只读与手动编辑两种状态的切换机制。发送链路中的实际取用逻辑环境变量与 UI 配置的取舍在真正发信时还会再做一次判断。邮件工具服务 mailTransport 中当SMTP_ENV_CONFIGURED true时host、port、username、password全部从ConfigService读取即.env否则从实例设置UI 配置读取。一个值得注意的实现细节SMTP_SSL环境变量本身并未被直接消费transport 的secure参数是由port 465推导得出的——端口为 465 时启用 SSL/TLS其他端口如 587则走 STARTTLS 加密。配置时请确保端口与加密方式匹配邮件服务商的约定。版本升级说明v2.62.0 及之后如果你是从 v2.62.0 之前的版本升级而来旧版.env中的 SMTP 变量会被自动映射到 UI无需重新手动填写。需要注意的是参见 部署环境变量文档从 v2.62.0 起企业版Enterprise Edition的 SMTP 配置不再从.env文件读取必须通过 UI 完成配置确认 UI 配置无误后可以从.env中安全移除这些变量。而社区版Community Edition仍可通过上述环境变量完成配置。也就是说本文介绍的两种方式中环境变量方式对社区版始终有效企业版则以 GUI 方式为准。邮件发送的完整链路源码视角理解配置之后再看 ToolJet 实际如何发信有助于排查配置正确但收不到邮件的问题。核心实现在 EmailUtilService.sendEmail流程如下收件人过滤若配置了FILTERED_DOMAINS_FOR_EMAIL匹配到这些域名的收件人会被直接跳过常用于测试环境模板渲染使用 Handlebars 编译mails/base/base_template.hbs及header/footer/body局部模板生成 HTML 邮件正文发送决策测试环境NODE_ENV test直接跳过发送开发环境且 SMTP 未启用时不真正发信而是把邮件内容打印到控制台并调用preview-email在本地预览其余情况通过nodemailer的createTransport建立真实连接发送发件人组装from字段格式为白标文本 DEFAULT_FROM_EMAIL发件人地址由SMTP_FROM_EMAIL决定——当SMTP_ENV_CONFIGURED true时取DEFAULT_FROM_EMAIL否则取 UI 中保存的 Senders email默认回退为hellotooljet.io。因此排查问题时可以按序确认实例是否启用 SMTPSMTP_ENABLED、环境变量开关状态SMTP_ENV_CONFIGURED、DEFAULT_FROM_EMAIL是否被收件方过滤以及端口/加密方式是否与邮件服务商一致。常见邮件服务商参数参考为了快速上手仓库还提供了常用邮件服务商的通用参数对照详见 常用邮件服务商文档服务商HostPort用户名密码Gmailsmtp.gmail.com587 或 465 (SSL)邮箱密码Yahoo Mailsmtp.mail.yahoo.com465 (SSL)邮箱密码Outlook.com/Hotmailsmtp.office365.com587 或 465 (SSL)邮箱密码Zoho Mailsmtp.zoho.com587 或 465 (SSL)邮箱密码SendGridsmtp.sendgrid.net587 或 465 (SSL)apikeyAPI keyMailgunsmtp.mailgun.org587 或 465 (SSL)SMTP username密码两个典型特例SendGrid用户名字段固定填apikey密码字段填生成的 API Key在 SendGrid 控制台 Settings → API Keys 页面生成MailgunSMTP 用户名需从 Domain Settings 页面的 SMTP Credentials 标签页获取密码为 Mailgun 账号密码。小结ToolJet 的 SMTP 配置为自托管实例提供了 GUI 与环境变量两条等价路径前者适合快速上手与集中管理后者更适合生产环境的自动化与凭据安全从 v2.62.0 起两者通过Apply configuration from environment variables开关联动源码层面则由SMTP_ENV_CONFIGURED统一裁决。配置完成后邀请、密码重置与通知邮件即可经由你指定的邮件服务器稳定送达。若需进一步排查可重点核对SMTP_ENABLED、SMTP_ENV_CONFIGURED与端口加密匹配情况并在开发环境下利用邮件预览输出快速验证配置正确性。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
