通用规则
SMTP 请求方式
为开发者提供 SMTP 协议的投递方式, 以下是会话过程. 详细的代码示例, 请移步这里
S: 220 SendCloud Inbound Server ESMTP Haraka 2.2.4 ready
C: ehlo ifaxin.com
S: 250-SendCloud Inbound Server Hello, Haraka is at your service.
S: 250-PIPELINING
S: 250-8BITMIME
S: 250-SIZE 16000000
S: 250 AUTH LOGIN
C: AUTH LOGIN base64(api_user)
S: 334 UGFzc3dvcmQ6
C: base64(api_key)
S: 235 Authentication successful
C: mail FROM:<support@ifaxin.com>
S: 250 sender <support@ifaxin.com> OK
C: rcpt TO:<ben@ifaxin.com>
S: 250 recipient <ben@ifaxin.com> OK
C: data
S: 354 go ahead, make my day
C: ... ...
C: .
S: 250 #1426390015358_15_6484_8661.sc-10_10_127_51-inbound#Queued
C: quit
S: 221 SendCloud Inbound Server closing connection. Have a jolly good day
注意
SMTP 调用返回 536 Frequency limited,意味着每个 apiuser 每分钟,api 和 smtp 总共调用不能超过 2 万次
messageId 和 emailId
messageId
是提交一次请求, 返回的消息编号.
emailId
是 SendCloud 投递一封邮件, 返回的邮件编号, 可以对应到某一次请求的某一个收件人.
两者的计算关系如下:
to = [A, B, C]
emailId_A = messageId + to.index(A) + '$' + A
emailId_B = messageId + to.index(B) + '$' + B
emailId_C = messageId + to.index(C) + '$' + C
# 注意:
* position 不做位数补齐
* 无论to中是否含有重复的值, 返回的emailidlist 跟发送列表的顺序都是相同的.
举例如下:
# to = ["ben@ifaxin.com", "joe@ifaxin.com", "bida@ifaxin.com", ... , "lianzimi@ifaxin.com"]
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound # messageId
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound0$ben@ifaxin.com # emailId
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound1$joe@ifaxin.com # emailId
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound2$bida@ifaxin.com # emailId
...
1425758592214_4576_32113_9310.sc-10_10_127_105-inbound99$lianzimi@ifaxin.com # emailId
maillistTaskId
当用户使用地址列表发送时, SendCloud 会调用后台服务来发送邮件, 这是一个异步调用过程. 而 SendCloud API 会返回用户一个 maillistTaskId
, 用户可以凭此值来查询地址列表发送的具体数据.
X-SMTPAPI 扩展字段
X-SMTPAPI 是 SendCloud 为开发者提供的邮件个性化定制的处理方式。
SendCloud 会检索 key 为 X-SMTPAPI
的头域信息,如果发现含有此头域, 则解析 value 的值用来改变邮件的处理方式。开发者在使用 SMTP 和 API 接入时都可以使用此字段。
API 方式:代码示例-普通发送 xsmtpapi
x_smtpapi = {
"to": ["d@163.com",'i@163.com'],
"sub": {
"%name%": ['jack', 'rose'],
"%money%": ['199', '299'],
},
}
params['xsmtpapi'] = simplejson.dumps(x_smtpapi)
SMTP 方式:代码示例-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)))
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值需为字符串
value 封装的 JSON 字符串的结构和用途见下:
to
含有收件人地址的数组, 指定邮件的收件人.
{
"to": ["ben@ifaxin.com", "joe@ifaxin.com"]
}
注意:
- 这里的
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 元.
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" }
}
}
}
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]}
}
}