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 ⇾ Mail templates
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