产品定价 立即试用
云平台
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
欧洲地区
北美地区 弗吉尼亚北部区域 欧洲地区 法兰克福区域
文档 > 管理用户界面 > 邮件服务器
入门
指南 API 常见问题
目录

邮件服务器配置

本文档提供在ThingsBoard中配置邮件服务器的分步说明。 使用邮件可发送通知、密码找回消息、定时报告及其他重要系统消息。

默认情况下，若未配置租户邮件服务器，系统将使用系统管理员层级的邮件服务器设置。但需要自定义邮件配置（如公司专用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”完成邮件服务器配置。

Go to the "Mail server" tab of the "Settings" page. Uncheck the "Use System Mail Server Settings" option to configure your own mail server settings;
Go to the "Mail server" tab of the "Settings" page. Uncheck the "Use System Mail Server Settings" option to configure your own mail server settings;
Fill in the "Mail From" field, select an SMTP provider, and proceed to the connection settings: choose the SMTP protocol, specify host and port of the SMTP server, and set the timeout;
Fill in the "Mail From" field, select an SMTP provider, and proceed to the connection settings: choose the SMTP protocol, specify host and port of the SMTP server, and set the timeout;
Optionally, enable TLS and Proxy;
Optionally, enable TLS and Proxy;
Enter credentials for SMTP authentication. Use either the "Basic" or "OAuth 2.0" authentication method. Now, you can send a test email to verify the settings. Finally, click "Save" to complete the mail server configuration.
Enter credentials for SMTP authentication. Use either the "Basic" or "OAuth 2.0" authentication method. Now, you can send a test email to verify the settings. Finally, click "Save" to complete the mail server configuration.

邮件服务器设置示例

自ThingsBoard 3.5.2起，新增了以下提供商的邮件设置模板：Sendgrid、Gmail和Office 365。 因此用户无需手动填写SMTP服务器主机、端口和TLS等连接设置。 若需使用其他SMTP服务器，请选择SMTP提供商类型“Custom”。

Sendgrid配置示例

SendGrid配置相对简单直接。首先需创建 SendGrid 账户。 可免费试用，免费套餐通常足以进行平台评估。

ㅤ1. 设置SendGrid配置

  • Once you create your account, you will be forwarded to the welcome page. Click "Start" button;
  • Go to the "Email API" section -> "Integration Guide" page and choose a setup method - "SMTP Relay";
  • Create an API key: enter the API key name and generate it.
Once you create your account, you will be forwarded to the welcome page. Click "Start" button;
Once you create your account, you will be forwarded to the welcome page. Click "Start" button;
Go to the "Email API" section -> "Integration Guide" page and choose a setup method - "SMTP Relay";
Go to the "Email API" section -> "Integration Guide" page and choose a setup method - "SMTP Relay";
Create an API key: enter the API key name and generate it.
Create an API key: enter the API key name and generate it.

ㅤ2. 设置ThingsBoard邮件服务器

在ThingsBoard实例中进入“Settings”页面 -> “Mail Server”选项卡并填写表单：

  • 填写“Mail From”字段；
  • 选择SMTP提供商 - SendGrid；
  • 输入用户名：apikey；
  • 输入密码：此前生成的密码。

点击“Save”按钮。

image


ㅤ3. 发送测试邮件

可选，可在邮箱接收测试邮件。 若配置有误，将收到包含错误日志的弹窗。

您也可在SendGrid网站上完成验证。

image

使用基本身份验证的Gmail配置示例

要使用Gmail，需启用两步验证（非强制，但强烈建议）并生成应用密码。

ㅤ1. 设置Google账户配置

  • Go to your Google Account and navigate to the "Security" page. Then select "2-Step Verification" tab;
  • At the bottom of the page, select "App passwords";
  • Click on the "Select app" and select "Other" app in the drop-down menu;
  • Enter app name and click "Generate" button;
  • Copy and save app password.
Go to your Google Account and navigate to the "Security" page. Then select "2-Step Verification" tab;
Go to your Google Account and navigate to the "Security" page. Then select "2-Step Verification" tab;
At the bottom of the page, select "App passwords";
At the bottom of the page, select "App passwords";
Click on the "Select app" and select "Other" app in the drop-down menu;
Click on the "Select app" and select "Other" app in the drop-down menu;
Enter app name and click "Generate" button;
Enter app name and click "Generate" button;
Copy and save app password.
Copy and save app password.

ㅤ2. 设置ThingsBoard邮件服务器

准备就绪后，可使用以下信息配置邮件服务器。 在ThingsBoard实例中进入“Settings”页面 -> “Mail Server”选项卡并填写表单：

  • 填写“Mail From”字段；
  • 选择SMTP提供商 - Google；
  • 输入您的邮箱作为用户名；
  • 保持basic身份验证类型；
  • 输入此前复制的应用密码。

点击“Save”按钮。

image


ㅤ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项目凭据时需要用到。

image


ㅤ2. 在 Google Developers Console 创建项目

  • Input “Project name” and “Location”. Then click “Create”. New project is created.
Input “Project name” and “Location”. Then click “Create”. New project is created.
Input “Project name” and “Location”. Then click “Create”. New project is created.

ㅤ3. 创建凭据

  • Select created project and navigate to the "APIs & Services" page;
  • Click on the "Credentials" tab, then click on the "Create Credentials" button and select "OAuth client ID";
  • In a "Create OAuth client ID" window select application type - "Web application" and input the name of your OAuth2 client. Then, in the "Authorized redirect URIs" section, click the "+ Add URI" button and paste the previously copied "Redirect URI template". Click "Create";
  • Save created client ID and client secret for future steps.
Select created project and navigate to the "APIs & Services" page;
Select created project and navigate to the "APIs & Services" page;
Click on the "Credentials" tab, then click on the "Create Credentials" button and select "OAuth client ID";
Click on the "Credentials" tab, then click on the "Create Credentials" button and select "OAuth client ID";
In a "Create OAuth client ID" window select application type - "Web application" and input the name of your OAuth2 client. Then, in the "Authorized redirect URIs" section, click the "+ Add URI" button and paste the previously copied "Redirect URI template". Click "Create";
In a "Create OAuth client ID" window select application type - "Web application" and input the name of your OAuth2 client. Then, in the "Authorized redirect URIs" section, click the "+ Add URI" button and paste the previously copied "Redirect URI template". Click "Create";
Save created client ID and client secret for future steps.
Save created client ID and client secret for future steps.


ㅤ4. 完成ThingsBoard设置

返回Thingsboard门户，将此前步骤的 Client ID 和 Client secret 粘贴到对应字段。点击“Save”。

image


ㅤ5. 生成访问令牌

最后，可获取访问令牌。点击 Generate access token，浏览器将重定向至提供商登录页。 请按浏览器中的步骤操作，授权后系统将自动保存Refresh Token和Access Token并重定向回ThingsBoard门户。 若成功生成访问令牌，将看到状态“generated”。

image


ㅤ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用户并复制用户主体名称。
Sign in to the Azure portal and select Microsoft Entra ID;
Sign in to the Azure portal and select Microsoft Entra ID;
Select microsoft user and copy user principal name.
Select microsoft user and copy user principal name.

要使用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凭据时需要用到。

image


ㅤ2. 在Azure portal注册应用：

  • Under the "Manage" section select the "App registrations" page, and click the "New registration" button;
  • Enter a name for your application and paste the previously copied "Redirect URI template". Click the "Register" button;
  • After application is created you can find "Client ID" and "Directory (tenant) ID" on "Overview" page. Save them for future steps.
Under the "Manage" section select the "App registrations" page, and click the "New registration" button;
Under the "Manage" section select the "App registrations" page, and click the "New registration" button;
Enter a name for your application and paste the previously copied "Redirect URI template". Click the "Register" button;
Enter a name for your application and paste the previously copied "Redirect URI template". Click the "Register" button;
After application is created you can find "Client ID" and "Directory (tenant) ID" on "Overview" page. Save them for future steps.
After application is created you can find "Client ID" and "Directory (tenant) ID" on "Overview" page. Save them for future steps.


ㅤ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.
Select "Certificates & secrets" > "Client secrets" > click "New client secret" button;
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";
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.
Save client secret value for future step.


ㅤ4. 为SMTP添加API权限以完成身份验证设置：

  • In the Azure portal go to “API permissions” page and click “Add a permission” button;
  • Select an API - "Microsoft Graph";
  • Select type of permissions - "Delegated permissions";
  • Search and check the box “SMTP.Send” permission. Then click “Add permissions” button;
  • Permissions is updated.
In the Azure portal go to “API permissions” page and click “Add a permission” button;
In the Azure portal go to “API permissions” page and click “Add a permission” button;
Select an API - "Microsoft Graph";
Select an API - "Microsoft Graph";
Select type of permissions - "Delegated permissions";
Select type of permissions - "Delegated permissions";
Search and check the box “SMTP.Send” permission. Then click “Add permissions” button;
Search and check the box “SMTP.Send” permission. Then click “Add permissions” button;
Permissions is updated.
Permissions is updated.


ㅤ5. 完成ThingsBoard设置：

返回ThingsBoard门户，将此前步骤的 Client ID、Client secret 和 Directory (tenant) ID 粘贴到对应字段。点击“Save”。

image


ㅤ6. 生成访问令牌：

最后，可获取访问令牌。点击“Generate access token”按钮，浏览器将重定向至提供商登录页。请按浏览器中的步骤操作， 授权后系统将自动保存Refresh Token和Access Token并重定向回ThingsBoard门户。 若成功生成访问令牌，将看到状态“generated”。

image


ㅤ7. 发送测试邮件：

点击“Send test email”按钮检查是否正常。请注意，每次更改提供商信息时系统会清除refresh和access token，需重新生成。


Office 365故障排查

若发送邮件时出现身份验证错误（如5.7.3）：

  1. 确认已为用户启用SMTP设置。前往此处。选择用户 → Mail → Manage email apps → Authenticate SMTP（若已启用，先禁用再启用）；
  2. 在Azure portal中确认已禁用Security defaults。

后续步骤