Docs
文档目录

邮件模板

功能概述

邮件模板用于定制身份认证相关的通知和验证邮件(路由:/console/project-{region}-{project}/auth/templates),涵盖邮箱验证、魔法链接、一次性验证码、密码找回、团队邀请、多因素认证和会话提醒。会话提醒仅在触发条件满足时加入邮件队列,不判断设备是否为新设备;邮件实际送达取决于队列处理和邮件服务。

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

未启用自定义 SMTP 时的邮件模板提示

测试项目未启用自定义 SMTP;未提交配置或发送邮件。


核心概念与架构

Agentbase 邮件模板引擎采用“项目级自定义 SMTP 门控 → 事件类型路由 → 多语言(Locale)匹配 → 双花括号变量({{variable}})安全注入 → 异步队列投递”的流水线架构。

核心概念与版本边界说明

核心概念详细说明与技术约束
自定义 SMTP 前置门控定制任何邮件模板的强制前提是在项目 设置 → SMTP 中启用并配置有效的自定义 SMTP 服务器。未启用自定义 SMTP 时,认证 → 模板 页面顶部会显示提示 "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)版本事实说明虽然底层前端仓库源码中预留了短信模板相关组件(用于邀请、验证、登录),但在当前版本的控制台 认证 → 模板 页面中仅挂载并开放上述 7 种邮件模板,未在界面挂载短信模板编辑器。

角色、入口与关联关系

控制台入口与权限要求

与其他模块的关联关系

  1. 项目设置(Project Settings → SMTP):SMTP 服务器连通性直接决定模板邮件能否成功投递。一旦开启自定义 SMTP,项目内所有由 Auth 触发的系统邮件均切流至该 SMTP 通道发送。

  2. 团队管理(Auth Teams):当在 team_support_ops(VIP 客户技术支持组)中通过客户端邀请成员时,触发 邀请用户 模板,将其中的 {{team}} 替换为 VIP客户技术支持组,将 {{redirect}} 替换为邀请确认回跳地址。

  3. 安全策略(Auth Security):当在 安全策略 中开启 Session alerts 开关后,满足会话提醒触发条件时会使用 Session alert 模板将邮件加入队列,实际送达取决于邮件服务;当用户使用邮箱作为 MFA 第二因子时,触发 2FA verification 模板。


功能详解与操作指南

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

在编辑 认证 → 模板 之前,请先完成自定义 SMTP 配置:

  1. 在项目 enterprise-ai-hub-210 左侧导航栏底部点击 设置(或从 认证 → 模板 顶部提示条点击 SMTP 设置)。

  2. 找到 SMTP 配置卡片,切换开关开启 自定义 SMTP 服务器。

  3. 填写企业邮件服务参数:

    • Sender name:默认发件人名称,如 Agentbase 企业智能客服中心。

    • Sender email:默认发件人邮箱地址,如 no-reply@enterprise.example.com(必须与 SMTP 认证账号或已授权发信域名一致)。

    • Reply to:默认回复接收邮箱,如 support@enterprise.example.com。

    • Server host:SMTP 服务器域名,如 smtpdm.aliyun.com 或 smtp.office365.com。

    • Port:SMTP 端口,常用 465(SSL/TLS)或 587(STARTTLS)。

    • Username / Password:SMTP 发信认证账号与授权码(密码使用 <SMTP_PASSWORD> 安全托管,服务端加密存储)。

    • Secure protocol:选择 TLS 或 SSL。

  4. 点击 Update 保存 SMTP 设置。保存成功后返回 认证 → 模板 页面,所有模板输入框即解除禁用状态。

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

在 认证 → 模板 页面中,每种模板在触发时机与支持的动态变量上各有分工。下表列出了全部 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 的前端密码重置页跳转地址。
邀请用户(团队邀请)邀请终端用户加入项目内团队(如 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(新会话安全提醒)开启 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. 编辑与保存多语言邮件模板操作步骤

  1. 进入 认证 → 模板 页面,定位到需要定制的模板卡片(例如 邀请用户 或 OTP session)。

  2. 选择模板语言(Template language):在语言下拉框中选择目标语言(默认为 en;面向国内企业客户可切换至对应语言代码分别配置,每个语言版本独立保存)。

  3. 配置模板五个核心字段:

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

    • 核对正文中是否已包含核心变量(如 {{redirect}} 或 {{otp}})。

    • 若编辑过程中希望放弃未保存的改动,可点击 重置更改 恢复到上一次已保存的状态。

    • 确认无误后点击 Update 保存,新模板将立即作用于后续触发的所有同类型、同语言平台邮件。

  2. 邮件品牌签名(Email signature,仅特定云端套餐可见):在云端部署且当前套餐包含 Email Branding 控制权时,页面会额外展示 邮件签名 卡片,可通过开关控制在发出的邮件底部签名中是否展示 Agentbase 品牌标识。


常见问题与排障

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

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

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

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

原因分析:

  1. 在编辑模板 Message 正文时,误删了 {{redirect}} 变量,或者在 HTML <a href="{{redirect}}"> 标签中将双花括号写成了单花括号 {redirect}、拼写错误(如 {{redirectUrl}})。

  2. 客户端在调用 account.createVerification(url) 或 account.createRecovery(email, url) 时,传入的 url 参数所在主机名未在项目 概览 → 平台 中登记为 Web 平台,导致服务端安全拦截。

解决步骤:

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

排查步骤:

  1. 检查发件邮箱与 SMTP 账号一致性:绝大多数量产邮件服务商(如阿里云邮件推送、腾讯企业邮、AWS SES、Microsoft 365)要求模板中的 Sender email 必须与 SMTP 登录认证的发信地址(或已验证的同域别名)完全一致;若在某个模板中单独填写了未经 SMTP 服务端授权的 Sender email,邮件会被 SMTP 服务器静默丢弃或拒信。建议将各模板的 Sender email 留空以直接复用项目级 SMTP 已调通的默认发信地址。

  2. 首次接入实测验证:首次修改项目级 SMTP 或模板后,建议先在 认证 → 用户 中使用测试账号触发一次 Verification(邮箱验证)或 重置密码,并检查收件箱及垃圾邮件箱(Spam)。


相关文档