SendCloud

# 分组管理

# 创建分组

URL:

https://api2.sendcloud.net/marketing/lists/segments
1

Method: POST

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

Request-Headers:

Header Type Required Description
Authorization string true Bearer Token

Body-Parameters:

Parameter Type Required Description
segmentName string true 分组名称 （最长48个字符，不支持字符 ^,?,+,.,*,\,[,],(,) ）
type integer true 分组类型 ( 0或1）
0.by field （按照属性分组）; 1. by campaign（按照发送效果分组）
condition object true 分组条件
└─relation string true 条件关系 (and 或 or)
└─items object[] true 条件 (最多支持10个筛选条件，筛选条件之间关系(relation)，要么全为且关系，要么全为或关系)
     └─campaignId integer false 营销任务 ID
如果 fieldName=campaign，此值必填，且该 ID 对应的任务状态必须是正在发送中或已发送完成
     └─fieldName string true

1.若 type=0
fieldName 为属性名，value 为属性值；
fieldName 为 "tag" 时，value=tagName


2.若 type=1
fieldName 必为 campaign，value 为 "sent","open","click","unopen","unclick","notsent" 之一，此时 campaignId 必填，为该 campaign 的 ID

     └─op string true 操作符 （== , != , > , >= , < , <= , contain , does not contain）
当 fieldName=campaign 时，此时 op 必须为 ==； 当 fieldName 为属性名或 tag 时，op 请参看筛选条件
     └─value string true 当 fieldName 为 "tag" ，此时 value=tagName ；
当 fieldName 为属性名，格式请参考筛选条件；
当 fieldName = "campaign"，value=sent, open, click, unopen, unclick, notsent 中之一

说明

  1. fieldName 和op 对应的关系请参考筛选条件

Request-Example:

curl -X POST -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments --data '{
  "segmentName": "湖北用户",
  "type": 0,
  "condition": {
    "relation": "and",
    "items": [
      {
        "fieldName": "Name",
        "op": "contain",
        "value": "李磊"
      }
    ]
  }
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Response-Success:

HttpStatus: 201

Response:

{
  "segmentId":"asfd4561361q5574"
}
1
2
3

Response-Error:

{
    "status": 400,
    "error": {
        "parameter": "fieldName",
        "message": "[asge] is not defined, please define it first"
    }
}
1
2
3
4
5
6
7

# 删除分组

URL:

https://api2.sendcloud.net/marketing/lists/segments/{segmentId}
1

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
segmentId string true 分组 ID

Request-Example:

curl -X DELETE -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments/asfd4561361q5574
1

Response-Success:

HttpStatus: 204

Response:

{}
1

Response-Error:

{
    "status": 404,
    "error": {
        "parameter": "",
        "message": "resource not found"
    }
}
1
2
3
4
5
6
7

# 更新分组

URL:

https://api2.sendcloud.net/marketing/lists/segments/{segmentId}
1

Method: PATCH

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

Request-Headers:

Header Type Required Description
Authorization string true Bearer Token

Path-Parameters:

Parameter Type Required Description
segmentId string true 分组 ID

Body-Parameters:

Parameter Type Required Description
segmentName string false 分组名称 （最长48个字符）
type integer true 分组类型 ( 0或1）
0.by field （按照属性分组）； 1. by campaign（按照发送效果分组）
condition object true 分组条件
└─relation string true 条件关系 (and 或 or)
└─items object[] true 条件 (最多支持10个筛选条件，筛选条件之间关系(relation)，要么全为且关系，要么全为或关系 )
     └─campaignId integer false 营销任务 ID
如果 fieldName=campaign，此值必填，且该 ID 对应的任务状态必须是正在发送中或已发送完成
     └─fieldName string true

1.若 type=0
fieldName 为属性名，value 为属性值；
fieldName 为 "tag" 时，value=tagName


2.若 type=1
fieldName 必为 campaign，value 为 "sent","open","click","unopen","unclick","notsent" 之一，此时 campaignId 必填，为该 campaign 的 ID

     └─op string true 操作符 （== , != , > , >= , < , <= , contain , does not contain）
当 fieldName=campaign 时，此时 op 必须为 ==； 当 fieldName 为属性名或 tag 时，op 请参看筛选条件
     └─value string true 当 fieldName 为 "tag" ，此时 value=tagName ；
当 fieldName 为属性名，格式请参考筛选条件；
当 fieldName = "campaign"，value = sent, open, click, unopen, unclick, notsent 中之一

说明

  1. fieldName 和op 对应的关系请参考筛选条件

Request-Example:

curl -X PATCH -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments/ 62849dc690d79d4947dd033d --data '{
  "segmentName": "湖北用户",
  "type": 0,
  "condition": {
    "relation": "and",
    "items": [
      {       
        "fieldName": "Name",
        "op": "contain",
        "value": "leonwang"
      }
    ]
  }
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14

Response-Parameters:

parameters Type Description
segmentId string 分组 ID
userId integer 用户 ID
segmentName string 分组名
listId integer 列表关联 ID
status string 分组状态 (-1.失败 1.更新中 2.更新完成)
createTime string 创建时间
updateTime string 更新时间
memberTotal integer 分组联系人总数
type integer 分组类型 ( 0或1） 0.by field （按照属性分组）； 1. by campaign（按照发送效果分组）
relation string 条件关系and,or
conditions object[] 分组条件
└─campaignId integer 任务 ID
└─fieldName string 属性名
└─op string 操作符
└─value string 属性值
process object 分组处理进度
└─statusDesc string 处理状态描述
└─complete Boolean true 已完成， false 未完成
└─percent integer 处理百分比

Response-Success:

HttpStatus: 200

Response:

{
    "segmentId": "60854a804b72410e5a456d69",
    "userId": 100249,
    "segmentName": "年龄介于13与45之间",
    "listId": 63877,
    "status": "2",
    "createTime": "2021-04-25 18:54:56",
    "updateTime": "2022-05-06 15:36:02",
    "memberTotal": 143,
    "relation": "and",
    "type": 0,
    "conditions": [
        {
            "campaignId": null,
            "fieldName": "age",
            "op": ">=",
            "value": "13"
        },
        {
            "campaignId": null,
            "fieldName": "age",
            "op": "<=",
            "value": "45"
        }
    ],
    "process": {
                "statusDesc": "segmentation completed",
                "complete": true,
                "percent": 100
            }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Response-Error:

{
    "status": 400,
    "error": {
        "parameter": "fieldName",
        "message": "[asge] is not defined, please define it first"
    }
}
1
2
3
4
5
6
7

# 分组详情

URL:

https://api2.sendcloud.net/marketing/lists/segments/{segmentId}
1

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
segmentId string true 分组 ID

Request-Example:

curl -X GET -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments/ 62849dc690d79d4947dd033d
1

Response-Parameters:

parameters Type Description
segmentId string 分组 ID
userId integer 用户 ID
segmentName string 分组名
listId integer 列表关联 ID
status string 分组状态 (-1.失败 1.更新中 2.更新完成)
createTime string 创建时间
updateTime string 更新时间
memberTotal integer 分组联系人总数
type integer 分组类型 ( 0或1） 0. by field （按照属性分组）； 1. by campaign（按照发送效果分组）
relation string 条件关系and,or
conditions object[] 分组条件
└─campaignId integer 任务 ID
└─fieldName string 属性名
└─op string 操作符
└─value string 属性值
process object 分组处理进度
└─statusDesc string 处理状态描述
└─complete Boolean true 已完成， false 未完成
└─percent integer 处理百分比

Response-Success:

HttpStatus: 200

Response:

{
    "segmentId": "6274ea51b05b2648606523ad",
    "userId": 100249,
    "segmentName": "test_by_field_tag_update",    
    "type": 0,
    "listId": 63877,
    "status": "2",
    "createTime": "2022-05-06 17:28:49",
    "updateTime": "2022-06-02 15:17:05",
    "memberTotal": 691,
    "relation": "and",
    "conditions": [
        {
            "campaignId": null,
            "fieldName": "Age",
            "op": "<",
            "value": "50"
        }
    ],
    "process": {
        "statusDesc": "segmentation completed",
        "complete": true,
        "percent": 100
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}
1
2
3
4
5
6
7

# 分组列表

URL:

https://api2.sendcloud.net/marketing/lists/segments
1

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
segmentName string false 分组名
type integer false 分组类型 ( 0或1） 0.by field （按照属性分组）； 1. by campaign（按照发送效果分组）
offset integer false 查询起始位置， 取值区间 [0-]， 默认为 0
count integer false 查询个数， 取值区间 [1-100]， 默认为 10

Request-Example:

curl -X GET -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments?offset=0&count=10&segmentName=abc_by_name&type=0
1

Response-Parameters:

Parameters Type Description
list array 联系人列表
└─segmentId string 分组 ID
└─userId integer 用户 ID
└─segmentName string 分组名
└─listId integer 列表关联 ID
└─status string 分组状态 (-1:失败 1:更新中 2:更新完成)
└─createTime string 创建时间
└─updateTime string 更新时间
└─memberTotal integer 分组联系人总数
└─type integer 分组类型 ( 0或1） 0.by field （按照属性分组）； 1. by campaign（按照发送效果分组）
└─relation string 条件关系and,or
└─conditions object[] 分组条件
     └─campaignId integer 任务 ID
     └─fieldName string 属性名
     └─op string 操作符
     └─value string 属性值
└─process object 分组处理进度
     └─statusDesc string 处理状态描述
     └─complete Boolean true 已完成， false 未完成
     └─percent integer 处理百分比
total integer 记录总数

Response-Success:

HttpStatus: 200

Response:

{
    "list": [
        {
            "segmentId": "62a162293724120da6f61af8",
            "userId": 99229,
            "segmentName": "abc_by_name",
            "relation": "and",
            "type": 0,
            "listId": 63486,
            "status": "2",
            "createTime": "2022-06-09 10:59:53",
            "updateTime": "2022-06-09 10:59:53",
            "memberTotal": 0,
            "conditions": [
                {
                    "campaignId": null,
                    "fieldName": "0517",
                    "op": "contain",
                    "value": "campaign-2022"
                }
            ],
            "process": {
                "statusDesc": "segmentation completed",
                "complete": true,
                "percent": 100
            }
        }
    ],
    "total": 1
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}
1
2
3
4
5
6
7

# 查询分组的处理进度

URL:

https://api2.sendcloud.net/marketing/lists/segments/{segmentId}/process
1

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
segmentId string true 分组 ID

Request-Example:

curl -X GET -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments/ 62849dc690d79d4947dd033d/process
1

Response-Success:

HttpStatus: 200

Response:

{
   "percent": 100,
    "complete": true,
    "statusDesc": "segmentation completed"
}
1
2
3
4
5

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}
1
2
3
4
5
6
7

# 某个分组的成员列表

URL:

https://api2.sendcloud.net/marketing/lists/segments/{segmentId}/members
1

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
segmentId string true 分组 ID

Query-Parameters:

Parameter Type Required Description
offset integer false 查询起始位置， 取值区间 [0-]， 默认为 0
count integer false 查询个数， 取值区间 [1-100]， 默认为 10

Body-Parameters:

Parameter Type Required Description
condition object false 分组条件
└─relation string true 条件关系 (and 或 or)
└─items object[] true 条件 (最多支持10个筛选条件，筛选条件之间关系(relation)，要么全为且关系，要么全为或关系）
     └─fieldName string true fieldName 为属性名，value 为属性值；
fieldName 为"tag" 时，value=tagName
     └─op string true 操作符 （== , != , > , >= , < , <= , contain , does not contain）
     └─value string true 当 fieldName = "tag" 时，value = tagName ；
当 fieldName 为属性名时，格式请参考筛选条件

说明

  1. fieldName 和op 对应的关系请参考筛选条件

Request-Example:

curl -X POST -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments/ 62908150eb5e955d6d214da6/members?offset=0&count=10 --data '{
    "condition": {
        "relation": "and",
        "items": [
            { 
              "fieldName": "Email",
              "op": "contain",
              "value": "tw"
            }
        ]
    }
}'
1
2
3
4
5
6
7
8
9
10
11
12

Response-Parameters:

parameters Type Description
list object[] 列表数组
└─id string 联系人 ID
└─listId integer 列表 ID
└─userId integer 用户 ID
└─email string 邮箱地址
└─phone string 手机号码
└─name string 名字
└─createTime string 创建时间（UTC+8）
└─updateTime string 更新订阅时间（UTC+8）
└─unsubscribeTime string 取消订阅时间（UTC+8）
└─fields object 联系人属性
└─tags string[] 标签 ID 集合
└─tagNames string[] 标签名集合
└─createTimeFmt string 创建时间（账户设置的时区）
└─updateTimeFmt string 更新时间（账户设置的时区）
└─unsubscribeTimeFmt string 取消订阅时间（账户设置的时区）
total integer 记录总数

Response-Success:

HttpStatus: 200

Response:

{
    "list": [
        {
            "id": "629d6650490f33c5eef1caa6",
            "listId": 63486,
            "userId": 99229,
            "email": "paulchen0518@yahoo.com.tw",
            "phone": null,
            "name": "shanshan",
            "createTime": "2022-06-06 10:28:32",
            "updateTime": "2022-06-06 10:28:32",
            "unsubscribeTime": null,
            "fields": {
                "Gender": "女"
            },
            "tags": null,
            "tagNames": [],
            "createTimeFmt": null,
            "updateTimeFmt": null,
            "unsubscribeTimeFmt": null
        },
        {
            "id": "629d665a490f33c5eef2932f",
            "listId": 63486,
            "userId": 99229,
            "email": "q510518@yahoo.com.tw",
            "phone": null,
            "name": "",
            "createTime": "2022-06-06 10:28:42",
            "updateTime": "2022-06-06 10:28:42",
            "unsubscribeTime": null,
            "fields": {
                "Gender": ""
            },
            "tags": null,
            "tagNames": [],
            "createTimeFmt": null,
            "updateTimeFmt": null,
            "unsubscribeTimeFmt": null
        }
    ],
    "total": 2
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}
1
2
3
4
5
6
7

# 删除分组联系人

URL:

https://api2.sendcloud.net/marketing/lists/segments/{segmentId}/members
1

Method: DELETE

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

Request-Headers:

Header Type Required Description
Authorization string true Bearer Token

Path-Parameters:

Parameter Type Required Description
segmentId string true 分组 ID

Body-Parameters:

Parameter Type Required Description
memberIds string[] true 联系人 ID 列表

Request-Example:

curl -X DELETE -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/segments/ 62849dc690d79d4947dd033d/members --data '{
  "memberIds": [
    "asdfsdf2211212aa",
    "2sadfs288332223s"
  ]
}'
1
2
3
4
5
6

Response-Success:

HttpStatus: 200

Response:

{
 "successCount": 100
}
1
2
3

Response-Error:

{
    "status":401,
    "error":{
        "parameter":"",
        "message":"Unauthorized"
    }
}
1
2
3
4
5
6
7
Last Updated: 2025/03/25 10:38:59

创建分组
删除分组
更新分组
分组详情
分组列表
查询分组的处理进度
某个分组的成员列表
删除分组联系人