SendCloud

# 联系人管理

# 批量添加或更新联系人

URL:

https://api2.sendcloud.net/marketing/lists/members
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
members object[] true 联系人列表，上限个数1000
└─email string true 邮箱地址
└─phone string false 电话号码
└─name string false 昵称
└─fields object false 联系人属性
└─tags string[] false 标签名称列表
tagFlag integer false 标签更新方式，0.覆盖、1.追加、2.跳过，默认值为1
updateExisting boolean true 是否更新属性(如果地址列表存在该地址)

说明

  1. 如果某联系人 Email 字段和参数 members.email 的值相同，则为更新此联系人，反之为添加联系人。
  2. 关于 tagFlag 不同值，所对应的不同的标签更新方式，见下面示例：
tagFlag 原tags 参数tags 新tags
0 [1,2,3] [] []
0 [1,2,3] null,未传 [1,2,3]
0 [1,2,3] [3,4,5] [3,4,5]
1 [1,2,3] [] [1,2,3]
1 [1,2,3] null,未传 [1,2,3]
1 [1,2,3] [3,4,5] [1,2,3,4,5]
2 [1,2,3] [] [1,2,3]
2 [1,2,3] null,未传 [1,2,3]
2 [1,2,3] [3,4,5] [1,2,3]
2 [] [3,4,5] []

Request-Example:

curl -X POST -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/members --data '{"members":[{"email":"xjmfc@126.com","phone":"13681312919","name":"朱锁锁","fields":{"Birthday":"03/30","Age":"12","customField":"我的测试"},"tags":["testTag"]}],"tagFlag":0,"updateExisting":true}'
1

Response-Success:

HttpStatus: 200

Response:

添加联系人返回内容

{
	"totalInserted": 2,
	"insertedMembers": [{
			"email": "202205ab233444444444446@qq.com",
			"id": "6294b0fa490f33c5ee3b5b0c"
		},
		{
			"email": "202205ab3331@qq.com",
			"id": "6294b0fa490f33c5ee3b5b0d"
		}
	],
	"totalUpdated": 0,
	"updatedMembers": [],
	"errorCount": 0,
	"errors": []
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Response-Error:

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

# 删除单个联系人

URL:

https://api2.sendcloud.net/marketing/lists/members/{memberId}
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
memberId string true 成员 ID

Request-Example:

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

Response-Success:

HttpStatus: 204

Response:

{}
1

Response-Error:

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

# 批量删除联系人

URL:

https://api2.sendcloud.net/marketing/lists/members/delete-batch
1

Method: DELETE

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

Request-Headers:

Header Type Required Description
Authorization string true token

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 操作符 （== , != , > , >= , < , <= , exist , contain , does not contain）
     └─value string true 当fieldName为 tag 时，value = tagName
当fieldName 为属性名，格式请参考筛选条件

说明

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

Request-Example:

curl -X DELETE -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/members/delete-batch --data '
{
    "condition": {
        "relation": "or",
        "items": [
            {
                "fieldName": "Email",
                "op": "contain",
                "value": "hotmail.com"
            },
            {
                "fieldName": "Phone",
                "op": "contain",
                "value": "188"
            }
        ]
    }
}
'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Response-Success:

HttpStatus: 200

Response:

{
    "successCount": 22
}
1
2
3

Response-Error:

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

# 更新单个联系人

URL:

https://api2.sendcloud.net/marketing/lists/members/{memberId}
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
memberId string true 成员 ID

Body-Parameters:

Parameter Type Required Description
phone string false 手机号
name string false 昵称
fields object false 联系人属性
tags string[] false 标签名称列表

Request-Example:

curl -X PATCH -H 'Content-Type: application/json; charset=utf-8' -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/members/62974a5e490f33c5eee647a2 --data '{"email":"xjmfc@126.com","phone":"13681312919","name":"朱锁锁","fields":{"Email":"xjmfc@126.com","Birthday":"03/30","Age":"12","customField":"我的测试"},"tags":["testTag"]}'
1

Response-Parameters:

Parameter Type Description
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 取消订阅时间（账户设置的时区）

Response-Success:

HttpStatus: 200

Response:

{
    "id": "62974a5e490f33c5eee647a2",
    "listId": null,
    "userId": 99229,
    "email": "lim8367@hotmail.com",
    "phone": null,
    "name": null,
    "createTime": "2022-06-01 19:15:42",
    "updateTime": "2022-06-01 19:15:42",
    "unsubscribeTime": null,
    "fields": {},
    "tags": [
        "628dd6eb8107fd77030b3dc1"
    ],
    "tagNames": [
        "wer4"
    ],
    "createTimeFmt": null,
    "updateTimeFmt": null,
    "unsubscribeTimeFmt": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Response-Error:

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

# 联系人详情

URL:

https://api2.sendcloud.net/marketing/lists/members/{memberId}
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
memberId string true 成员 ID

Request-Example:

curl -X GET -H 'Authorization:Bearer YXBpX3VzZXI6YXBpX2tleQ==' -i https://api2.sendcloud.net/marketing/lists/members/62974a5e490f33c5eee647a2
1

Response-Parameters:

Parameter Type Description
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 取消订阅时间（账户设置的时区）

Response-Success:

HttpStatus: 200

Response:

{
    "id": "5ff676de490f33c5ee941a80",
    "listId": 63486,
    "userId": 99229,
    "email": "17@sendcloud.im",
    "phone": "133456634",
    "name": "wem zh",
    "unsubscribeTime": null,
    "fields": {
        "huangli": "12.00",
        "Age": "13"
    },
    "tags": [
        "5ff676d5c3445509bee370a1"
    ],
    "tagNames": [
        "3"
    ],
    "createTimeFmt": "2021-01-07 10:50:05",
    "updateTimeFmt": "2022-05-25 10:19:01",
    "unsubscribeTimeFmt": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Response-Error:

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

# 联系人列表

URL:

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

Method: POST

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

Request-Headers:

Header Type Required Description
Authorization string true Bearer Token

Query-Parameters:

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

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 操作符 （== , != , > , >= , < , <= , exist , 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/listMembers?offset=0&count=10 --data '{
    "condition": {
        "relation": "and",
        "items": [
            { 
              "fieldName": "Email",
              "op": "contain",
              "value": "qq.com"
            }
        ]
    }
}'
1
2
3
4
5
6
7
8
9
10
11
12

Response-Parameters:

Parameter Type Description
list array 列表数组
└─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": "629594c9490f33c5ee6fe9e1",
            "listId": 63486,
            "userId": 99229,
            "email": "111@yahoo.com.sg",
            "phone": "18111111111",
            "name": "",
            "createTime": "2022-05-31 12:08:41",
            "updateTime": "2022-05-31 12:08:41",
            "unsubscribeTime": null,
            "fields": {
                "Gender": "男",
                "Age": "1"
            },
            "tags": null,
            "tagNames": [],
            "createTimeFmt": null,
            "updateTimeFmt": null,
            "unsubscribeTimeFmt": null
        },
        {
            "id": "629594c9490f33c5ee6fe9e0",
            "listId": 63486,
            "userId": 99229,
            "email": "maggieee.wang@gmail.com",
            "phone": "18111111111",
            "name": "",
            "createDate": "2022-05-31 12:08:41",
            "updateDate": "2022-05-31 12:08:41",
            "unsubscribeTime": null,
            "fields": {
                "Gender": "",
                "Age": "1"
            },
            "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
44
45

Response-Error:

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

发件人管理

批量添加或更新联系人
删除单个联系人
批量删除联系人
更新单个联系人
联系人详情
联系人列表