AgentbaseDocs
文档目录

邮件模板

功能概述

邮件模板(Templates)是 Agentbase 身份认证(Auth)服务提供的企业级通知与核验邮件定制中心(路由:/console/project-{region}-{project}/auth/templates,页面标题显示 Email templates 并带有 Experimental 徽标)。在项目 **企业智能客服与知识中台**(Project ID:enterprise-ai-hub-210)中,当终端用户(如客户张伟 user_zhangwei_001 或客服专家李娜 user_lina_002)触发邮箱验证、魔法链接登录(Magic URL)、一次性验证码登录(OTP session)、找回密码(Reset password)、团队邀请(Invite user)、多因素认证挑战(2FA verification)或新设备登录安全提醒(Session alert)时,平台会自动渲染并下发对应的系统邮件。

通过结合项目级自定义 SMTP 服务(Custom SMTP)与 Auth → Templates 多语言模板编辑器,企业可以将所有发往终端用户的邮件发件人名称(Sender name)、发件邮箱地址(Sender email)、回复地址(Reply to)、邮件主题(Subject)以及 HTML/纯文本邮件正文(Message)完全替换为企业自身的品牌视觉与合规话术,彻底消除通用平台默认发件域名带来的陌生感,显著提升企业客户的邮件打开率与转化信任度。


核心概念与架构

Agentbase 邮件模板引擎采用“项目级自定义 SMTP 门控 → 事件类型路由 → 多语言(Locale)匹配 → 双花括号变量({{variable}})安全注入 → 异步队列投递”的流水线架构。下图展示了从终端用户触发认证事件到收到定制化品牌邮件的完整链路:

flowchart TB
    subgraph Triggers["7 大认证触发场景 (Auth Events)"]
        E1["1. Verification<br/>(注册/邮箱验证)"]
        E2["2. Magic URL<br/>(无密码魔法链接登录)"]
        E3["3. OTP session<br/>(邮箱 6 位验证码登录)"]
        E4["4. Reset password<br/>(找回与重置密码)"]
        E5["5. Invite user<br/>(邀请加入团队 team_support_ops)"]
        E6["6. 2FA verification<br/>(MFA 二次验证挑战)"]
        E7["7. Session alert<br/>(新设备登录安全告警)"]
    end

    subgraph Gate["前置条件门控 (SMTP Gate)"]
        SMTPCheck{"项目 Settings → SMTP<br/>已启用 Custom SMTP?"}
        DefaultMail["使用平台默认内置模板与发件通道<br/>(Templates 页处于只读预览态)"]
        CustomEngine["启用项目自定义模板渲染引擎<br/>(读取 Auth → Templates 配置)"]
    end

    subgraph TemplateEngine["多语言模板与变量注入引擎"]
        LocaleSelect["按请求 Locale 匹配 Template language<br/>(如 zh-CN / en / ja)"]
        HeaderInject["注入发件头信息<br/>Sender name / Sender email / Reply to / Subject"]
        VarRender["解析并替换模板变量<br/>{{user}}, {{project}}, {{redirect}}, {{otp}},<br/>{{team}}, {{agentClient}}, {{ipAddress}} 等"]
    end

    subgraph Delivery["邮件投递"]
        SMTPServer["企业自建或云厂商 SMTP 服务器<br/>(TLS / STARTTLS 加密传输)"]
        Inbox["终端用户收件箱<br/>(zhangwei@customer-corp.example.com)"]
    end

    E1 & E2 & E3 & E4 & E5 & E6 & E7 --> SMTPCheck
    SMTPCheck -->|未启用| DefaultMail --> Inbox
    SMTPCheck -->|已启用| CustomEngine
    CustomEngine --> LocaleSelect --> HeaderInject --> VarRender --> SMTPServer --> Inbox

核心概念与版本边界说明

核心概念详细说明与技术约束
自定义 SMTP 前置门控定制任何邮件模板的强制前提是在项目 Settings → SMTP 中启用并配置有效的自定义 SMTP 服务器。未启用自定义 SMTP 时,Auth → Templates 页面顶部会显示提示 "Custom SMTP server is required for customizing emails",且所有模板的发件人字段禁用、正文处于只读状态。
7 类标准邮件模板覆盖身份验证与安全告警全链路:Verification、Magic URL、OTP session、Reset password、Invite user、2FA verification、Session alert。
多语言独立存储(Template language)每个模板类型均支持按语言代码(默认 en,支持切换 zh-CN 等多语言)独立编辑并保存。当客户端发起请求时,服务端根据当前请求的 Locale 选择对应语言的模板进行渲染。
**动态模板变量({{...}})**采用双花括号语法(如 {{user}}、{{project}}、{{redirect}}、{{otp}})在发送瞬间注入真实上下文。不同模板类型支持的变量集合严格固定,不可跨模板混用未声明的变量。
短信模板(SMS Templates)版本事实说明虽然底层前端仓库源码中预留了短信模板相关组件(用于邀请、验证、登录),但在当前 v2.10.0 版本的 Console Auth → Templates 页面中仅挂载并开放上述 7 种邮件模板,未在界面挂载短信模板编辑器。

角色、入口与关联关系

控制台入口与权限要求

与其他模块的关联关系


功能详解与操作指南

1. 前置步骤:启用项目级自定义 SMTP(Custom SMTP)

在编辑 Auth → Templates 之前,请先完成自定义 SMTP 配置:

2. 七种邮件模板类型与可用变量全集

在 Auth → Templates 页面中,每种模板在触发时机与支持的动态变量上各有分工。下表列出了全部 7 种邮件模板的触发场景、必留关键变量及全量可用变量说明:

模板名称触发场景与对应 API / 操作可用模板变量清单必留核心变量与防踩坑说明
Verification(邮箱验证)用户注册后或主动请求验证邮箱时触发(客户端调用 account.createVerification(url)){{user}}、{{project}}、{{redirect}}**必须保留 {{redirect}}**:该变量承载带加密 Token 的邮箱验证确认完整 URL;若在正文中误删 {{redirect}},收件人将无法点击完成邮箱验证。
Magic URL(魔法链接登录)用户使用无密码 Magic URL 登录时触发(客户端调用 account.createMagicURLToken(userId, email, url)){{user}}、{{project}}、{{redirect}}、{{agentClient}}、{{agentDevice}}、{{agentOs}}**必须保留 {{redirect}}**:收件人点击该链接后回跳至应用前端并完成会话创建。可在正文中展示 {{agentClient}}、{{agentOs}} 帮助用户核对发起请求的浏览器与系统。
OTP session(邮箱 OTP 登录)用户使用邮箱一次性验证码登录时触发(客户端调用 account.createEmailToken(userId, email)){{user}}、{{project}}、{{otp}}、{{agentClient}}、{{agentDevice}}、{{agentOs}}**必须保留 {{otp}}**:该变量会被替换为 6 位数字一次性验证码。建议在邮件中加粗醒目展示 {{otp}} 并提示验证码有效期。
Reset password(重置密码)用户忘记密码发起找回流程时触发(客户端调用 account.createRecovery(email, url)){{user}}、{{project}}、{{redirect}}**必须保留 {{redirect}}**:承载包含 userId 与重置 secret 的前端密码重置页跳转地址。
Invite user(团队邀请)邀请终端用户加入项目内团队(如 team_support_ops)时触发(调用 teams.createMembership(...)){{team}}、{{user}}、{{project}}、{{redirect}}**必须保留 {{redirect}} 与建议保留 {{team}}**:{{team}} 显示被邀请加入的团队名称(如 VIP客户技术支持组),点击 {{redirect}} 完成入组确认。
2FA verification(多因素认证验证码)开启 MFA 的用户选择通过 Email 接收二次验证挑战码时触发(调用 account.createMfaChallenge(AuthenticationFactor.Email)){{user}}、{{project}}、{{otp}}、{{agentClient}}、{{agentDevice}}、{{agentOs}}**必须保留 {{otp}}**:承载二次核验所需的 6 位动态验证码。
Session alert(新会话安全提醒)当 Auth → Security 开启 Session alerts 后,用户每次产生新登录会话时自动触发{{user}}、{{project}}、{{device}}、{{ipAddress}}、{{country}}通知类邮件(无需跳转确认链接)。建议在正文中完整列出登录设备 {{device}}、源 IP {{ipAddress}} 与国家/地区 {{country}},提醒用户非本人操作时立即改密。

模板变量含义速查表

变量名渲染后的实际内容说明(以 enterprise-ai-hub-210 为例)
{{user}}收件终端用户的显示名称(Name,如 张伟);若用户未设置姓名,则回退展示邮箱前缀或提示词。
{{project}}当前项目名称,即 企业智能客服与知识中台。
{{team}}仅在 Invite user 模板中可用,展示目标团队名称(如 VIP客户技术支持组)。
{{redirect}}由触发该操作的客户端传入并由服务端附加签名凭证(userId、secret 等参数)的完整回调 URL。
{{otp}}服务端生成的 6 位一次性数字验证码(如 839204)。
{{agentClient}}发起登录/验证码请求的客户端浏览器或应用名称(如 Chrome、Safari)。
{{agentDevice}}发起请求的终端设备类型(如 Desktop、Smartphone)。
{{agentOs}}发起请求的操作系统名称(如 macOS、Windows、iOS)。
{{device}}仅在 Session alert 模板中可用,描述新登录会话的客户端与设备综合信息。
{{ipAddress}}仅在 Session alert 模板中可用,展示新登录会话的客户端源 IP 地址。
{{country}}仅在 Session alert 模板中可用,展示根据源 IP 解析出的国家或地区名称。

3. 编辑与保存多语言邮件模板操作步骤

编辑器字段是否必填配置说明与示例(enterprise-ai-hub-210)
Sender name可选该模板专属发件人名称(留空则继承项目级 SMTP 默认发件人名称)。示例:企业智能客服与知识中台安全中心
Sender email可选该模板专属发件邮箱地址(需确保您的 SMTP 服务器允许使用该地址发信)。示例:security-noreply@enterprise.example.com
Reply to可选用户在邮件客户端点击“回复”时的收件地址。示例:vip-support@enterprise.example.com
Subject必填邮件标题,支持插入模板变量。示例:[{{project}}] 邀请您加入「{{team}}」协作团队
Message必填邮件正文内容(支持 HTML 标签排版与样式)。编辑器旁提供了当前模板支持的所有变量标签,点击即可一键复制变量名并粘贴至正文中。

常见问题与排障

Q1:为什么进入 Auth → Templates 页面后,所有模板的 Sender name、Subject 和 Message 正文都是灰色不可编辑状态?

原因分析: 为了防止平台公共共享发信通道被滥用发送自定义钓鱼内容,Agentbase 强制要求必须先在项目中开启并配置自定义 SMTP(Custom SMTP),才允许自定义邮件发件人与正文模板。

解决步骤: 点击 Auth → Templates 页面顶部提示横幅中的 SMTP settings(或前往左侧导航栏底部 Settings → SMTP),开启自定义 SMTP 开关,填入有效的企业 SMTP 主机、端口与发信凭据并保存,随后刷新 Auth → Templates 页面即可正常编辑。

Q2:修改了 Verification 或 Reset password 模板后,用户收到了邮件但点击链接无法完成验证或无法跳转怎么办?

原因分析:

解决步骤:

Q3:开启自定义 SMTP 并保存模板后,客户端调用发送验证码接口成功,但收件箱一直收不到邮件如何排查?

排查步骤:


相关文档