任务管理
创建任务
URL
https://email.api.engagelab.cc/v1/marketing/campaigns
HTTP 请求方式
POST
Content-Type
application/json; charset=utf-8
请求 Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
Body 参数
Parameter | Type | Required | Description |
---|---|---|---|
campaign_type | integer | true | 任务类型 1:A/B任务,2:普通任务 |
name | string | true | 任务名称(最长64个字符) |
to | object[] | true | 收件人,目前支持数组长度为1。 |
reply_to | string | false | 回复地址 |
sender_id | string | * | 发件人ID(仅支持普通任务) |
template_invoke_name | string | * | 邮件模板调用名称(仅支持普通任务) |
subject | string | * | 邮件主题,优先于邮件模板自带的主题,如果AB任务为内容测试,必填 |
send_time | string | * | 发送时间(仅支持普通任务),如2022-10-19 19:35:20 |
time_zone | integer | * | 默认是+8时区 |
attachments | object[] | false | 邮件附件(最多10个附件) |
filename | string | false | 附件文件名,如:example.pdf |
content | string | fasle | 附件内容的base64编码 |
ab_test | object | * | A/B任务的配置参数(仅支持A/B任务) |
google_track | object | false | google_track配置参数(仅支持普通任务) |
warm_up | object[] | false | 预热式发送配置参数(仅支持普通任务) |
说明:
1、所有附件文件大小的总和不能超过10MB。注意:文件在经过base64编码之后,会略微变大。这里的10MB限制,是指base64编码之前的大小。
参数to的格式有如下3种:
[
{
"type": "list",
"value": ["all"]
}
]
[
{
"type": "tag",
"value": ["tag1"]
}
]
[
{
"type": "segment",
"value": ["segment1"]
}
]
参数ab_test的格式如下:
当Campaign是A/B任务时,参数ab_test为必填字段
Parameter | Type | Required | Description |
---|---|---|---|
ab_test | object | true | A/B任务配置数据 |
percent | integer | true | 比例设置,取值范围[1, 100]。20表示20%的联系人作为测试收件人,剩下的按照胜利条件继续发送 |
win_condition | object | true | 确定A/B胜利者的条件 |
time_unit | string | true | 时间单位: day、hour |
after_time | integer | true | 在多少时间后计算胜利条件。时间单位是小时时,取值范围[0-23];时间单位是天时,取值范围[0-10] |
compare | string | true | 比较字段。取值如下:open_percent、click_percent、uni_open_percent、uni_click_percent、delivered_percent |
template_invoke_names | string[] | * | 邮件模板测试,template_invoke_name值被忽略,subject必填。 |
sender_ids | string[] | * | 发件人ID测试,sender_id值被忽略。 |
send_times | string[] | * | 发送时间测试,send_time值被忽略。 |
subjects | string[] | * | 邮件主题测试,subject值被忽略。 |
示例如下:
// A/B测试,不同的邮件主题
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"subjects": []
}
// A/B测试,不同的邮件模板
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"template_invoke_names": []
}
// A/B测试,不同的sender
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"sender_ids": []
}
// A/B测试,不同的发送时间
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"send_times": []
}
说明:
- ab_test的配置,目前只支持单个测试项。
参数google_track的格式如下:
配置google_track的参数,系统会将这些参数添加到邮件的链接中。追踪客户从任务到网站的流量,便于在google_analysis工具里分析你的网站。
Parameter | Type | Required | Description |
---|---|---|---|
google_track | object | false | Google track配置参数 |
campaign_name | string | false | Campaign name (最长64个字符) |
campaign_source | string | false | Source (最长64个字符) |
campaign_medium | string | false | Medium (最长64个字符) |
campaign_term | string | false | Keyword (最长64个字符) |
campaign_content | string | false | Content (最长64个字符) |
示例如下:
"google_track": {
"campaign_name":"",
"campaign_source":"",
"campaign_medium":"",
"campaign_term":"",
"campaign_content":""
}
参数warm_up的格式如下:
预热式发送,可以针对某些收信域,设定每小时、每天的发送数量,可以提高送达率。同时,可以根据送达率的高低,来调整发送速率的变化。
Parameter | Type | Required | Description |
---|---|---|---|
warm_up | object[] | false | 预热式发送的配置参数,最大长度20 |
domain | string | true | 收信域 |
rate | integer | true | 发信速率的级别 |
upgrade_value | float | true | 速率升级的送达率指标,取值为(0,1]的小数 |
downgrade_value | float | true | 速率降级的送达率指标,取值为(0,1]的小数 |
示例如下:
"warm_up": [{
"domain": "gmail.com",
"rate": 1,
"upgrade_value": "0.95",
"downgrade_value": "0.75"
}, {
"domain": "hotmail.com",
"rate": 3,
"upgrade_value": "0.95",
"downgrade_value": "0.75"
}]
请求示例
创建普通任务
curl -X POST -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns --data '{
"campaign_type": 1,
"name": "11.11_leon_api8",
"to":[{
"type": "tag",
"value": ["tag1"]
}],
"sender_id": "53",
"reply_to": "",
"template_invoke_name": "leon2_shanshan",
"subject": "happy new year",
"run_time": "2022-10-26 17:10:20",
"time_zone":"8",
"attachments":[{
"content":"base64 content",
"file_name":"1.jpg"
},{
"content":"base64 content",
"file_name":"2.jpg"
}],
"warm_up": [{
"domain":"gmail.com",
"rate":1,
"upgrade_value":"0.95",
"downgrade_value":"0.75"
},{
"domain":"hotmail.com",
"rate":1,
"upgrade_value":"0.95",
"downgrade_value":"0.75"
}],
"google_track":{
"campaign_name":"",
"campaign_source":"",
"campaign_medium":"",
"campaign_term":"",
"campaign_content":""
}
}
'
创建AB任务
curl -X POST -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns --data '{
"campaign_type": 2,
"name": "11.11_leon_api9",
"to":[{
"type": "list",
"value": ["all"]
}],
"sender_id": "53",
"reply_to": "reply@sendcloud.im",
"template_invoke_name": "leon2_shanshan",
"subject": "happy new year",
"run_time": "2022-10-26T17:10:20+0800",
"time_zone":"8",
"attachments":[{
"content":"base64 content",
"file_name":"1.jpg"
}
],
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"template_invoke_names": []
},
"google_track":{
"campaign_name":"",
"campaign_source":"",
"campaign_medium":"",
"campaign_term":"",
"campaign_content":""
}
}'
响应示例
Response-Success
HttpStatus: 200
{
"result": {
"campaign_id": 34007,
"campaign_type": 2,
"name": "testddd",
"to": {
"type": "tag",
"value": ["tag1"]
},
"template_invoke_name": "leon2_shanshan",
"reply_to": "",
"status": 2,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"run_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"sender_id": 21,
"google_track": {
"campaign_name":"",
"campaign_source":"",
"campaign_medium":"",
"campaign_term":"",
"campaign_content":""
},
"warm_up": [{
"domain":"hotmail.com",
"rate":1,
"upgrade_value":"0.95",
"downgrade_value":"0.75"
},{
"domain":"hotmail.com",
"rate":1,
"upgrade_value":"0.95",
"downgrade_value":"0.75"
}],
}
}
a/b test任务响应示例
{
"result": {
"campaign_id": 34009,
"campaign_type": 2,
"name": "testddd",
"to":[{
"type": "list",
"value": ["all"]
}],
"template_invoke_name": "leon2_shanshan",
"reply_to": "",
"status": 0,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"run_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"sender_id": 21,
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"template_invoke_names": []
},
"google_track": {
"campaign_name":"",
"campaign_source":"",
"campaign_medium":"",
"campaign_term":"",
"campaign_content":""
}
}
}
Response-Error
HttpStatus: 401
{
"code": 32112,
"message": "name cannot be empty"
}
删除任务
URL
https://email.api.engagelab.cc/v1/marketing/campaigns/{campaign_id}
HTTP 请求方式
DELETE
Content-Type
application/x-www-form-urlencoded;charset=utf-8
请求 Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
请求示例
curl -X DELETE -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns/8
响应示例
Response-Succes
HttpStatus: 200
{
"count": 1
}
Response-Error
HttpStatus: 401
{
"code": 30000,
"message": "Authentication failed"
}
更新任务
URL
https://email.api.engagelab.cc/v1/marketing/campaigns/{campaign_id}
HTTP 请求方式
PUT
Content-Type
application/json; charset=utf-8
请求 Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Bearer Token |
Body 参数
Parameter | Type | Required | Description |
---|---|---|---|
campaign_type | integer | true | 任务类型 1:A/B任务,2:普通任务 |
name | string | true | 任务名称(最长64个字符) |
to | object[] | true | 收件人,目前支持数组长度为1。 |
reply_to | string | false | 回复地址 |
sender_id | string | * | 发件人ID(仅支持普通任务) |
template_invoke_name | string | * | 邮件模板调用名称(仅支持普通任务) |
subject | string | * | 邮件主题(如果AB任务时、必填) |
send_time | string | * | 发送时间(仅支持普通任务),如2022-10-19 19:35:20 |
time_zone | integer | * | 默认是+8时区 |
attachments | object[] | false | 邮件附件(最多10个附件) |
filename | string | false | 附件文件名,如:example.pdf |
content | text | fasle | 附件内容的base64编码 |
ab_test | object | * | A/B任务的配置参数(仅支持A/B任务) |
google_track | object | false | google_track配置参数 |
warm_up | object[] | false | 预热式发送配置参数(仅支持普通任务) |
请求示例
curl -X PUT -H ' application/json; charset=utf-8' -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns/8 --data '{
"name":"11.11_leon_api8"
}'
响应示例
Response-Success
HttpStatus: 200
{
"count": 1
}
Response-Error
{
"code": 32110,
"message": "The current campaign has been executed and cannot be modified"
}
任务列表
URL
https://email.api.engagelab.cc/v1/marketing/campaigns
HTTP 请求方式
GET
Content-Type
application/x-www-form-urlencoded;charset=utf-8
请求 Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
Query 参数
Parameter | Type | Required | Description |
---|---|---|---|
campaign_type | integer | false | 任务类型 1.A/B任务 2.普通任务 |
status | integer | false | 任务状态(0.待发送,1.发送中,2.已完成,-1.失败) |
name | string | false | 任务名称 |
limit | integer | false | 查询个数, 取值区间 [1-100], 默认为 10 |
offset | integer | false | 查询起始位置, 取值区间 [0-],默认为 0 |
请求示例
curl -X GET -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns?&status=2
响应示例
Response-Success
HttpStatus:200
{
"result": [
{
"campaign_id": 34007,
"campaign_type": 1,
"name": "testddd",
"to":[{
"type": "list",
"value": ["all"]
}],
"template_invoke_name": "leon2_shanshan",
"reply_to": "",
"status": 2,
"google_track": null,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"run_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"warm_up": [],
"sender_id": 21,
"from_email": "xjmfc23@legendnovel.com",
"from_name": "aaaa",
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"template_invoke_names": []
}
],
"total": 2
}
Response-Error
{
"code": 30000,
"message": "Authentication failed"
}
任务详情
URL
https://email.api.engagelab.cc/v1/marketing/campaigns/{campaign_id}
HTTP 请求方式
GET
Content-Type
application/x-www-form-urlencoded;charset=utf-8
请求 Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
请求示例
curl -X GET -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns/33761
响应说明
Parameter | Type | Description |
---|---|---|
name | string | 任务名称 |
to | object[] | 收件人,目前支持数组长度为1。 |
campaign_id | integer | 任务 ID |
campaign_type | integer | 任务类型 1 A/B任务 2普通任务 |
template_invoke_name | string | 模板调用名称 |
reply_to | string | 回复地址 |
status | integer | 任务状态 (0.待发送,1.发送中,2.已完成,-1.失败) |
from_email | string | 发件人ID对应的发件人地址 |
from_name | string | 发件人ID对应的昵称 |
sender_id | integer | 发件人 ID |
create_time | string | 创建时间(UTC+8) |
update_time | string | 更新时间(UTC+8) |
run_time | string | 运行时间(UTC+8) |
time_tone | integer | 时区(参考时区字典) |
complete_time | string | 完成时间(UTC+8) |
google_track | object | google_track配置参数 |
warm_up | array[object] | 预热式发送配置参数(仅支持普通任务) |
ab_test | object | A/B测试配置 |
响应示例
Response-Success
HttpStatus: 200
{
"result": {
"campaign_id": 34007,
"campaign_type": 1,
"name": "testddd",
"to":[{
"type": "list",
"value": ["all"]
}],
"from_email": "xjmfc23@legendnovel.com",
"from_name": "aaaa",
"template_invoke_name": "leon2_shanshan",
"reply_to": "",
"status": 2,
"google_track": null,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"run_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"warm_up": null,
"sender_id": 21,
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"template_invoke_names": []
}
}
Response-Error
{
"code": 30000,
"message": "Authentication failed"
}