任務管理
創建任務
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"
}