任務管理
調用地址
| 數據中心 | URL | 
|---|---|
| 新加坡 | https://email.api.engagelab.cc | 
| 土耳其 | https://emailapi-tr.engagelab.com | 
當使用REST API時,需要確認使用的數據中心選擇對應的base URL。
POST/v1/marketing/campaigns
創建任務
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"
}
            
            







