Campaigns
Create
URL
https://email.api.engagelab.cc/v1/marketing/campaigns
HTTP Request Method
POST
Content-Type
application/json; charset=utf-8
Request-Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
Body-Parameters
Parameter | Type | Required | Description |
---|---|---|---|
campaign_type | integer | true | Task type: 1 for A/B test, 2 for regular campaign |
name | string | true | Task name (up to 64 characters) |
to | object[] | true | Recipients, currently supports an array length of 1 |
reply_to | string | false | Reply address |
sender_id | string | * | Sender ID (only supported for regular campaign) |
template_invoke_name | string | * | Template invoke name (only supported for regular campaign) |
subject | string | * | Email subject, takes priority over the built-in template subject. Required if AB test is a content test |
send_time | string | * | Send time (only supported for regular tasks), format: "YYYY-MM-DD HH:mm:ss" |
time_zone | integer | * | Default time zone (+8 by default) |
attachments | object[] | false | Email attachments (up to 10 attachments) |
filename | string | false | Attachment file name, e.g., example.pdf |
content | string | false | Attachment content in base64 encoding |
ab_test | object | * | A/B test configuration parameters (only supported for A/B test) |
google_track | object | false | Google Track configuration parameters (only supported for regular campaign) |
warm_up | object[] | false | Warm-up sending configuration parameters (only supported for regular campaign) |
Note:
- The total size of all attachment files must not exceed 10MB. Please note that the size of files slightly increases after base64 encoding. The 10MB limit refers to the size before base64 encoding.
The three formats for the "to" parameter are:
[
{
"type": "list",
"value": ["all"]
}
]
[
{
"type": "tag",
"value": ["tag1"]
}
]
[
{
"type": "segment",
"value": ["segment1"]
}
]
The format of the parameter "ab_test" is as follows:
When Campaign is an A/B test, the "ab_test" parameter is required.
Parameter | Type | Required | Description |
---|---|---|---|
ab_test | object | true | A/B test configuration data |
percent | integer | true | Percentage setting, range [1, 100]. For example, 20 means 20% of contacts are selected as test recipients, while the rest are sent based on the winning condition |
win_condition | object | true | Determines the winning condition for the A/B test |
time_unit | string | true | Time unit: day, hour |
after_time | integer | true | How long to wait before calculating the winning condition. If the time unit is hours, the range is [0-23]; if the time unit is days, the range is [0-10] |
compare | string | true | Comparison field. Possible values: open_percent, click_percent, uni_open_percent, uni_click_percent, delivered_percent |
template_invoke_names | string[] | * | Template testing. The template_invoke_name value is ignored, subject is required |
sender_ids | string[] | * | Sender ID testing. The sender_id value is ignored |
send_times | string[] | * | Send time testing. The send_time value is ignored |
subjects | string[] | * | Email subject testing. The subject value is ignored |
Example is as follows:
// 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": []
}
Note:
- The configuration of ab_test currently only supports a single test item
The format of the google_track parameter is as follows:
Configure the parameters for google_track, and the system will add these parameters to the links in emails. Track customer traffic from campaigns to your website, enabling analysis in Google Analytics.
Parameter | Type | Required | Description |
---|---|---|---|
google_track | object | false | Google track configuration parameters |
campaign_name | string | false | Campaign name (up to 64 characters) |
campaign_source | string | false | Source (up to 64 characters) |
campaign_medium | string | false | Medium (up to 64 characters) |
campaign_term | string | false | Keyword (up to 64 characters) |
campaign_content | string | false | Content (up to 64 characters) |
Example is as follows:
"google_track": {
"campaign_name":"",
"campaign_source":"",
"campaign_medium":"",
"campaign_term":"",
"campaign_content":""
}
The format of the parameter "warm_up" is as follows:
Warm-up sending allows setting the number of emails per hour or per day for specific recipient domains, which can improve deliverability. Additionally, the sending rate can be adjusted based on the observed deliverability.
Parameter | Type | Required | Description |
---|---|---|---|
warm_up | object[] | false | Configuration parameters for warm-up sending, with a maximum length of 20 |
domain | string | true | Recipient domain |
rate | integer | true | Level of sending rate |
upgrade_value | float | true | Deliverability threshold for rate upgrade, a decimal value between (0,1] |
downgrade_value | float | true | Deliverability threshold for rate downgrade, a decimal value between (0,1] |
Example is as follows:
"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"
}]
Request-Example
Create a regular campaign
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":""
}
}
'
Create a A/B campaign
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 example
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 campaign response example
{
"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"
}
Delete
URL
https://email.api.engagelab.cc/v1/marketing/campaigns/{campaign_id}
HTTP Request Method
DELETE
Content-Type
application/x-www-form-urlencoded;charset=utf-8
Request-Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
Request-Example
curl -X DELETE -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns/8
Response example
Response-Succes
HttpStatus: 200
{
"count": 1
}
Response-Error
HttpStatus: 401
{
"code": 30000,
"message": "Authentication failed"
}
Update
URL
https://email.api.engagelab.cc/v1/marketing/campaigns/{campaign_id}
HTTP Request Method
PUT
Content-Type
application/json; charset=utf-8
Request-Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Bearer Token |
Body-Parameters
Parameter | Type | Required | Description |
---|---|---|---|
campaign_type | integer | true | Type of campaign: 1 for A/B test, 2 for regular campaign |
name | string | true | Campaign name (up to 64 characters) |
to | object[] | true | Recipients, currently supports an array of size 1 |
reply_to | string | false | Reply address |
sender_id | string | * | Sender ID (only supported for regular campaigns) |
template_invoke_name | string | * | Name of the email template to be invoked (only supported for regular campaigns) |
subject | string | * | Email subject (required for A/B tests) |
send_time | string | * | Sending time (only supported for regular tasks), format: YYYY-MM-DD HH:mm:ss |
time_zone | integer | * | Default time zone, usually +8 |
attachments | object[] | false | Email attachments (up to 10 attachments) |
filename | string | false | Attachment file name, e.g., example.pdf |
content | text | false | Base64 encoded content of the attachment |
ab_test | object | * | Configuration parameters for A/B tests (only supported for A/B tests) |
google_track | object | false | Configuration parameters for Google tracking |
warm_up | object[] | false | Configuration parameters for warm-up sending (only supported for regular campaigns) |
Request-Example:
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 example
Response-Success
HttpStatus: 200
{
"count": 1
}
Response-Error
{
"code": 32110,
"message": "The current campaign has been executed and cannot be modified"
}
Campaign list
URL
https://email.api.engagelab.cc/v1/marketing/campaigns
HTTP request method
GET
Content-Type
application/x-www-form-urlencoded;charset=utf-8
Request-Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
Query-Parameters
Parameter | Type | Required | Description |
---|---|---|---|
campaign_type | integer | false | Campaign type: 1. A/B campaign, 2. regular campaign |
status | integer | false | Campaign status: 0. Pending, 1. In progress, 2. Completed, -1. Failed |
name | string | false | Campaign name |
limit | integer | false | Number of results to retrieve, range [1-100], default is 10 |
offset | integer | false | Starting position for the query, range [0-], default is 0 |
Request-Example
curl -X GET -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns?&status=2
Response example
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"
}
Campaign details
URL
https://email.api.engagelab.cc/v1/marketing/campaigns/{campaign_id}
HTTP request method
GET
Content-Type
application/x-www-form-urlencoded;charset=utf-8
Request-Headers
Header | Type | Required | Description |
---|---|---|---|
Authorization | string | true | Basic base64(api_user:api_key) |
Request-Example
curl -X GET -H 'Authorization:Basic YXBpX3VzZXI6YXBpX2tleQ==' -i https://email.api.engagelab.cc/v1/marketing/campaigns/33761
Response-Parameters
Parameter | Type | Description |
---|---|---|
name | string | Campaign name |
to | object[] | Recipients, currently supports an array with a length of 1. |
campaign_id | integer | Campaign ID |
campaign_type | integer | Campaign type: 1 for A/B test, 2 for regular campaign |
template_invoke_name | string | Template invocation name |
reply_to | string | Reply-to address |
status | integer | Campaign status (0: pending, 1: in progress, 2: completed, -1: failed) |
from_email | string | Sender's email address |
from_name | string | Sender's nickname |
sender_id | integer | Sender ID |
create_time | string | Creation time (UTC+8) |
update_time | string | Update time (UTC+8) |
run_time | string | Run time (UTC+8) |
time_tone | integer | Timezone (refer to timezone dictionary) |
complete_time | string | Completion time (UTC+8) |
google_track | object | Google Track configuration parameters |
warm_up | array[object] | Warm-up sending configuration parameters (only supported for regular campaigns) |
ab_test | object | A/B test configuration |
Response example
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"
}