AppPush
WebPush
WhatsApp
Email
SMS
OTP
X-SMTPAPI 扩展字段
最新更新：2023-03-14
X-SMTPAPI 是 EngageLab 为开发者提供的邮件个性化定制的处理方式。
EngageLab 会检索 key 为 X-SMTPAPI 的头域信息，如果发现含有此头域，则解析 value 的值用来改变邮件的处理方式。开发者在使用 SMTP 和 API 接入时都可以使用此字段。
API 方式：
x_smtpapi = {
"to": ["d@hotmail.com",'i@hotmail.com'],
"sub": {
"%name%": ['jack', 'rose'],
"%money%": ['199', '299'],
},
}
params['xsmtpapi'] = simplejson.dumps(x_smtpapi)
x_smtpapi = {
"to": ["d@hotmail.com",'i@hotmail.com'],
"sub": {
"%name%": ['jack', 'rose'],
"%money%": ['199', '299'],
},
}
params['xsmtpapi'] = simplejson.dumps(x_smtpapi)
此代码块在浮窗中显示
SMTP 方式：
x_smtpapi = {
"to": ["d@hotmail.com",'i@hotmail.com'],
"sub": {
"%name%": ['jack', 'rose'],
"%money%": ['199', '299'],
},
}
msg['X-SMTPAPI'] = Header(base64.b64encode(simplejson.dumps(x_smtpapi)))
x_smtpapi = {
"to": ["d@hotmail.com",'i@hotmail.com'],
"sub": {
"%name%": ['jack', 'rose'],
"%money%": ['199', '299'],
},
}
msg['X-SMTPAPI'] = Header(base64.b64encode(simplejson.dumps(x_smtpapi)))
此代码块在浮窗中显示
SMTP 服务器会对邮件中 **key** 为 `X-SMTPAPI` 的头域信息做格式检查。 如果不符合上述要求，则会报 `xsmtpapi error` 的错误。
需要注意的是：
1. SMTP 调用时，X-SMTPAPI 必须是头域字段的最后一个， 否则，可能导致 `xsmtpapi error` 的错误。
2. SMTP 调用时，X-SMTPAPI 必须是 base64 编码封装， 否则，SMTP 成功请求后，在投递中被 EngageLab 拦截判为无效邮件- `worker:invalid XSMTP-API` 的错误。
3. API 调用时，直接传入 JSON 字符串即可，无需 base64 编码封装。
4. X-SMTPAPI 的总长度不能超过 1M 。
SMTP 服务器会对邮件中 **key** 为 `X-SMTPAPI` 的头域信息做格式检查。 如果不符合上述要求，则会报 `xsmtpapi error` 的错误。
需要注意的是：
1. SMTP 调用时，X-SMTPAPI 必须是头域字段的最后一个， 否则，可能导致 `xsmtpapi error` 的错误。
2. SMTP 调用时，X-SMTPAPI 必须是 base64 编码封装， 否则，SMTP 成功请求后，在投递中被 EngageLab 拦截判为无效邮件- `worker:invalid XSMTP-API` 的错误。
3. API 调用时，直接传入 JSON 字符串即可，无需 base64 编码封装。
4. X-SMTPAPI 的总长度不能超过 1M 。
此代码块在浮窗中显示
value 封装的 JSON 字符串的结构和用途见下：
to 含有收件人地址的数组，指定邮件的收件人。
{
"to": ["ben@engagelab.com", "joe@engagelab.com"]
}
{
"to": ["ben@engagelab.com", "joe@engagelab.com"]
}
此代码块在浮窗中显示
注意:
- 这里的
to会覆盖收件人参数to - 这里的
to的收件人个数不能超过 100
sub 是一个关联数组。 它的 key 是「变量」, value 是「替换值数组」。
用法解释：每一个「变量」对应一个「替换值数组」, 在做邮件内容替换时，每一个「收件人」按其在「收件人数组」中出现的位置使用「替换值数组」中相应位置的值来替换「变量」的值。
参见如下示例：
# 邮件内容
亲爱的%name%:
您好！您本月在 XX 的消费金额为：%money% 元。
#---------------------------------------------------
# X-SMTPAPI
{
"to": ["ben@engagelab.com", "joe@engagelab.com"],
"sub":
{
"%name%": ["Ben", "Joe"],
"%money%":[288, 497]
}
#---------------------------------------------------
# ben@engagelab.com 收到的邮件：
亲爱的 Ben:
您好！您本月在 xx 的消费金额为：288 元。
#---------------------------------------------------
# joe@engagelab.com 收到的邮件：
亲爱的 Joe:
您好！您本月在 xx 的消费金额为：497 元。
# 邮件内容
亲爱的%name%:
您好！您本月在 XX 的消费金额为：%money% 元。
#---------------------------------------------------
# X-SMTPAPI
{
"to": ["ben@engagelab.com", "joe@engagelab.com"],
"sub":
{
"%name%": ["Ben", "Joe"],
"%money%":[288, 497]
}
#---------------------------------------------------
# ben@engagelab.com 收到的邮件：
亲爱的 Ben:
您好！您本月在 xx 的消费金额为：288 元。
#---------------------------------------------------
# joe@engagelab.com 收到的邮件：
亲爱的 Joe:
您好！您本月在 xx 的消费金额为：497 元。
此代码块在浮窗中显示
apps 是包含了一组应用名（退订、打开、点击）和它们设置的关联数组。 这些设置会覆盖它们在用户账户中的设置。
x_smtpapi =
{
"to": ["xxx@qq.com"],
"sub": {"%name%": ["Joe"]},
"filters": {
"subscription_tracking": { # 退订追踪
"settings": { "enable": "1" }
},
"open_tracking": { # 打开追踪
"settings": { "enable": "1" }
},
"click_tracking": { # 点击追踪
"settings": { "enable": "1" }
}
}
x_smtpapi =
{
"to": ["xxx@qq.com"],
"sub": {"%name%": ["Joe"]},
"filters": {
"subscription_tracking": { # 退订追踪
"settings": { "enable": "1" }
},
"open_tracking": { # 打开追踪
"settings": { "enable": "1" }
},
"click_tracking": { # 点击追踪
"settings": { "enable": "1" }
}
}
此代码块在浮窗中显示
page_id
用法解释：
page_id 对应的是 EngageLab 控制台 “发送设置”-“退订设置”-“退订页面”下所创建的某个退订页面的 ID 字段。
客户需要在 EngageLab 控制台预先创建退订页面，之后才能在发送时给 page_id 设置成对应的 ID。
发送时通过 page_id 传参，值设置为某个退订页面的 ID ，此时退订链接、退订页面均为所配置的语言及样式。
page_id 传参的优先级高于发送时 API_USER 所对应的默认的退订页面设置。
支持数组形式来指定退订页面，需与 xsmtpapi 中的 to 个数一致。数组位置和每一个「收件人」按其在「收件人数组」中出现的位置进行一一对应。如果出现和 to 的个数不匹配的情况，则改用使用客户此 apiUser 下的默认 page_id。
参见如下示例：
x_smtpapi =
{
"to": ["xxx@qq.com", "xxx@hotmail.com", "xxx@gmail.com"],
"sub":{"%name%": ["Joe", "Ben", "Michael"]},
"settings":
{
"unsubscribe":
{"page_id": [1, 2, 3]}
}
}
x_smtpapi =
{
"to": ["xxx@qq.com", "xxx@hotmail.com", "xxx@gmail.com"],
"sub":{"%name%": ["Joe", "Ben", "Michael"]},
"settings":
{
"unsubscribe":
{"page_id": [1, 2, 3]}
}
}
此代码块在浮窗中显示
