本文档提供在ThingsBoard中配置邮件服务器的分步说明。 使用邮件可发送通知、密码找回消息、定时报告及其他重要系统消息。
ThingsBoard支持在两个层级配置邮件服务器：
- 系统管理员层级 – 定义适用于所有租户的全局SMTP设置（除非被覆盖）。
- 租户管理员层级 – 允许各租户设置自己的SMTP，需要时可覆盖全局配置。
默认情况下，若未配置租户邮件服务器，系统将使用系统管理员层级的邮件服务器设置。但需要自定义邮件配置（如公司专用SMTP服务器）的租户可定义自己的设置。
邮件服务器配置
配置邮件服务器设置需执行以下步骤：
步骤1. 登录ThingsBoard实例WEB UI；
步骤2. 进入“Settings”页面的“Mail server”选项卡。若以系统管理员身份登录，将直接进入邮件服务器设置。若以租户管理员身份登录，需取消勾选“Use System Mail Server Settings”以配置自己的邮件服务器设置；
步骤3. 邮件服务器配置：
- 填写“Mail From”字段；
- 选择SMTP提供商；
- 进入连接设置：
- 选择SMTP协议；
- 指定SMTP服务器主机和端口；
- 设置超时；
- 可选：启用TLS和Proxy；
- 身份验证：输入SMTP身份验证凭据。使用“Basic”或“OAuth 2.0”身份验证方式。
步骤4. 可发送测试邮件验证设置；
步骤5. 最后，点击“Save”完成邮件服务器配置。
邮件服务器设置示例
自ThingsBoard 3.5.2起，新增了以下提供商的邮件设置模板：Sendgrid、Gmail和Office 365。 因此用户无需手动填写SMTP服务器主机、端口和TLS等连接设置。 若需使用其他SMTP服务器，请选择SMTP提供商类型“Custom”。
Sendgrid配置示例
SendGrid配置相对简单直接。首先需创建 SendGrid 账户。 可免费试用，免费套餐通常足以进行平台评估。
ㅤ1. 设置SendGrid配置
- 创建账户后将跳转至欢迎页。点击"Start"按钮；
- 进入"Email API"部分->"Integration Guide"页面，选择设置方法-"SMTP Relay"；
- 创建API密钥：输入API密钥名称并生成。
ㅤ2. 设置ThingsBoard邮件服务器
在ThingsBoard实例中进入“Settings”页面 -> “Mail Server”选项卡并填写表单：
- 填写“Mail From”字段；
- 选择SMTP提供商 - SendGrid；
- 输入用户名：apikey；
- 输入密码：此前生成的密码。
点击“Save”按钮。
ㅤ3. 发送测试邮件
可选，可在邮箱接收测试邮件。 若配置有误，将收到包含错误日志的弹窗。
您也可在SendGrid网站上完成验证。
使用基本身份验证的Gmail配置示例
要使用Gmail，需启用两步验证（非强制，但强烈建议）并生成应用密码。
ㅤ1. 设置Google账户配置
- 进入您的Google账户，导航至"Security"页面。然后选择"2-Step Verification"选项卡；
- 在页面底部选择"App passwords"；
- 点击"Select app"并在下拉菜单中选择"Other"应用；
- 输入应用名称并点击"Generate"按钮；
- 复制并保存应用密码。
ㅤ2. 设置ThingsBoard邮件服务器
准备就绪后，可使用以下信息配置邮件服务器。 在ThingsBoard实例中进入“Settings”页面 -> “Mail Server”选项卡并填写表单：
- 填写“Mail From”字段；
- 选择SMTP提供商 - Google；
- 输入您的邮箱作为用户名；
- 保持basic身份验证类型；
- 输入此前复制的应用密码。
点击“Save”按钮。
ㅤ3. 发送测试邮件
可选，可在邮箱接收测试邮件。 若配置有误，将收到包含错误日志的弹窗。
使用OAuth2身份验证的Gmail配置示例
自ThingsBoard 3.5.2起，支持对Gmail SMTP服务器使用OAuth2授权。 使用OAuth 2.0协议，用户可通过Gmail Web OAuth进行身份验证，而无需在应用中直接输入用户名和密码。 此方式更安全，但稍复杂。
要使用Gmail OAuth2，需在Google Developers Console创建项目，但先设置ThingsBoard邮件服务器。
ㅤ1. 设置ThingsBoard邮件服务器
- 在ThingsBoard实例中，进入“Settings”页面 -> “Mail Server”选项卡；
- 填写“mail From”字段；
- 选择SMTP提供商 - “Google”；
- 在“Authentication”块中，使用将用于发送邮件的邮箱地址填写用户名；
- 将身份验证类型切换为 OAuth2；
- 复制并保存“Redirect URI template”。设置Google项目凭据时需要用到。
ㅤ2. 在 Google Developers Console 创建项目
- 输入"Project name"和"Location"。然后点击"Create"。新项目已创建。
ㅤ3. 创建凭据
- 选择已创建的项目并导航至"APIs & Services"页面；
- 点击"Credentials"选项卡，然后点击"Create Credentials"按钮并选择"OAuth client ID"；
- 在"Create OAuth client ID"窗口中选择应用类型-"Web application"并输入OAuth2客户端名称。然后在"Authorized redirect URIs"部分点击"+ Add URI"按钮并粘贴之前复制的"Redirect URI template"。点击"Create"；
- 保存创建的client ID和client secret以备后续步骤使用。
ㅤ4. 完成ThingsBoard设置
返回Thingsboard门户，将此前步骤的 Client ID 和 Client secret 粘贴到对应字段。点击“Save”。
ㅤ5. 生成访问令牌
最后，可获取访问令牌。点击 Generate access token，浏览器将重定向至提供商登录页。 请按浏览器中的步骤操作，授权后系统将自动保存Refresh Token和Access Token并重定向回ThingsBoard门户。 若成功生成访问令牌，将看到状态“generated”。
ㅤ6. 发送测试邮件
点击“Send test email”按钮检查是否正常。请注意，每次更改提供商信息时系统会清除refresh和access token，需重新生成。
使用OAuth2身份验证的Office 365配置示例
自ThingsBoard 3.6起，支持对Office 365 SMTP服务器使用OAuth2授权。
请注意：
OAuth 2.0仅支持Microsoft 365账户，不支持个人Outlook账户（如 @outlook.com或 @hotmail.com账户）。
首先，进入“Azure directory”保存用于发送邮件的用户主体名称（若不存在，请创建或从外部服务邀请）：
- 登录 Azure portal 并选择Microsoft Entra ID；
- 选择microsoft用户并复制用户主体名称。
要使用Office 365 OAuth2，需在Azure portal注册应用，但先设置ThingsBoard邮件服务器。
ㅤ1. 设置ThingsBoard邮件服务器：
- 在ThingsBoard实例中，进入“Settings”页面 -> “Mail Server”选项卡；
- 输入此前复制的Microsoft用户主体名称（如app_user@onmicrosoft.com）；
- 选择SMTP提供商 - “Office 365”；
- 在“Authentication”块中，使用与Mail From相同的Microsoft用户主体名称填写用户名；
- 将身份验证类型切换为 OAuth2；
- 复制并保存“Redirect URI template”。设置Azure portal凭据时需要用到。
ㅤ2. 在Azure portal注册应用：
- 在"Manage"部分选择"App registrations"页面，点击"New registration"按钮；
- 输入应用程序名称并粘贴之前复制的"Redirect URI template"。点击"Register"按钮；
- 应用创建后可在"Overview"页面找到"Client ID"和"Directory (tenant) ID"。保存以供后续步骤使用。
ㅤ3. 创建“Client secret”：
- Select "Certificates & secrets" > "Client secrets" > click "New client secret" button;
- Add a description for your client secret. Select an expiration for the secret or specify a custom lifetime. Click "Add";
- Save client secret value for future step.
ㅤ4. 为SMTP添加API权限以完成身份验证设置：
- 在Azure门户中进入"API permissions"页面，点击"Add a permission"按钮；
- 选择API-"Microsoft Graph"；
- 选择权限类型-"Delegated permissions"；
- 搜索并勾选"SMTP.Send"权限。然后点击"Add permissions"按钮；
- 权限已更新。
ㅤ5. 完成ThingsBoard设置：
返回ThingsBoard门户，将此前步骤的 Client ID、Client secret 和 Directory (tenant) ID 粘贴到对应字段。点击“Save”。
ㅤ6. 生成访问令牌：
最后，可获取访问令牌。点击“Generate access token”按钮，浏览器将重定向至提供商登录页。请按浏览器中的步骤操作， 授权后系统将自动保存Refresh Token和Access Token并重定向回ThingsBoard门户。 若成功生成访问令牌，将看到状态“generated”。
ㅤ7. 发送测试邮件：
点击“Send test email”按钮检查是否正常。请注意，每次更改提供商信息时系统会清除refresh和access token，需重新生成。
Office 365故障排查
若发送邮件时出现身份验证错误（如5.7.3）：
- 确认已为用户启用SMTP设置。前往此处。选择用户 → Mail → Manage email apps → Authenticate SMTP（若已启用，先禁用再启用）；
- 在Azure portal中确认已禁用Security defaults。