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.
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 concept | Detailed description and technical constraints |
|---|---|
| Custom SMTP as a mandatory prerequisite gate | The 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 templates | Covering 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 support | Although 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
Navigation path: Log in to the Agentbase Console → enter the project
企业智能客服与知识中台(enterprise-ai-hub-210) → Auth in the left navigation bar → click the Templates tab at the top.Route URL:
/console/project-{region}-{project}/auth/templatesPrerequisite configuration entry point: If the current project has not yet configured custom SMTP, clicking the SMTP settings link in the banner at the top of the page takes you directly to the project-level Settings page (
/console/project-{region}-{project}/settings/smtp) to configure the SMTP host, port, credentials, and encryption method.Operation permission gate: Viewing and editing depend on the current user’s project permissions; editing templates also requires custom SMTP to be enabled.
Relationships with Other Modules
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.
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}}withVIP客户技术支持组and{{redirect}}with the invitation confirmation redirect URL.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:
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).Locate the SMTP configuration card and turn on the Custom SMTP server toggle.
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.comorsmtp.office365.com.Port: The SMTP port; commonly
465(SSL/TLS) or587(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
TLSorSSL.
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 name | Trigger scenario and corresponding API / operation | List of available template variables | Core 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 name | Description 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
Go to the Auth → Templates page and locate the template card you want to customize (e.g. Invite user or OTP session).
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).Configure the template's five core fields:
| Editor field | Required | Configuration notes and example (enterprise-ai-hub-210) |
|---|---|---|
| Sender name | Optional | The sender name exclusive to this template (if left blank, it inherits the project-level SMTP default sender name). Example: 企业智能客服与知识中台安全中心 |
| Sender email | Optional | The sender email address exclusive to this template (make sure your SMTP server allows sending from this address). Example: security-noreply@enterprise.example.com |
| Reply to | Optional | The address that receives messages when the user clicks "Reply" in their email client. Example: vip-support@enterprise.example.com |
| Subject | Required | The email subject line; template variables can be inserted. Example: [{{project}}] 邀请您加入「{{team}}」协作团队 |
| Message | Required | The 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. |
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.
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.
Q2: After modifying the Verification or Reset password template, users receive the email but cannot complete verification or be redirected when clicking the link — what should I do?
Root cause analysis:
While editing the
Messagetemplate 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}}).When the client calls
account.createVerification(url)oraccount.createRecovery(email, url), the hostname of the passedurlparameter is not registered as a Web platform in the project's Overview → Platforms, causing the server to block the request for security.
Troubleshooting steps:
Open the corresponding template in Auth → Templates and use the editor's variable copy button to ensure the body accurately contains
<a href="{{redirect}}">点击完成验证</a>.Check whether the
redirectURL domain passed by the frontend code has been added to the project's Overview → Platforms list.
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:
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 emailthat 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 theSender emailof each template empty so the project-level SMTP default sender address that has already been verified is reused directly.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.
Related Documentation
Auth Overview: Learn about passwordless login methods such as Magic URL and Email OTP, as well as the overall authentication flow.
Teams management: Learn about the team member invitation flow and the trigger mechanism of the Invite user email template.
Auth security policies (Security): Enable Session alerts (new session alerts) and multi-factor authentication (MFA), to be used together with the corresponding email templates.
Project Settings: Configure the project-level custom SMTP server, webhooks, and global parameters.
