White-labeling: Mail Templates

ThingsBoard uses mail templates to send email notifications when certain events occur — for example, account activation or password reset. The platform provides default templates that you can customize for each tenant or customer.

1. Navigate to the White labeling page and open the Mail templates tab.
2. Uncheck the Use system mail templates box to enable editing.
3. Select the mail template you want to edit from the drop-down list.
4. Edit the mail subject and mail body as needed.
5. Click Save.

The following mail templates are available for customization:

Template	Triggered when	Available placeholders
Test email message	An administrator sends a test email while configuring the outgoing mail server	${targetEmail}
Account activation message	A new user is created and receives an activation link	${activationLink}, ${activationLinkTtlInHours}, ${targetEmail}
Account activated message	A user successfully activates their account	${loginLink}, ${targetEmail}
Account lockout message	A user’s account is locked due to too many failed login attempts	${lockoutAccount}, ${maxFailedLoginAttempts}, ${targetEmail}
Reset password message	A user requests a password reset	${passwordResetLink}, ${passwordResetLinkTtlInHours}, ${targetEmail}
Password was reset message	A user’s password has been successfully changed	${loginLink}, ${targetEmail}
2FA verification message	A 2FA code is sent to the user	${code}, ${expirationTimeSeconds}, ${targetEmail}

The mail body is processed as a template, so it supports placeholders written as ${placeholderName}. The platform substitutes them with actual values before sending the email. The mail subject is sent as plain text — placeholders in the subject are not substituted.

Use only the placeholders listed for the given template above.

Placeholder	Substituted with
${targetEmail}	Email address the message is sent to
${activationLink}	One-time link the user opens to activate their account
${activationLinkTtlInHours}	Lifetime of the activation link, in hours (rounded up)
${loginLink}	Link to the platform login page
${lockoutAccount}	Email address of the account that has been locked out
${maxFailedLoginAttempts}	Number of failed login attempts that triggers the lockout
${passwordResetLink}	One-time link the user opens to set a new password
${passwordResetLinkTtlInHours}	Lifetime of the password reset link, in hours (rounded up)
${code}	Two-factor authentication verification code
${expirationTimeSeconds}	Lifetime of the 2FA verification code, in seconds