Docs
Contents

Email Templates

Feature Overview

Email Templates customize authentication notifications and verification emails (route: /console/project-{region}-{project}/auth/templates), including email verification, magic links, one-time passcodes, password recovery, team invitations, multi-factor authentication, and session alerts. Session alerts are queued only when the trigger conditions are met; they do not detect whether a device is new. Delivery depends on queue processing and the mail service.

By combining the project-level custom SMTP service with the Auth → Templates multilingual template editor, enterprises can fully replace the sender name, sender email address, reply-to address, subject, and HTML/plain-text message body of all emails sent to end users with their own brand visuals and compliant messaging, completely eliminating the unfamiliarity caused by generic platform default sending domains and significantly improving email open rates and trust-driven conversion among enterprise customers.

Email template notice when custom SMTP is disabled

Custom SMTP is disabled in the test project; no configuration was saved and no email was sent.


Core Concepts and Architecture

The Agentbase email template engine uses a pipeline architecture of "project-level custom SMTP gating → event type routing → locale matching → secure injection of double-brace variables ({{variable}}) → asynchronous queue delivery".

Core concepts and version boundary notes

Core conceptDetailed description and technical constraints
Custom SMTP as a mandatory prerequisite gateThe mandatory prerequisite for customizing any email template is enabling and configuring a valid custom SMTP server under the project's Settings → SMTP. When custom SMTP is not enabled, the top of the Auth → Templates page shows the notice "Custom SMTP server is required for customizing emails", sender fields of all templates are disabled, and bodies are read-only.
7 standard email templatesCovering the full chain of authentication and security alerts: Verification, Magic URL, OTP session, Reset password, Invite user, 2FA verification, and Session alert.
Independent multilingual storage (Template language)Each template type supports independent editing and saving per language code (default en, with support for switching to zh-CN and other languages). When the client initiates a request, the server selects the template in the corresponding language based on the current request's Locale for rendering.
Dynamic template variables ({{...}})Double-brace syntax (e.g., {{user}}, {{project}}, {{redirect}}, {{otp}}) injects real context at send time. The set of variables supported by each template type is strictly fixed; undeclared variables cannot be mixed across templates.
Factual note on SMS Templates version supportAlthough components for SMS templates (for invitations, verification, and login) are reserved in the underlying frontend repository source code, the current Console's Auth → Templates page only mounts and exposes the above 7 email templates; no SMS template editor is mounted in the UI.

Roles, Entry Points, and Relationships

Console Entry Point and Permission Requirements

Relationships with Other Modules

  1. Project Settings → SMTP: SMTP server connectivity directly determines whether template emails can be delivered successfully. Once custom SMTP is enabled, all Auth-triggered system emails within the project are switched to that SMTP channel for delivery.

  2. Team management (Auth Teams): When inviting members to team_support_ops (VIP customer technical support group) via the client, the Invite user template is triggered, replacing {{team}} with VIP客户技术支持组 and {{redirect}} with the invitation confirmation redirect URL.

  3. Security policy (Auth Security): When the security policy has the Session alerts toggle enabled, the Session alert template is used to queue email only when the session alert conditions are met; actual delivery depends on the mail service; when a user uses email as the MFA second factor, the 2FA verification template is triggered.


Feature Details and Operation Guide

1. Prerequisites: Enable project-level Custom SMTP

Before editing Auth → Templates, please complete the custom SMTP configuration first:

  1. At the bottom of the left navigation in project enterprise-ai-hub-210, click Settings (or click SMTP settings from the banner at the top of Auth → Templates).

  2. Locate the SMTP configuration card and turn on the Custom SMTP server toggle.

  3. Fill in the enterprise email service parameters:

    • Sender name: The default sender name, e.g. Agentbase 企业智能客服中心.

    • Sender email: The default sender email address, e.g. no-reply@enterprise.example.com (must match the SMTP authentication account or an authorized sending domain).

    • Reply to: The default reply-to inbox, e.g. support@enterprise.example.com.

    • Server host: The SMTP server domain, e.g. smtpdm.aliyun.com or smtp.office365.com.

    • Port: The SMTP port; commonly 465 (SSL/TLS) or 587 (STARTTLS).

    • Username / Password: The SMTP sending authentication account and authorization code (the password is stored in a <SMTP_PASSWORD> securely managed way, encrypted on the server side).

    • Secure protocol: Select TLS or SSL.

  4. Click Update to save the SMTP settings. After saving, return to the Auth → Templates page, and all template input boxes will become editable.

2. The Seven Email Template Types and the Complete Set of Available Variables

On the Auth → Templates page, each template differs in trigger timing and supported dynamic variables. The table below lists, for all 7 email templates, the trigger scenarios, the key variables that must be retained, and descriptions of all available variables:

Template nameTrigger scenario and corresponding API / operationList of available template variablesCore variables to retain and pitfalls to avoid
Verification (email verification)Triggered after user registration or when the user actively requests email verification (client calls account.createVerification(url)){{user}}, {{project}}, {{redirect}}You must retain {{redirect}}: this variable carries the complete email verification confirmation URL containing the encrypted Token; if {{redirect}} is accidentally deleted from the body, the recipient will be unable to click through to complete email verification.
Magic URL (magic link login)Triggered when the user signs in with a passwordless Magic URL (client calls account.createMagicURLToken(userId, email, url)){{user}}, {{project}}, {{redirect}}, {{agentClient}}, {{agentDevice}}, {{agentOs}}You must retain {{redirect}}: after clicking this link, the recipient is redirected back to the application frontend and the session is created. You may display {{agentClient}} and {{agentOs}} in the body to help the user verify the browser and system that initiated the request.
OTP session (email OTP login)Triggered when the user signs in with a one-time email verification code (client calls account.createEmailToken(userId, email)){{user}}, {{project}}, {{otp}}, {{agentClient}}, {{agentDevice}}, {{agentOs}}You must retain {{otp}}: this variable is replaced with a 6-digit one-time verification code. It is recommended to display {{otp}} prominently in bold in the email and to note the code's validity period.
Reset password (password reset)Triggered when the user forgets their password and initiates recovery (client calls account.createRecovery(email, url)){{user}}, {{project}}, {{redirect}}You must retain {{redirect}}: it carries the frontend password reset page URL containing userId and the reset secret.
Invite user (team invitation)Triggered when inviting an end user to join a team within the project (e.g. team_support_ops) (calls teams.createMembership(...)){{team}}, {{user}}, {{project}}, {{redirect}}You must retain {{redirect}} and it is recommended to retain {{team}}: {{team}} shows the name of the team being joined (e.g. VIP客户技术支持组), and clicking {{redirect}} confirms joining the team.
2FA verification (MFA verification code)Triggered when an MFA-enabled user chooses to receive the second-factor challenge code via Email (calls account.createMfaChallenge(AuthenticationFactor.Email)){{user}}, {{project}}, {{otp}}, {{agentClient}}, {{agentDevice}}, {{agentOs}}You must retain {{otp}}: it carries the 6-digit dynamic code required for second-factor verification.
Session alert (new session security alert)Used to queue an email when Session alerts is enabled and the session alert conditions are met; delivery is not guaranteed{{user}}, {{project}}, {{device}}, {{ipAddress}}, {{country}}Notification-type email (no confirmation link to click). It is recommended to list the login device {{device}}, source IP {{ipAddress}} and country/region {{country}} in full in the body, advising the user to change their password immediately if the activity was not theirs.

Template Variable Meaning Quick Reference

Variable nameDescription of the actual rendered content (using enterprise-ai-hub-210 as an example)
{{user}}The display name of the recipient end user (Name, e.g. 张伟); if the user has not set a name, it falls back to the email prefix or placeholder text.
{{project}}The current project name, i.e. 企业智能客服与知识中台.
{{team}}Available only in the Invite user template; shows the target team name (e.g. VIP客户技术支持组).
{{redirect}}The complete callback URL passed in by the client that triggered the operation, with signature credentials attached by the server (parameters such as userId, secret).
{{otp}}The server-generated 6-digit one-time numeric code (e.g. 839204).
{{agentClient}}The name of the client browser or application that initiated the login/verification code request (e.g. Chrome, Safari).
{{agentDevice}}The type of end device that initiated the request (e.g. Desktop, Smartphone).
{{agentOs}}The operating system name of the device that initiated the request (e.g. macOS, Windows, iOS).
{{device}}Available only in the Session alert template; describes combined client and device information of the new login session.
{{ipAddress}}Available only in the Session alert template; shows the client source IP address of the new login session.
{{country}}Available only in the Session alert template; shows the country or region name resolved from the source IP.

3. Steps to Edit and Save Multilingual Email Templates

  1. Go to the Auth → Templates page and locate the template card you want to customize (e.g. Invite user or OTP session).

  2. Select the template language (Template language): choose the target language in the language dropdown (default is en; for domestic enterprise customers you can switch to the corresponding language codes and configure each separately; each language version is saved independently).

  3. Configure the template's five core fields:

Editor fieldRequiredConfiguration notes and example (enterprise-ai-hub-210)
Sender nameOptionalThe sender name exclusive to this template (if left blank, it inherits the project-level SMTP default sender name). Example: 企业智能客服与知识中台安全中心
Sender emailOptionalThe sender email address exclusive to this template (make sure your SMTP server allows sending from this address). Example: security-noreply@enterprise.example.com
Reply toOptionalThe address that receives messages when the user clicks "Reply" in their email client. Example: vip-support@enterprise.example.com
SubjectRequiredThe email subject line; template variables can be inserted. Example: [{{project}}] 邀请您加入「{{team}}」协作团队
MessageRequiredThe email body content (supports HTML tags for layout and styling). Next to the editor are all variable tags supported by the current template; click to copy the variable name and paste it into the body.
  1. Review and save:

    • Verify that the body contains the core variables (e.g. {{redirect}} or {{otp}}).

    • If you want to discard unsaved changes while editing, click Reset changes to restore the last saved state.

    • After confirming everything is correct, click Update to save; the new template will immediately apply to all subsequent triggered emails of the same type on the same language platform.

  2. Email signature (only visible on certain cloud plans): on cloud deployments where the current plan includes Email Branding control, the page additionally shows the Email signature card, where a toggle controls whether the Agentbase brand mark is shown in the signature at the bottom of outgoing emails.


FAQ and Troubleshooting

Q1: Why are the Sender name, Subject and Message bodies of all templates grayed out and uneditable after entering the Auth → Templates page?

Root cause analysis: To prevent the platform's shared sending channel from being abused to send custom phishing content, Agentbase requires that you first enable and configure Custom SMTP in the project before you are allowed to customize the email sender and body templates.

Troubleshooting steps: Click SMTP settings in the banner at the top of the Auth → Templates page (or go to Settings → SMTP at the bottom of the left navigation), enable the custom SMTP toggle, enter a valid corporate SMTP host, port, and sending credentials, and save; then refresh the Auth → Templates page and editing will work normally.

Root cause analysis:

  1. While editing the Message template body, the {{redirect}} variable was accidentally deleted, or in an HTML <a href="{{redirect}}"> tag the double curly braces were written as single braces {redirect} or misspelled (e.g. {{redirectUrl}}).

  2. When the client calls account.createVerification(url) or account.createRecovery(email, url), the hostname of the passed url parameter is not registered as a Web platform in the project's Overview → Platforms, causing the server to block the request for security.

Troubleshooting steps:

Q3: After enabling Custom SMTP and saving templates, the client successfully calls the send-code API, but the inbox never receives the email — how do I troubleshoot?

Troubleshooting steps:

  1. Check consistency between the sender email address and the SMTP account: the vast majority of production email service providers (such as Alibaba Cloud DirectMail, Tencent Enterprise Mail, AWS SES, and Microsoft 365) require that the Sender email in the template exactly match the sending address used for SMTP login authentication (or an already verified alias in the same domain); if a Sender email that has not been authorized by the SMTP server is filled in for a specific template, the email will be silently dropped or rejected by the SMTP server. It is recommended to leave the Sender email of each template empty so the project-level SMTP default sender address that has already been verified is reused directly.

  2. Verify with a real test on first integration: after first modifying the project-level SMTP or a template, it is recommended to first use a test account in Auth → Users to trigger a Verification (email verification) or Reset password once, then check the inbox and the spam folder.