# X-SMTPAPI 扩展字段

X-SMTPAPI 是 SendCloud 为开发者提供的邮件个性化定制的处理方式。

SendCloud 会检索 key 为 X-SMTPAPI 的头域信息，如果发现含有此头域, 则解析 value 的值用来改变邮件的处理方式。开发者在使用 SMTP 和 API 接入时都可以使用此字段。

API 方式：

x_smtpapi = {
    "to": ["d@163.com",'i@163.com'],
    "sub": {
        "%name%": ['jack', 'rose'],
        "%money%": ['199', '299'],
    },
}

params['xsmtpapi'] = simplejson.dumps(x_smtpapi)

1
2
3
4
5
6
7
8
9

SMTP 方式：

x_smtpapi = {
    "to": ["d@163.com",'i@163.com'],
    "sub": {
        "%name%": ['jack', 'rose'],
        "%money%": ['199', '299'],
    },
}
#自定义Header
msg['SC-Custom-key1'] = "value1"; 
msg['SC-Custom-key2'] = "value2";

msg['X-SMTPAPI'] = Header(base64.b64encode(simplejson.dumps(x_smtpapi)))

1
2
3
4
5
6
7
8
9
10
11
12

SMTP 服务器会对邮件中 **key** 为 `X-SMTPAPI` 的头域信息做格式检查. 如果不符合上述要求, 则会报 `xsmtpapi error` 的错误.
需要注意的是:

1. SMTP 调用时, X-SMTPAPI 必须是头域字段的最后一个. 否则, 可能导致 `xsmtpapi error` 的错误
2. SMTP 调用时, X-SMTPAPI 必须是base64 编码封装. 否则, SMTP成功请求后，在投递中被SendCloud拦截判为无效邮件- `worker:invalid XSMTP-API` 的错误
3. API 调用时, 直接传入 JSON 字符串即可, 无需 base64 编码封装
4. X-SMTPAPI 的总长度不能超过 1M
5. 若客户想从 WebHook 的数据中带有埋在邮件里的信息，可在SMTP发送时加入自定义Header，Key 需以 "SC-Custom-" 开头, 则这个 Key:Value 会通过 WebHook 返回给用户, Key:Value值需为字符串

1
2
3
4
5
6
7
8

value 封装的 JSON 字符串的结构和用途见下:

to 含有收件人地址的数组, 指定邮件的收件人.


    {
        "to": ["ben@ifaxin.com", "joe@ifaxin.com"]
    }

1
2
3
4
5

注意:

这里的 to 会覆盖收件人参数 to
这里的 to 的收件人个数不能超过 100

**sub 是一个关联数组. **它的 key 是「变量」, value 是「替换值数组」.

用法解释: 每一个「变量」对应一个「替换值数组」, 在做邮件内容替换时, 每一个「收件人」按其在「收件人数组」中出现的位置使用「替换值数组」中相应位置的值来替换「变量」的值.

参见如下示例:


# 邮件内容

亲爱的%name%:

    您好! 您本月在爱发信的消费金额为: %money% 元.

#---------------------------------------------------

# X-SMTPAPI

{
"to": ["ben@ifaxin.com", "joe@ifaxin.com"],
"sub":
{
"%name%": ["Ben", "Joe"],
"%money%":[288, 497]
}
}

#---------------------------------------------------

# ben@ifaxin.com 收到的邮件:

亲爱的 Ben:

    您好! 您本月在爱发信的消费金额为: 288 元.

#---------------------------------------------------

# joe@ifaxin.com 收到的邮件:

亲爱的 Joe:

    您好! 您本月在爱发信的消费金额为: 497 元.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

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" }
    }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

page_id

用法解释：

page_id 对应的是 SendCloud 控制台 “发送设置”-“退订设置”-“退订页面”下所创建的某个退订页面的 ID 字段.
客户需要在 SendCloud 控制台预先创建退订页面，之后才能在发送时给 page_id 设置成对应的 ID.
发送时通过 page_id 传参，值设置为某个退订页面的 ID ，此时退订链接、退订页面均为所配置的语言及样式.
page_id 传参的优先级高于发送时 API_USER 所对应的默认的退订页面设置.
支持数组形式来指定退订页面，需与xsmtpapi 中的 to个数一致。数组位置和每一个「收件人」按其在「收件人数组」中出现的位置进行一一对应。如果出现和 to 的个数不匹配的情况，则改用使用客户此 apiUser 下的默认 page_id.

参见如下示例:

x_smtpapi =
{
    "to": ["xxx@qq.com", "xxx@163.com", "xxx@gmail.com"],
    "sub":{"%name%": ["Joe", "Ben", "Michael"]},
    "settings": 
    {
        "unsubscribe": 
            {"page_id": [1, 2, 3]}
    }
}

1
2
3
4
5
6
7
8
9

SMTP 请求方式 messageId 和 emailId