Mail Server Settings

The mail server settings configure the outgoing SMTP server ThingsBoard uses to send emails — including notifications, user activation emails, password recovery messages, and scheduled reports.

Mail server settings can be configured at two levels:

• System administrator — defines global SMTP settings that apply to all tenants unless overridden.
• Tenant administrator — can override global settings with a custom SMTP configuration (e.g., a company-specific SMTP server).

If a tenant does not configure their own mail server, the system administrator's settings are used.

1. Navigate to Settings and open the Mail server tab. If you are a tenant administrator, uncheck Use System Mail Server Settings to configure your own.
2. Fill in the Mail From field (the sender address that appears in outgoing emails).
3. Select an SMTP provider (SendGrid, Google, Office 365, or Custom).
4. Configure connection settings:
   • SMTP protocol (SMTP or SMTPS)
   • SMTP host and port
   • Connection timeout
   • Optionally enable TLS and Proxy
5. Configure Authentication — either Basic (username + password) or OAuth 2.0 (available for Google and Office 365).
6. Click Send test email to verify the configuration.
7. Click Save.

Since ThingsBoard 3.5.2, built-in templates are available for SendGrid, Gmail, and Office 365. These auto-fill connection settings (host, port, TLS). For other providers, select Custom.

1. Set up SendGrid

1. Create a SendGrid account. On the welcome page, click Start.
2. Go to Email API > Integration Guide and choose SMTP Relay.
3. Create an API key: enter a name and click Generate.

2. Configure ThingsBoard

In ThingsBoard, go to Settings > Mail server. Select SMTP provider SendGrid. Enter username apikey and paste the generated API key as the password. Click Send test email to verify, then Save.

1. Generate a Google app password

1. Go to your Google Account Security page and select 2-Step Verification.
2. At the bottom of the page, select App passwords.
3. Select Other app from the dropdown.
4. Enter an app name and click Generate.
5. Copy the generated app password.

2. Configure ThingsBoard

In ThingsBoard, select SMTP provider Google. Enter your Gmail address as the username, keep authentication type Basic, and enter the app password. Click Send test email to verify, then Save.

1. Configure ThingsBoard (initial setup)

In ThingsBoard, select SMTP provider Google, enter your Gmail address as the username, and toggle authentication to OAuth2. Copy the Redirect URI template — you will need it when creating Google credentials.

2. Create a Google Cloud project

1. Go to the Google Developers Console. Enter a project name and click Create.

3. Create OAuth credentials

1. Select the project and navigate to APIs & Services.
2. Go to the Credentials tab, click Create Credentials, and select OAuth client ID.
3. Select application type Web application, enter a name, and in Authorized redirect URIs paste the redirect URI from step 1. Click Create.
4. Copy the Client ID and Client secret.

4. Complete ThingsBoard setup

Back in ThingsBoard, paste the Client ID and Client secret, then click Save. Click Generate access token — your browser will redirect to Google for authorization. After granting access, the tokens are saved automatically. Click Send test email to verify.

1. Copy the user principal name

Sign in to the Azure portal, open Microsoft Entra ID, select a user, and copy the User Principal Name.

2. Configure ThingsBoard (initial setup)

In ThingsBoard, select SMTP provider Office 365. Enter the user principal name as both Mail From and Username. Toggle authentication to OAuth2. Copy the Redirect URI template.

3. Register an application in Azure

1. In the Azure portal, go to App registrations and click New registration.
2. Enter a name, paste the Redirect URI (Web type) from step 2, and click Register.
3. On the Overview page, note the Client ID and Directory (tenant) ID.

4. Create a client secret

1. Go to Certificates & secrets > Client secrets and click New client secret.
2. Add a description, select an expiration, and click Add.
3. Copy the secret value.

5. Add SMTP API permissions

1. Go to API permissions and click Add a permission.
2. Select Microsoft Graph > Delegated permissions.
3. Search for and check SMTP.Send, then click Add permissions.
4. Click Grant admin consent.

6. Complete ThingsBoard setup

Back in ThingsBoard, paste the Client ID, Client secret, and Directory (tenant) ID, then click Save. Click Generate access token — your browser will redirect to Microsoft for authorization. After granting access, the tokens are saved automatically. Click Send test email to verify.

Office 365 troubleshooting:

If you see authentication errors (e.g., 5.7.3):

1. Ensure SMTP is enabled for the user: go to the Microsoft 365 admin center, select the user > Mail > Manage email apps > enable Authenticated SMTP (if already enabled, disable and re-enable).
2. In the Azure portal, ensure Security defaults are disabled.

The Send Email on Alarm recipe walks through the full setup: configuring notification recipients, creating an alarm notification template with email delivery, and setting up a rule that sends an email when an alarm is created.