任務管理
調用地址
| 資料中心 | URL |
|---|---|
| 新加坡 | https://email.api.engagelab.cc |
| 土耳其 | https://emailapi-tr.engagelab.com |
| 美國 | https://emailapi-us.engagelab.com |
使用 REST API 時,請確認所選資料中心與對應的基礎 URL 相符。
POST/v1/marketing/campaigns
建立
URL
https://email.api.engagelab.cc/v1/marketing/campaigns
HTTP 請求方法
POST
Content-Type
application/json; charset=utf-8
請求標頭
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | true | Basic base64(api_user:api_key) |
請求體參數
| 參數 | Type | 必填 | 說明 |
|---|---|---|---|
| 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 | * | 電子郵件主旨,優先於範本內建主旨。若 A/B 測試為內容測試則為必填 |
| send_time | string | * | 傳送時間(僅支援一般任務),格式:"YYYY-MM-DD HH:mm:ss" |
| time_zone | string | * | 預設時區(預設 +8),例如 +8 |
| attachments | object[] | false | 電子郵件附件(最多 10 個附件) |
| file_name | string | false | 附件檔案名稱,例如 example.pdf |
| content | string | false | 以 base64 編碼的附件內容 |
| ab_test | object | * | A/B 測試設定參數(僅支援 A/B 測試) |
| google_track | object | false | Google Track 設定參數(僅支援一般行銷活動) |
| warm_up | object[] | false | 預熱發送設定參數(僅支援一般行銷活動) |
注意:
所有附件檔案的總大小不得超過 10MB。請注意,檔案在 base64 編碼後大小會略微增加。10MB 的限制是指 base64 編碼前的大小。
template_invoke_name必須引用批次範本(template_type=1);觸發範本(template_type=0)不能用於行銷活動。對於to,list使用all,segment或tag分別使用分眾 ID 或標籤 ID。
"to" 參數的五種格式如下:
[
{
"type": "list",
"value": ["all"]
}
]
[
{
"type": "tag",
"value": ["62386112014b7b2f912fddd1"]
}
]
[
{
"type": "not_tag",
"value": ["62386112014b7b2f912fddd3"]
}
]
[
{
"type": "segment",
"value": ["62386112014b7b2f912fddd2"]
}
]
[
{
"type": "not_segment",
"value": ["62386112014b7b2f912fddd4"]
}
]
[
{
"type": "tag",
"value": ["62386112014b7b2f912fddd1"]
},
{
"type": "not_tag",
"value": ["62386112014b7b2f912fddd3"]
}
]
> 注意:`type` 可以是 `list`(所有聯絡人,值固定為 `["all"]`)、`tag`(標籤)、`not_tag`(排除的標籤)、`segment`(分眾)或 `not_segment`(排除的分眾);`value` 為對應 ID 的陣列。`not_tag` 與 `not_segment` 為新增功能。
"ab_test" 參數的格式如下:
當行銷活動為 A/B 測試時,"ab_test" 參數為必填。
| 參數 | Type | 必填 | 說明 |
|---|---|---|---|
| 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 testing, different email subjects
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"subjects": []
}
// A/B testing, different email templates
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"template_invoke_names": []
}
// A/B testing, different senders
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"sender_ids": []
}
// A/B testing, different sending times.
"ab_test": {
"percent": 20,
"win_condition": {
"time_unit": "hour",
"after_time": 18,
"compare": "open_percent"
},
"send_times": []
}
注意:
- ab_test 的設定目前僅支援單一測試項目
google_track 參數的格式如下:
設定 google_track 的參數後,系統會將這些參數加入電子郵件中的連結。可追蹤從行銷活動到網站的客戶流量,以便在 Google Analytics 中進行分析。
| 參數 | Type | 必填 | 說明 |
|---|---|---|---|
| google_track | object | false | Google Track 設定參數 |
| campaign_name | string | false | 行銷活動名稱(最多 64 個字元) |
| campaign_source | string | false | 來源(最多 64 個字元) |
| campaign_medium | string | false | 媒介(最多 64 個字元) |
| campaign_term | string | false | 關鍵字(最多 64 個字元) |
| campaign_content | string | false | 內容(最多 64 個字元) |
範例如下:
"google_track": {
"campaign_name":"",
"campaign_source":"",
"campaign_medium":"",
"campaign_term":"",
"campaign_content":""
}
"warm_up" 參數的格式如下:
預熱發送可針對特定收件者網域設定每小時或每日的郵件數量,有助於提升送達率。此外,可根據觀察到的送達率調整發送速率。
| 參數 | Type | 必填 | 說明 |
|---|---|---|---|
| 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": 2,
"name": "11.11_leon_api8",
"to":[{
"type": "tag",
"value": ["62386112014b7b2f912fddd1"]
}],
"sender_id": "53",
"reply_to": "",
"template_invoke_name": "leon2_shanshan",
"subject": "happy new year",
"send_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":""
}
}
'
建立 A/B 行銷活動
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_api9",
"to":[{
"type": "list",
"value": ["all"]
}],
"sender_id": "53",
"reply_to": "reply@sendcloud.im",
"template_invoke_name": "leon2_shanshan",
"subject": "happy new year",
"send_time": "2022-10-26 17:10:20",
"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": 36894,
"campaign_type": 2,
"name": "testddd",
"to": [{
"type": "tag",
"value": ["62386112014b7b2f912fddd1"]
}],
"subject": "happy new year",
"label_id": [617450],
"template_invoke_name": "leon2_shanshan",
"reply_to": null,
"status": 2,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"send_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"zone_id": "Beijing, Chongqing, Hong Kong, Urumqi",
"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 測試行銷活動回應範例
{
"result": {
"campaign_id": 36895,
"campaign_type": 1,
"name": "testddd",
"to":[{
"type": "list",
"value": ["all"]
}],
"subject": null,
"label_id": null,
"template_invoke_name": "leon2_shanshan",
"reply_to": null,
"status": 0,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"send_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"zone_id": "Beijing, Chongqing, Hong Kong, Urumqi",
"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
請求標頭
| 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/{campaign_id}
回應範例
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
請求標頭
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | true | Basic base64(api_user:api_key) |
請求體參數
| 參數 | Type | 必填 | 說明 |
|---|---|---|---|
| campaign_type | integer | true | 行銷活動類型:1 為 A/B 測試,2 為一般行銷活動 |
| name | string | false | 行銷活動名稱(最多 64 個字元) |
| to | object[] | false | 收件人,目前支援大小為 1 的陣列 |
| reply_to | string | false | 回覆地址 |
| sender_id | string | * | 寄件者 ID(僅支援一般行銷活動) |
| template_invoke_name | string | * | 要調用的電子郵件範本名稱(僅支援一般行銷活動) |
| subject | string | * | 電子郵件主旨(A/B 測試必填) |
| send_time | string | * | 傳送時間(僅支援一般任務),格式:YYYY-MM-DD HH:mm:ss |
| time_zone | string | * | 預設時區,通常為 +8 |
| attachments | object[] | false | 電子郵件附件(最多 10 個附件) |
| file_name | string | false | 附件檔案名稱,例如 example.pdf |
| content | string | false | base64 編碼的附件內容 |
| ab_test | object | * | A/B 測試的設定參數(僅支援 A/B 測試) |
| google_track | object | false | Google 追蹤的設定參數 |
| 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/{campaign_id} --data '{
"name":"11.11_leon_api8"
}'
回應範例
Response-Success
HttpStatus: 200
{
"result": {
"campaign_id": 36894,
"campaign_type": 2,
"name": "testddd",
"to": [{
"type": "tag",
"value": ["62386112014b7b2f912fddd1"]
}],
"subject": "happy new year",
"label_id": [617450],
"template_invoke_name": "leon2_shanshan",
"reply_to": null,
"status": 2,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"send_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"zone_id": "Beijing, Chongqing, Hong Kong, Urumqi",
"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"
}],
}
}
}
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
請求標頭
| Header | Type | Required | Description |
|---|---|---|---|
| Authorization | string | true | Basic base64(api_user:api_key) |
查詢參數
| 參數 | Type | 必填 | 說明 |
|---|---|---|---|
| campaign_type | integer | false | 行銷活動類型:1. A/B 行銷活動,2. 一般行銷活動 |
| status | integer | false | 行銷活動狀態:0. 待處理,1. 進行中,2. 已完成,-1. 失敗 |
| name | string | false | 行銷活動名稱 |
| to_type | integer | false | 收件人類型:0 所有聯絡人,1 分眾,2 標籤 |
| to_value | string | false | 收件人範圍 ID;類型為 1 或 2 時使用分眾 ID 或標籤 ID |
| 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": 36894,
"campaign_type": 1,
"name": "testddd",
"to":[{
"type": "list",
"value": ["all"]
}],
"subject": null,
"label_id": null,
"template_invoke_name": "leon2_shanshan",
"reply_to": null,
"status": 2,
"google_track": null,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"send_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"zone_id": "Beijing, Chongqing, Hong Kong, Urumqi",
"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": []
},
"report_summary": {
"targets": 4,
"sent": 4,
"delivered": 2,
"invalid_email": 2,
"soft_bounce": 0,
"billing_count": 2,
"total_clicks": 1,
"total_opens": 2
}
}
],
"total": 2,
"count": 1
}
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
請求標頭
| 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/{campaign_id}
回應參數
| 參數 | Type | 說明 |
|---|---|---|
| name | string | 行銷活動名稱 |
| to | object[] | 收件人,目前支援長度為 1 的陣列。 |
| campaign_id | integer | 行銷活動 ID |
| campaign_type | integer | 行銷活動類型:1 為 A/B 測試,2 為一般行銷活動 |
| template_invoke_name | string | 範本調用名稱 |
| reply_to | string | 回覆地址(Reply-to) |
| status | integer | 行銷活動狀態 (0: 待處理,1: 進行中,2: 已完成,-1: 失敗) |
| from_email | string | 寄件者電子郵件地址 |
| from_name | string | 寄件者暱稱 |
| sender_id | integer | 寄件者 ID |
| create_time | string | 建立時間 (UTC+8) |
| update_time | string | 更新時間 (UTC+8) |
| send_time | string | 傳送時間 (UTC+8) |
| time_zone | string | 時區,例如 +8 |
| complete_time | string | 完成時間 (UTC+8) |
| google_track | object | Google Track 設定參數 |
| warm_up | array[object] | 預熱發送設定參數(僅支援一般行銷活動) |
| ab_test | object | A/B 測試設定 |
| subject | string | 電子郵件主旨(A/B 測試任務為 null) |
| label_id | array[integer] | 行銷活動標籤 ID 陣列,從 task_template.label_id 解析;未設定則為 null |
| zone_id | string | 時區 ID,例如 "Beijing, Chongqing, Hong Kong, Urumqi" |
回應範例
Response-Success
HttpStatus: 200
{
"result": {
"campaign_id": 36894,
"campaign_type": 1,
"name": "testddd",
"to":[{
"type": "list",
"value": ["all"]
}],
"subject": null,
"label_id": null,
"from_email": "xjmfc23@legendnovel.com",
"from_name": "aaaa",
"template_invoke_name": "leon2_shanshan",
"reply_to": null,
"status": 2,
"google_track": null,
"create_time": "2022-09-27T16:36:32+0800",
"update_time": "2022-10-12T00:00:00+0800",
"send_time": "2022-09-27T16:41:23+0800",
"complete_time": "2022-10-12T00:00:00+0800",
"time_zone": "+8",
"zone_id": "Beijing, Chongqing, Hong Kong, Urumqi",
"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"
}










