创建模板
调用地址
POST https://otp.api.engagelab.cc/v1/template-configs
调用验证
请参考 调用验证 了解如何进行 API 鉴权。
请求
请求参数
一个请求对象以 JSON 格式表达,因此请求头需要带 Content-Type: application/json 。
| 参数 | 类型 | 选项 | 说明 |
|---|---|---|---|
| template_id | String | 必填 | 自定义的模版 id,具有唯一性,限制 128 字符 |
| description | String | 选填 | 模版的描述,限制 255 字符 |
| send_channel_strategy | String | 必填 | 模版策略,单个通道取值为 whatsapp/sms/email/voice,多通道用|隔开,按顺序补发,email 不能和其他通道一起组成策略 |
| brand_name | String | 选填 | 品牌标志,在某些模版样式具有品牌签名时会替换品牌签名变量,长度限制在 2-10 个字符 |
| verify_code_config | Object | 条件必填 | 验证码的配置,模版包含验证码类型时必填 |
| verify_code_config.verify_code_type | Integer | 必填 | 验证码类型,取值范围[1,7],1 数字/2 小写英文字母/4 大写英文字母,可组合(如 3 表示数字+小写字母) |
| verify_code_config.verify_code_len | Integer | 必填 | 验证码长度,取值范围[4,10] |
| verify_code_config.verify_code_ttl | Integer | 必填 | 验证码有效期,单位分钟,取值[1,10],策略包含 whatsapp 时只能为 1、5、10 |
| whatsapp_config | Object | 条件必填 | whatsapp 策略的配置,下发策略包含 whatsapp 时必填 |
| whatsapp_config.template_type | Integer | 必填 | whatsapp 模版类型,目前仅支持默认模版,固定为 1 |
| whatsapp_config.template_default_config | Object | 条件必填 | whatsapp 默认模版配置,whatsapp 模版类型为默认模版时必填 |
| sms_config | Object | 条件必填 | sms 策略的配置,下发策略包含 sms 时必填 |
| sms_config.template_type | Integer | 必填 | sms 模版类型,1-默认模版/2-自定义模版 |
| sms_config.template_default_config | Object | 条件必填 | sms 默认模版配置,sms 模版类型为默认模版时必填 |
| sms_config.template_custom_config | Object | 条件必填 | sms 自定义模版配置,sms 模版类型为自定义模版时必填 |
| sms_config.template_custom_config.custom_sub_type | String | 必填 | 自定义模版类型,authentication-验证码/marketing-营销/utility-通知 |
| sms_config.template_custom_config.custom_content | String | 必填 | 自定义模版内容,authentication 类型时必须包含{{code}}变量 |
| sms_config.template_custom_config.custom_country_codes | String | 选填 | 目标国家地区代码,逗号分隔,用于模版审核时参考 |
| voice_config | Object | 条件必填 | voice 策略的配置,下发策略包含 voice 时必填 |
| voice_config.template_type | Integer | 必填 | voice 模版类型,目前仅支持默认模版,固定为 1 |
| voice_config.template_default_config | Object | 条件必填 | voice 默认模版配置,voice 模版类型为默认模版时必填 |
| email_config | Object | 条件必填 | email 策略的配置,下发策略包含 email 时必填 |
| email_config.template_name | String | 必填 | email 模版名称 |
| email_config.template_custom_configs | Array | 条件必填 | email 自定义模版配置,email 模版类型为自定义模版时必填,支持多语言配置 |
| email_config.template_custom_configs.language | String | 必填 | 语言,default 为默认,消息下发时可根据 language 参数匹配不同模版内容 |
| email_config.template_custom_configs.pre_from_name | String | 选填 | 预设的发送人名称 |
| email_config.template_custom_configs.pre_from_mail | String | 必填 | 预设的发送人邮箱 |
| email_config.template_custom_configs.pre_subject | String | 必填 | 预设的邮件主题 |
| email_config.template_custom_configs.template_content | String | 必填 | 邮件内容,支持 html,变量需用{{}}括起来 |
| email_config.template_custom_configs.pre_param_map | Object | 选填 | 邮件内容变量的默认值,key-value 对声明,value 需要使用字符串 |
| pwa_config | Object | 选填 | pwa 相关配置,暂时可不使用 |
| pwa_config.pwa_platform | String | 选填 | 使用的 pwa 平台,具体取值请与技术支持联系获取 |
| pwa_config.pwa_code | String | 选填 | 使用的 pwa 平台中的 code |
请求示例
请求头
POST /v1/template-configs HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
POST /v1/template-configs HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
此代码块在浮窗中显示
请求体
{
"template_id": "test-template-1", // 自定义的模版id,应用内唯一
"description": "测试模版1", // 该模版的描述说明
"send_channel_strategy": "whatsapp|sms", // 模版的下发策略,支持whatsapp/sms/voice/email四类,组合策略则使用|字符表示失败补发
"brand_name": "品牌名称", // 品牌名称,用在一些国家地区模版内容中的签名(如短信通道中一些国家地区要求要注册签名)
"verify_code_config": { // 验证码的配置,用于配置自动生成的验证码,模版包含验证码类型时必填
"verify_code_type": 1, // 验证码类型,取值范围[1,7]
"verify_code_len": 6, // 验证码长度,取值范围[4,10]
"verify_code_ttl": 1 // 验证码有效期,取值范围[1,10],注意当策略包含whatsapp时取值只能是1,5,10
},
"whatsapp_config": { // whatsapp策略的配置,当下发策略包含whatsapp时有效
"template_type": 1, // whatsapp模版类型,目前仅支持默认模版,即固定取值为1
"template_default_config": { // whatsapp默认模版配置,针对默认模版类型时有效
"contain_security": false, // 是否添加安全提醒
"contain_expire": false // 是否添加过期时间内容
}
},
"sms_config": { // sms策略的配置,当下发策略包含sms时有效
"template_type": 2, // sms模版类型,取值:1-默认模版/2-自定义模版
"template_default_config": { // sms默认模版配置,针对默认模版类型时有效
"contain_security": false, // 是否添加安全提醒
"contain_expire": false // 是否添加过期时间内容
},
"template_custom_config": { // sms自定义模版配置,sms模版类型为自定义模版时有效
"custom_sub_type": "authentication", // 自定义模版类型,取值:authentication-验证码/marketing-营销/utility-通知
"custom_content": "xxx", // 自定义模版内容,注意若子类型为authentication验证码类型时必须包含{{code}}变量
"custom_country_codes": "HK,PH" // 自定义模版的目标国家地区,用于模版审核时参考,请按实际填写,否则可能影响实际下发
}
},
"voice_config": { // voice策略的配置,当下发策略包含voice时有效
"template_type": 1, // voice模版类型,目前仅支持默认模版,即固定取值为1
"template_default_config": { // voice默认模版配置,针对默认模版类型时有效
"contain_security": false, // 是否添加安全提醒
"contain_expire": false // 是否添加过期时间内容
}
},
"email_config": { // email策略的配置,当下发策略包含email时有效
"template_name": "email模板名称", // email模版名称
"template_custom_configs": [{ // email自定义模版配置,注意这里是对象数组,主要是通过language进行区分配置多个
"language": "default", // 语言,default为默认,消息下发时可以根据language参数来匹配不同的模版内容
"pre_from_name": "test", // 预设的发送人名称
"pre_from_mail": "test@test.com", // 预设的发送人邮箱
"pre_subject": "test", // 预设的邮件主题
"template_content": "预设邮件模版内容,必填,自定义变量如{{self}},验证码是{{code}}", // 邮件内容,支持html,变量需要使用两个大括号{{}}括起来
"pre_param_map": { // 邮件内容中变量的默认值,即下发时若不指定变量值,则采用下述的默认值来替换变量,采用key-value对声明,value需要使用字符串
"self": "这里是self变量预设值"
}
}]
},
"pwa_config": { // pwa相关的配置,暂时可以不使用
"pwa_platform": "xx", // 使用的pwa平台,具体取值请与技术支持联系获取确定
"pwa_code": "xx" // 使用的pwa平台中的code
}
}
{
"template_id": "test-template-1", // 自定义的模版id,应用内唯一
"description": "测试模版1", // 该模版的描述说明
"send_channel_strategy": "whatsapp|sms", // 模版的下发策略,支持whatsapp/sms/voice/email四类,组合策略则使用|字符表示失败补发
"brand_name": "品牌名称", // 品牌名称,用在一些国家地区模版内容中的签名(如短信通道中一些国家地区要求要注册签名)
"verify_code_config": { // 验证码的配置,用于配置自动生成的验证码,模版包含验证码类型时必填
"verify_code_type": 1, // 验证码类型,取值范围[1,7]
"verify_code_len": 6, // 验证码长度,取值范围[4,10]
"verify_code_ttl": 1 // 验证码有效期,取值范围[1,10],注意当策略包含whatsapp时取值只能是1,5,10
},
"whatsapp_config": { // whatsapp策略的配置,当下发策略包含whatsapp时有效
"template_type": 1, // whatsapp模版类型,目前仅支持默认模版,即固定取值为1
"template_default_config": { // whatsapp默认模版配置,针对默认模版类型时有效
"contain_security": false, // 是否添加安全提醒
"contain_expire": false // 是否添加过期时间内容
}
},
"sms_config": { // sms策略的配置,当下发策略包含sms时有效
"template_type": 2, // sms模版类型,取值:1-默认模版/2-自定义模版
"template_default_config": { // sms默认模版配置,针对默认模版类型时有效
"contain_security": false, // 是否添加安全提醒
"contain_expire": false // 是否添加过期时间内容
},
"template_custom_config": { // sms自定义模版配置,sms模版类型为自定义模版时有效
"custom_sub_type": "authentication", // 自定义模版类型,取值:authentication-验证码/marketing-营销/utility-通知
"custom_content": "xxx", // 自定义模版内容,注意若子类型为authentication验证码类型时必须包含{{code}}变量
"custom_country_codes": "HK,PH" // 自定义模版的目标国家地区,用于模版审核时参考,请按实际填写,否则可能影响实际下发
}
},
"voice_config": { // voice策略的配置,当下发策略包含voice时有效
"template_type": 1, // voice模版类型,目前仅支持默认模版,即固定取值为1
"template_default_config": { // voice默认模版配置,针对默认模版类型时有效
"contain_security": false, // 是否添加安全提醒
"contain_expire": false // 是否添加过期时间内容
}
},
"email_config": { // email策略的配置,当下发策略包含email时有效
"template_name": "email模板名称", // email模版名称
"template_custom_configs": [{ // email自定义模版配置,注意这里是对象数组,主要是通过language进行区分配置多个
"language": "default", // 语言,default为默认,消息下发时可以根据language参数来匹配不同的模版内容
"pre_from_name": "test", // 预设的发送人名称
"pre_from_mail": "test@test.com", // 预设的发送人邮箱
"pre_subject": "test", // 预设的邮件主题
"template_content": "预设邮件模版内容,必填,自定义变量如{{self}},验证码是{{code}}", // 邮件内容,支持html,变量需要使用两个大括号{{}}括起来
"pre_param_map": { // 邮件内容中变量的默认值,即下发时若不指定变量值,则采用下述的默认值来替换变量,采用key-value对声明,value需要使用字符串
"self": "这里是self变量预设值"
}
}]
},
"pwa_config": { // pwa相关的配置,暂时可以不使用
"pwa_platform": "xx", // 使用的pwa平台,具体取值请与技术支持联系获取确定
"pwa_code": "xx" // 使用的pwa平台中的code
}
}
此代码块在浮窗中显示
响应
响应参数
| 字段 | 类型 | 选项 | 描述 |
|---|---|---|---|
| code | Integer | 必填 | 错误码,0 表示成功,其他为失败 |
| message | String | 必填 | 响应信息 |
响应示例
成功返回
{
"code": 0,
"message": "success"
}
{
"code": 0,
"message": "success"
}
此代码块在浮窗中显示
失败返回
{
"code": 3003,
"message": "not contains any channel config"
}
{
"code": 3003,
"message": "not contains any channel config"
}
此代码块在浮窗中显示
Email 模板变量高级用法
当您在发送策略中启用 Email 通道时,支持高度自定义邮件主题和正文内容。通过变量占位符 {{变量名}},可自动填充验证码、品牌信息等内容,实现灵活的个性化邮件体验。
变量类型及用法
Email 模板正文(template_content)和主题(pre_subject)均可嵌入变量,格式为 {{变量名}}。
发送 API 通过 template.params 字段动态传入,或在模板创建阶段设置默认值。
支持的变量
下面变量仅 Email 通道适用。
| 变量名 | 类型 | 说明 | 填充方式 |
|---|---|---|---|
{{logo_url}} |
自定义变量 | 品牌 Logo 图片地址 | 发送时通过 template.params 传入 |
{{title}} |
自定义变量 | 邮件正文标题文字 | 发送时通过 template.params 传入 |
{{support_email}} |
自定义变量 | 客服/支持邮箱地址 | 发送时通过 template.params 传入 |
{{subject}} |
自定义变量 | 动态覆盖邮件主题 | 发送时通过 template.params 传入 |
{{from_name}} |
自定义变量 | 动态覆盖发件人名称 | 发送时通过 template.params 传入 |
{{from_mail}} |
自定义变量 | 动态覆盖发件人邮箱 | 发送时通过 template.params 传入 |
注意:
{{subject}}、{{from_name}}、{{from_mail}}这几个特殊变量不会插入到正文 HTML,而是直接覆盖邮件的元数据字段。
邮件主题示例
{{brand_name}} 验证码
{{brand_name}} 验证码
此代码块在浮窗中显示
邮件正文示例
<img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>您的验证码是 <strong>{{code}}</strong>,请在 {{ttl}} 分钟内完成验证。</p>
<p>如有疑问,请联系 <a href="mailto:{{support_email}}">{{support_email}}</a></p>
<img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>您的验证码是 <strong>{{code}}</strong>,请在 {{ttl}} 分钟内完成验证。</p>
<p>如有疑问,请联系 <a href="mailto:{{support_email}}">{{support_email}}</a></p>
此代码块在浮窗中显示
模板默认值设置
模板创建时,可在 pre_param_map 字段设置自定义变量的默认值。发送邮件时未传入变量时,将自动使用默认值。
"pre_param_map": {
"logo_url": "https://example.com/logo.png",
"title": "您的验证码",
"support_email": "support@example.com"
}
"pre_param_map": {
"logo_url": "https://example.com/logo.png",
"title": "您的验证码",
"support_email": "support@example.com"
}
此代码块在浮窗中显示
发送参数说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
to |
string | 是 | 目标邮箱地址 |
template.id |
string | 是 | 邮件模板 ID |
template.language |
string | 否 | 语言代码,默认 default |
template.params |
object | 否 | 模板变量赋值(不含 {{}}) |
示例请求:
{
"to": "user@example.com",
"template": {
"id": "my_email_template",
"language": "default",
"params": {
"logo_url": "https://example.com/logo.png",
"title": "您的验证码",
"support_email": "support@example.com"
}
}
}
{
"to": "user@example.com",
"template": {
"id": "my_email_template",
"language": "default",
"params": {
"logo_url": "https://example.com/logo.png",
"title": "您的验证码",
"support_email": "support@example.com"
}
}
}
此代码块在浮窗中显示
变量填充优先级
- 优先使用发送接口中
template.params传入的变量值; - 若未传入,则使用模板
pre_param_map中的默认值; - 若两者均未设置,则占位符原样显示在邮件内容中。
常见问题解答
Q: 为什么变量未被替换?
A: 请确认变量名书写及格式正确(需 {{变量名}}),并确保已通过 template.params 提供值,或模板已设置默认值。
Q: 如何动态设置邮件主题、发件人?
A: 在请求参数 template.params 内传入 subject、from_name、from_mail,即可动态覆盖模板预设的主题和发件人信息。
错误码
| 错误码 | http code | 说明 |
|---|---|---|
| 1000 | 500 | 内部错误 |
| 2001 | 401 | 鉴权失败,未携带正确的 token |
| 2002 | 401 | 鉴权失败,token 已过期或已被禁用 |
| 2004 | 403 | 无调用此 API 的权限 |
| 3001 | 400 | 请求参数格式无效,请检查是否符合参数格式的 JSON 内容 |
| 3002 | 400 | 请求参数有误,请检查请求参数是否符合要求 |
| 3003 | 400 | 业务级别的参数错误,请检查返回 message 字段说明 |










