任务管理

创建任务

URL:

https://api2.sendcloud.net/marketing/campaigns

Method: POST

Content-Type: multipart/form-data; charset=utf-8

Request-Headers:

Header	Type	Required	Description
Authorization	string	true	Bearer Token

Body-Parameters:

Parameter	Type	Required	Description
attachments	file	false	files附件（最多10个附件），在taskType=2的情况，才支持附件
campaignJson	string	true	json字符串
└─taskType	integer	true	任务类型 1 A/B任务 2普通任务
└─name	string	true	任务名称((最长64个字符)
└─to	string	true	收件人： sendListType=0，to 传 all sendListType=1，to 传 segmentId sendListType=2，to 传值 tagId
└─sendListType	string	true	发送类型(0.联系人，1.segment，2. tag)
└─senderId	string	true	发件人 ID
└─replyTo	string	false	回复地址
└─templateInvokeName	string	true	模板调用名称
└─googleTrack	object	false	googleTrack配置，在taskType=2的情况，才支持
└─campaignName	string	false	活动名称 (最大长度64个字符)
└─campaignSource	string	false	来源 (最大长度64个字符)
└─campaignMedium	string	false	媒体 (最大长度64个字符)
└─campaignTerm	string	false	关键词 (最大长度64个字符)
└─campaignContent	string	false	内容 (最大长度64个字符)
└─runTime	string	true	运行时间,如2022-10-19 19:35:20
└─timeZone	integer	true	时区(参考时区字典)，不填默认是+8时区
└─warmUpConfigList	object[]	false	预热配置 ，在taskType=2的情况，才支持
└─domain	string	false	域名
└─rate	integer	false	速率
└─upgradeValue	double	false	速率上调阈值 取值区间(0,1)不包含0和1
└─downgradeValue	double	false	速率下调阈值 取值区间(0,1)不包含0和1
└─abTestPercent	string	false	比例设置(值范围1 - 100),如 20 表示 20%的联系人作为测试收件人
└─abTestWinCondition	object	false	确定A/B胜利者的条件
└─timeUnit	integer	true	时间单位: 1为小时 2为天
└─afterTime	integer	true	在多少时间后开始执行: 时间单位是小时时，仅支持填写 大于0，小于23的正整数; 时间单位是天时，仅支持填写 大于0，小于10的正整数
└─compare	integer	true	比较类型： 1打开率 2点击率 3独立打开率 4独立点击率 5送达率
└─abTestItemConfig	object	false	测试项
└─testItemType	integer	true	测试项类别 1.邮件主题 2.邮件内容 3.发件人 4.发送时间
└─itemContentOne	string	true	根据测试项类别不同而不同；1.邮件主题——填写邮件的主题 2.邮件内容——填写邮件模板的templateInvokeName 3.发件人——发件人Id 4.发送时间——发送时间,格式为yyyy-MM-dd HH:mm:ss
└─itemContentTwo	string	true	根据测试项类别不同而不同
└─itemContentThree	string	true	根据测试项类别不同而不同
└─templateSubject	string	true	测试项类别为2时 - 自定义的模板主题

说明

1. taskType=1 A/B任务时，googleTrack和warmUpConfigList若传递则忽略参数值，系统赋值为null。可以不传或为null。
2. taskType=1 A/B任务时，abTestPercent，abTestWinCondition，timeUnit，afterTime，compare，abTestItemConfig，testItemType 是必填项；
3. taskType=1 A/B任务时，itemContentOne、itemContentTwo、itemContentThree这三个测试项最少传2个
4. taskType=1 A/B任务时，itemContentOne、itemContentTwo、itemContentThree是同一测试项类别的三个值，不能重复，runTime必须是这三个值的最早的时间
5. taskType=2 普通任务时，如果设置 googleTrack 值，则 campaignName、campaignSource，campaignMedium 是必填项，googleTrack可以不传或为null。
6. taskType=2 普通任务时，如果设置 warmUpConfigList 值，则 domain、rate、upgradeValue、downgradeValue 是必填项，warmUpConfigList可以不传或为null。
7. runTime必须大于timeZone时区的当前时间
8. 总计33个参数

Request-Example:

curl -X POST -H 'Content-Type: multipart/form-data; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/campaigns -F 'campaignJson={
    "taskType":1,
    "name":"11.11_leon_api8",
    "to":"632a9c7954094e458d7ff327",
    "sendListType":"1",
    "senderId":"53",
    "replyTo":"",
    "templateInvokeName":"leon2_shanshan",
    "googleTrack":{
        "campaignName":"6181",
        "campaignSource":"jingdong",
        "campaignMedium":"tiktok",
        "campaignTerm":"offset 300",
        "campaignContent":"tv"
    },
    "runTime":"2022-10-26 17:10:20",
    "timeZone":"8",
    "warmUpConfigList":[
        {
            "domain":"gmail.com",
            "rate":1,
            "upgradeValue":0.95,
            "downgradeValue":0.85
        },
        {
            "domain":"outlook.com",
            "rate":1,
            "upgradeValue":0.95,
            "downgradeValue":0.85
        }
    ],
    "emptyExistedAttachments":0,
    "abTestPercent":"20",
    "abTestWinCondition":{
        "timeUnit":1,
        "afterTime":5,
        "compare":3
    },
    "abTestItemConfig":{
        "testItemType":4,
        "itemContentOne":"2022-10-26 17:55:20",
        "itemContentTwo":"2022-10-26 17:40:20",
        "itemContentThree":"2022-10-26 17:10:20",
        "templateSubject":""
    }
}' \
  -F attachments=@4d58874449847899f9567bf687769fea.png

Response-Success:

HttpStatus: 201

Response:

{
    "campaignId": 33774
}

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}

删除任务

URL:

https://api2.sendcloud.net/marketing/campaigns/{campaignId}

Method: DELETE

Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request-Headers:

Header	Type	Required	Description
Authorization	string	true	Bearer Token

Path-parameters:

Parameter	Type	Required	Description
campaignId	string	true	任务 ID

Request-Example:

curl -X DELETE -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/campaigns/8

Response-Success

HttpStatus: 204

Response:

{}

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}

更新任务

URL:

 https://api2.sendcloud.net/marketing/campaigns/{campaignId}

Method: PATCH

Content-Type: multipart/form-data; charset=utf-8

Request-Headers:

Header	Type	Required	Description
Authorization	string	true	Bearer Token

Path-parameters:

Parameter	Type	Required	Description
campaignId	string	true	任务 ID

Body-Parameters:

Parameter	Type	Required	Description
attachments	file	false	files附件（最多10个附件），在taskType=2的情况，才支持附件
campaignJson	string	true	json字符串
└─emptyExistedAttachments	integer	false	置空已有附件 0沿用原有附件;1置空原有附件，不传默认为0 .更新时attachments不传，但原记录有附件，此时该参数决定是沿用原来的附件，还是将原来的附件置空;更新时attachments传递，则忽略此参数使用传递的附件更新
└─taskType	integer	true	任务类型 1 A/B任务 2普通任务，不能改变taskType类型
└─name	string	true	任务名称((最长64个字符)
└─to	string	true	收件人： sendListType=0，to 传 all sendListType=1，to 传 segmentId sendListType=2，to 传值 tagId
└─sendListType	string	true	发送类型(0. 联系人， 1.segment，2.tag)
└─senderId	string	true	发件人 ID
└─replyTo	string	false	回复地址
└─templateInvokeName	string	true	模板调用名称
└─googleTrack	object	false	google track配置，在taskType=2的情况，才支持
└─campaignName	string	false	活动名称 (最大长度64个字符)
└─campaignSource	string	false	来源 (最大长度64个字符)
└─campaignMedium	string	false	媒体 (最大长度64个字符)
└─campaignTerm	string	false	关键词 (最大长度64个字符)
└─campaignContent	string	false	内容 (最大长度64个字符)
└─runTime	string	false	运行时间(格式:2022-06-09 15:02:40)
└─timeZone	integer	false	时区(参考时区字典)，不填默认是+8时区
└─warmUpConfigList	object[]	false	预热配置 在taskType=2的情况，才支持
└─domain	string	false	域名
└─rate	integer	false	速率
└─upgradeValue	double	false	速率上调阈值 取值区间(0,1)不包含0和1
└─downgradeValue	double	false	速率下调阈值 取值区间(0,1)不包含0和1
└─abTestPercent	string	false	比例设置(值范围1 - 100),如 20 表示 20%的联系人作为测试收件人
└─abTestWinCondition	object	false	确定A/B胜利者的条件
└─timeUnit	integer	true	时间单位: 1为小时 2为天
└─afterTime	integer	true	在多少时间后开始执行: 时间单位是小时时，仅支持填写 大于0，小于23的正整数; 时间单位是天时，仅支持填写 大于0，小于10的正整数
└─compare	integer	true	比较类型： 1打开率 2点击率 3独立打开率 4独立点击率 5送达率
└─abTestItemConfig	object	true	测试项
└─testItemType	integer	true	测试项类别 1.邮件主题 2.邮件内容 3.发件人 4.发送时间
└─itemContentOne	string	true	根据测试项类别不同而不同；1.邮件主题——填写邮件的主题 2.邮件内容——填写邮件模板的templateInvokeName 3.发件人——发件人Id 4.发送时间——发送时间,格式为yyyy-MM-dd HH:mm:ss
└─itemContentTwo	string	true	根据测试项类别不同而不同
└─itemContentThree	string	true	根据测试项类别不同而不同
└─templateSubject	string	true	测试项类别为2时 - 自定义的模板主题

说明

1. taskType=1 A/B任务时，googleTrack和warmUpConfigList若传递则忽略参数值。可以不传或为null。
2. taskType=1 A/B任务时，abTestPercent，abTestWinCondition，timeUnit，afterTime，compare，abTestItemConfig，testItemType 是必填项；不能为null
3. taskType=1 A/B任务时，itemContentOne、itemContentTwo、itemContentThree这三个测试项最少传2个
4. taskType=1 A/B任务时，itemContentOne、itemContentTwo、itemContentThree是同一测试项类别的三个值，不能重复，runTime必须等于这三个值的最早的时间
5. taskType=2 普通任务时，googleTrack 值为null，则忽略更新 googleTrack 字段；如果 googleTrack 值为{}，则删除原有的配置项
6. taskType=2 普通任务时，warmUpConfigList 值为null，则忽略更新 warmUpConfigList 字段; 如 warmUpConfigList 值为[]，则删除原有的配置项
7. runTime必须大于timeZone时区的当前时间
8. 不能改变taskType类型
9. 总计34个参数

Request-Example:

curl -X PATCH -H 'Content-Type: multipart/form-data; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/campaigns/8 -F 'campaignJson={
    "emptyExistedAttachments":0,
    "taskType":1,
    "name":"11.11_leon_api8",
    "to":"632a9c7954094e458d7ff327",
    "sendListType":"1",
    "senderId":"53",
    "replyTo":"",
    "templateInvokeName":"leon2_shanshan",
    "googleTrack":{
        "campaignName":"6181",
        "campaignSource":"jingdong",
        "campaignMedium":"tiktok",
        "campaignTerm":"offset 300",
        "campaignContent":"tv"
    },
    "runTime":"2022-10-26 17:10:20",
    "timeZone":"8",
    "warmUpConfigList":[
        {
            "domain":"gmail.com",
            "rate":1,
            "upgradeValue":0.95,
            "downgradeValue":0.85
        },
        {
            "domain":"outlook.com",
            "rate":1,
            "upgradeValue":0.95,
            "downgradeValue":0.85
        }
    ],
    "abTestPercent":"20",
    "abTestWinCondition":{
        "timeUnit":1,
        "afterTime":5,
        "compare":3
    },
    "abTestItemConfig":{
        "testItemType":4,
        "itemContentOne":"2022-10-26 17:55:20",
        "itemContentTwo":"2022-10-26 17:40:20",
        "itemContentThree":"2022-10-26 17:10:20",
        "templateSubject":""
    }
}' \
  -F attachments=@4d58874449847899f9567bf687769fea.png

Response-Success

HttpStatus: 200

Response:

{}

Response-Error:

{
    "status": 400,
    "error": {
        "parameter": "",
        "message": "The current task has been executed and cannot be modified"
    }
}

任务列表

URL:

https://api2.sendcloud.net/marketing/campaigns

Method: GET

Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request-Headers:

Header	Type	Required	Description
Authorization	string	true	Bearer Token

Query-Parameters:

Parameter	Type	Required	Description
taskType	integer	false	任务类型 1.A/B任务 2.普通任务
taskStatus	integer	false	任务状态(0.待发送，1.发送中，2.已完成，-1.失败)
name	string	false	任务名称
count	integer	false	查询个数， 取值区间 [1-100]， 默认为 10
offset	integer	false	查询起始位置， 取值区间 [0-]，默认为 0

Request-Example:

curl -X GET -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/campaigns?&taskStatus=2

Response-Success

HttpStatus: 200

Response:

{
    "list": [
        {
            "campaignId": 34016,
            "taskType": 2,
            "name": "新建普通任务",
            "to": "63413692180b4f23f8accf7a",
            "userId": 100249,
            "labelId": "598682",
            "fromEmail": "LeonWang@legendnovel.com",
            "fromName": "LeonWang",
            "templateInvokeName": "leon2_shanshan",
            "replyTo": "",
            "taskStatus": 2,
            "googleTrack": null,
            "createTime": "2022-10-08 17:18:34",
            "updateTime": "2022-10-17 17:18:00",
            "runTime": "2022-10-17 17:10:12",
            "completeTime": "2022-10-17 17:18:00",
            "createTimeFmt": null,
            "updateTimeFmt": null,
            "runTimeFmt": null,
            "completeTimeFmt": null,
            "timeZone": "+8",
            "warmUpConfigList": [
                {
                    "domain": "gmail.com",
                    "rate": -1,
                    "upgradeValue": 0.95,
                    "downgradeValue": 0.85
                },
                {
                    "domain": "yahoo.com",
                    "rate": -1,
                    "upgradeValue": 0.95,
                    "downgradeValue": 0.85
                },
                {
                    "domain": "hotmail.com",
                    "rate": 1,
                    "upgradeValue": 0.95,
                    "downgradeValue": 0.85
                }
            ],
            "senderId": 53,
            "abTestPercent": null,
            "abTestWinCondition": null,
            "abTestItemConfig": null
        },
        {
            "campaignId": 34007,
            "taskType": 1,
            "name": "testddd",
            "to": "All Contacts",
            "userId": 100249,
            "labelId": "598655,598656,598657,598658",
            "fromEmail": "xjmfc23@legendnovel.com",
            "fromName": "aaaa",
            "templateInvokeName": "leon2_shanshan",
            "replyTo": "",
            "taskStatus": 2,
            "googleTrack": null,
            "createTime": "2022-09-27 16:36:32",
            "updateTime": "2022-10-12 00:00:00",
            "runTime": "2022-09-27 16:41:23",
            "completeTime": "2022-10-12 00:00:00",
            "createTimeFmt": null,
            "updateTimeFmt": null,
            "runTimeFmt": null,
            "completeTimeFmt": null,
            "timeZone": "+8",
            "warmUpConfigList": null,
            "senderId": 21,
            "abTestPercent": "64",
            "abTestWinCondition": {
                "timeUnit": 1,
                "afterTime": 5,
                "compare": 1
            },
            "abTestItemConfig": {
                "testItemType": 3,
                "templateSubject": null,
                "itemContentOne": "21",
                "itemContentTwo": "53",
                "itemContentThree": "29"
            }
        }
    ],
    "total": 2
}

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}

任务详情

URL:

https://api2.sendcloud.net/marketing/campaigns/{campaignId}

Method: GET

Content-Type: application/x-www-form-urlencoded;charset=utf-8

Request-Headers:

Header	Type	Required	Description
Authorization	string	true	Bearer Token

Path-parameters:

Parameter	Type	Required	Description
campaignId	string	true	任务 ID

Request-Example:

curl -X GET -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/campaigns/33761

Response-Parameters:

Parameter	Type	Description
name	string	任务名称
to	string	收件人 tag、segment 或list
campaignId	integer	任务 ID
taskType	integer	任务类型 1 A/B任务 2普通任务
userId	integer	用户 ID
labelId	string	标签 ID，系统添加的
fromEmail	string	sender地址
fromName	string	发件人名称
templateInvokeName	string	模板调用名称
replyTo	string	回复地址
taskStatus	integer	任务状态 (0.待发送，1.发送中，2.已完成，-1.失败)
googleTrack	object	Google追踪
└─campaignName	string	活动名称
└─campaignSource	string	来源
└─campaignMedium	string	媒体
└─campaignTerm	string	关键词
└─campaignContent	string	内容
createTime	string	创建时间（UTC+8）
updateTime	string	更新时间（UTC+8）
runTime	string	运行时间（UTC+8）
timeZone	integer	时区(参考时区字典)
completeTime	string	完成时间（UTC+8）
createTimeFmt	string	创建时间（账户设置的时区）
updateTimeFmt	string	更新时间（账户设置的时区）
runTimeFmt	string	运行时间（账户设置的时区）
completeTimeFmt	string	完成时间（账户设置的时区）
warmUpConfigList	object[]	预热配置
└─domain	string	域名
└─rate	integer	速率
└─upgradeValue	double	速率上调阈值 取值区间(0,1)不包含0和1
└─downgradeValue	double	速率下调阈值 取值区间(0,1)不包含0和1
senderId	integer	发件人 ID
abTestPercent	string	比例设置(值范围1 - 100),如 20 表示 20%的联系人作为测试收件人
abTestWinCondition	object	确定A/B胜利者的条件
└─timeUnit	integer	时间单位: 1为小时 2为天
└─afterTime	integer	在多少时间后开始执行: 时间单位是小时时，仅支持填写 大于0，小于23的正整数; 时间单位是天时，仅支持填写 大于0，小于10的正整数
└─compare	integer	比较类型： 1打开率 2点击率 3独立打开率 4独立点击率 5送达率
abTestItemConfig	object	测试项
└─testItemType	integer	测试项类别 1邮件主题 2邮件内容 3发件人 4发送时间
└─itemContentOne	string	根据测试项类别不同而不同；1.邮件主题——为邮件的主题 2.邮件内容——为邮件模板的templateInvokeName 3.发件人——发件人Id 4.发送时间——发送时间,格式为yyyy-MM-dd HH:mm:ss
└─itemContentTwo	string	根据测试项类别不同而不同
└─itemContentThree	string	根据测试项类别不同而不同
└─templateSubject	string	测试项类别为2时 - 自定义的模板主题

Response-Success

HttpStatus: 200

Response:

{
    "campaignId": 34034,
    "taskType": 1,
    "name": "11.11_leon_api8",
    "to": "632a9c7954094e458d7ff327",
    "userId": 100249,
    "labelId": "598723,598724,598725",
    "fromEmail": "LeonWang@legendnovel.com",
    "fromName": "LeonWang",
    "templateInvokeName": "leon2_shanshan",
    "replyTo": null,
    "taskStatus": 2,
    "googleTrack": null,
    "createTime": "2022-10-26 17:09:23",
    "updateTime": "2022-10-26 22:55:20",
    "runTime": "2022-10-26 17:10:20",
    "completeTime": "2022-10-26 22:55:20",
    "createTimeFmt": null,
    "updateTimeFmt": null,
    "runTimeFmt": null,
    "completeTimeFmt": null,
    "timeZone": "+8",
    "warmUpConfigList": null,
    "senderId": 53,
    "abTestPercent": "20",
    "abTestWinCondition": {
        "timeUnit": 1,
        "afterTime": 5,
        "compare": 3
    },
    "abTestItemConfig": {
        "testItemType": 4,
        "templateSubject": null,
        "itemContentOne": "2022-10-26 17:55:20",
        "itemContentTwo": "2022-10-26 17:40:20",
        "itemContentThree": "2022-10-26 17:10:20"
    }
}

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}

预热调速(停止、free)

URL:

https://api2.sendcloud.net/marketing/campaigns/{campaignId}/warmup/actions/rate_change

Method: POST

Content-Type: application/json; charset=utf-8

Request-Headers:

Header	Type	Required	Description
Authorization	string	true	Bearer Token

Path-parameters:

Parameter	Type	Required	Description
campaignId	integer	true	任务 ID

Body-Parameters:

Parameter	Type	Required	Description
domain	string	true	域名
rate	integer	true	速率(-1不限速，-2停止剩余邮件发送)

Request-Example:

curl -X POST -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/campaigns/452/warmup/actions/rate_change --data '{
  "domain": "gmail.com",
  "rate": -1
}'

Response-Success

HttpStatus: 200

Response:

{}

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}