邮件模板
功能概述
邮件模板用于定制身份认证相关的通知和验证邮件(路由:/console/project-{region}-{project}/auth/templates),涵盖邮箱验证、魔法链接、一次性验证码、密码找回、团队邀请、多因素认证和会话提醒。会话提醒仅在触发条件满足时加入邮件队列,不判断设备是否为新设备;邮件实际送达取决于队列处理和邮件服务。
通过结合项目级自定义 SMTP 服务(Custom SMTP)与 认证 → 模板 多语言模板编辑器,企业可以将所有发往终端用户的邮件发件人名称(Sender name)、发件邮箱地址(Sender email)、回复地址(Reply to)、邮件主题(Subject)以及 HTML/纯文本邮件正文(Message)完全替换为企业自身的品牌视觉与合规话术,彻底消除通用平台默认发件域名带来的陌生感,显著提升企业客户的邮件打开率与转化信任度。
测试项目未启用自定义 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 种邮件模板,未在界面挂载短信模板编辑器。 |
角色、入口与关联关系
控制台入口与权限要求
导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 左侧导航栏 认证 → 点击顶部 模板 页签。路由地址:
/console/project-{region}-{project}/auth/templates前置配置跳转入口:若当前项目尚未配置自定义 SMTP,点击页面顶部横幅中的 SMTP 设置 链接,可直接跳转至项目级 设置 页(
/console/project-{region}-{project}/settings/smtp)配置 SMTP 主机、端口、账号密码与加密方式。操作权限门禁:查看与修改能力取决于当前用户的项目权限;修改模板还需开启自定义 SMTP。
与其他模块的关联关系
项目设置(Project Settings → SMTP):SMTP 服务器连通性直接决定模板邮件能否成功投递。一旦开启自定义 SMTP,项目内所有由 Auth 触发的系统邮件均切流至该 SMTP 通道发送。
团队管理(Auth Teams):当在
team_support_ops(VIP 客户技术支持组)中通过客户端邀请成员时,触发 邀请用户 模板,将其中的{{team}}替换为VIP客户技术支持组,将{{redirect}}替换为邀请确认回跳地址。安全策略(Auth Security):当在 安全策略 中开启 Session alerts 开关后,满足会话提醒触发条件时会使用 Session alert 模板将邮件加入队列,实际送达取决于邮件服务;当用户使用邮箱作为 MFA 第二因子时,触发 2FA verification 模板。
功能详解与操作指南
1. 前置步骤:启用项目级自定义 SMTP(Custom SMTP)
在编辑 认证 → 模板 之前,请先完成自定义 SMTP 配置:
在项目
enterprise-ai-hub-210左侧导航栏底部点击 设置(或从 认证 → 模板 顶部提示条点击 SMTP 设置)。找到 SMTP 配置卡片,切换开关开启 自定义 SMTP 服务器。
填写企业邮件服务参数:
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。
点击 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. 编辑与保存多语言邮件模板操作步骤
进入 认证 → 模板 页面,定位到需要定制的模板卡片(例如 邀请用户 或 OTP session)。
选择模板语言(Template language):在语言下拉框中选择目标语言(默认为
en;面向国内企业客户可切换至对应语言代码分别配置,每个语言版本独立保存)。配置模板五个核心字段:
| 编辑器字段 | 是否必填 | 配置说明与示例(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 标签排版与样式)。编辑器旁提供了当前模板支持的所有变量标签,点击即可一键复制变量名并粘贴至正文中。 |
检查并保存:
核对正文中是否已包含核心变量(如
{{redirect}}或{{otp}})。若编辑过程中希望放弃未保存的改动,可点击 重置更改 恢复到上一次已保存的状态。
确认无误后点击 Update 保存,新模板将立即作用于后续触发的所有同类型、同语言平台邮件。
邮件品牌签名(Email signature,仅特定云端套餐可见):在云端部署且当前套餐包含 Email Branding 控制权时,页面会额外展示 邮件签名 卡片,可通过开关控制在发出的邮件底部签名中是否展示 Agentbase 品牌标识。
常见问题与排障
Q1:为什么进入 Auth → Templates 页面后,所有模板的 Sender name、Subject 和 Message 正文都是灰色不可编辑状态?
原因分析: 为了防止平台公共共享发信通道被滥用发送自定义钓鱼内容,Agentbase 强制要求必须先在项目中开启并配置自定义 SMTP(Custom SMTP),才允许自定义邮件发件人与正文模板。
解决步骤: 点击 认证 → 模板 页面顶部提示横幅中的 SMTP 设置(或前往左侧导航栏底部 设置 → SMTP),开启自定义 SMTP 开关,填入有效的企业 SMTP 主机、端口与发信凭据并保存,随后刷新 认证 → 模板 页面即可正常编辑。
Q2:修改了 Verification 或 Reset password 模板后,用户收到了邮件但点击链接无法完成验证或无法跳转怎么办?
原因分析:
在编辑模板
Message正文时,误删了{{redirect}}变量,或者在 HTML<a href="{{redirect}}">标签中将双花括号写成了单花括号{redirect}、拼写错误(如{{redirectUrl}})。客户端在调用
account.createVerification(url)或account.createRecovery(email, url)时,传入的url参数所在主机名未在项目 概览 → 平台 中登记为 Web 平台,导致服务端安全拦截。
解决步骤:
打开 认证 → 模板 对应模板,使用编辑器提供的变量复制按钮,确保正文中准确包含
<a href="{{redirect}}">点击完成验证</a>。检查前端代码传入的
redirectURL 域名是否已添加到项目 概览 → 平台 列表中。
Q3:开启自定义 SMTP 并保存模板后,客户端调用发送验证码接口成功,但收件箱一直收不到邮件如何排查?
排查步骤:
检查发件邮箱与 SMTP 账号一致性:绝大多数量产邮件服务商(如阿里云邮件推送、腾讯企业邮、AWS SES、Microsoft 365)要求模板中的 Sender email 必须与 SMTP 登录认证的发信地址(或已验证的同域别名)完全一致;若在某个模板中单独填写了未经 SMTP 服务端授权的
Sender email,邮件会被 SMTP 服务器静默丢弃或拒信。建议将各模板的Sender email留空以直接复用项目级 SMTP 已调通的默认发信地址。首次接入实测验证:首次修改项目级 SMTP 或模板后,建议先在 认证 → 用户 中使用测试账号触发一次 Verification(邮箱验证)或 重置密码,并检查收件箱及垃圾邮件箱(Spam)。
相关文档
认证概览(Auth Overview):了解 Magic URL、Email OTP 等无密码登录方式与整体认证流程。
团队管理(Teams):了解团队成员邀请流程以及 邀请用户 邮件模板的触发机制。
认证安全策略(Security):启用 Session alerts(新会话提醒)与多因素认证(MFA),配合对应邮件模板使用。
项目设置(Project Settings):配置项目级自定义 SMTP 服务器、Webhooks 与全局参数。
