本文档提供在ThingsBoard中配置邮件服务器的分步说明。 使用邮件可发送通知、密码找回消息、定时报告及其他重要系统消息。
ThingsBoard系统管理员定义全局邮件服务器设置，适用于所有客户。
邮件服务器配置
配置邮件服务器设置需执行以下步骤：
步骤1. 以系统管理员身份登录ThingsBoard实例WEB UI；
步骤2. 进入“Settings”页面的“Mail server”选项卡。将直接进入邮件服务器设置；
步骤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配置
- 创建您的帐户后，您将被转发到欢迎页面。点击"开始"按钮。
- 转到"电子邮件API"部分 -> "集成指南"页面，选择设置方法 - "SMTP中继"。
- 创建一个API密钥：输入API密钥名称并生成它。
ㅤ2. 设置ThingsBoard邮件服务器
在ThingsBoard实例中进入“Settings”页面 -> “Mail Server”选项卡并填写表单：
- 填写“Mail From”字段；
- 选择SMTP提供商 - SendGrid；
- 输入用户名：apikey；
- 输入密码：此前生成的密码。
点击“Save”按钮。
ㅤ3. 发送测试邮件
可选，可在邮箱接收测试邮件。 若配置有误，将收到包含错误日志的弹窗。
您也可在SendGrid网站上完成验证。
使用基本身份验证的Gmail配置示例
要使用Gmail，需启用两步验证（非强制，但强烈建议）并生成应用密码。
ㅤ1. 设置Google账户配置
- 转到您的Google帐户，导航到"安全"页面。然后选择"两步验证"选项卡。
- 在页面底部，选择"应用程序密码"。
- 点击"选择应用"，在下拉菜单中选择"其他"应用。
- 输入应用名称，点击"生成"按钮。
- 复制并保存应用密码。
ㅤ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 创建项目
- 输入"项目名称"和"位置"。然后点击"创建"。创建新项目。
ㅤ3. 创建凭据
- 选择创建的项目，导航到"API和服务"页面。
- 点击"凭据"选项卡，然后点击"创建凭据"按钮，选择"OAuth客户端ID"。
- 在"创建OAuth客户端ID"窗口中，选择应用程序类型 - "Web应用"并输入您的OAuth2客户端的名称。然后，在"授权的重定向URI"部分中，点击"+ 添加URI"按钮并粘贴之前复制的"重定向URI模板"。点击"创建"。
- 保存创建的客户端ID和客户端密钥以供以后使用。
ㅤ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注册应用：
- 在"管理"部分下，选择"应用注册"页面，然后点击"新注册"按钮。
- 为您的应用程序输入名称并粘贴之前复制的"重定向URI模板"。点击"注册"按钮。
- 创建应用程序后，可以在"概览"页面上找到"客户端ID"和"目录（租户）ID"。保存它们以供以后使用。
ㅤ3. 创建“Client secret”：
- 选择"证书和密钥" > "客户端密钥" >点击"新客户端密钥"按钮。
- 为您的客户端密钥添加描述。为密钥选择过期时间或指定自定义生命周期。点击"添加"。
- 保存客户端密钥值以供以后使用。
ㅤ4. 为SMTP添加API权限以完成身份验证设置：
- 在Azure门户中转到"API权限"页面，然后点击"添加权限"按钮。
- 选择一个API - "Microsoft Graph"。
- 选择权限类型 - "委派权限"。
- 搜索并勾选"SMTP。Send"权限复选框。然后点击"添加权限"按钮。
- 权限已更新。
ㅤ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。