Address List

Address list is typically used when sending marketing emails.

You can query, add, modify and delete address list, as well as list member.

Creation time sorting of returned results of all interfaces.

Query address list (batch query)

URL 

https://api.sendcloud.net/apiv2/addresslist/list

HTTP Request Method 

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address list no lists of alias address, separated by semicolons
start int no start position, [0-], defaults to 0
limit int no amount, [0-100],defaults to 100

Request Example 

https://api.sendcloud.net/apiv2/addresslist/list?apiUser=***&apiKey=***&limit=2

Returned Value Description

Parameter Description
name name of address list
address list of alias addresses, you can call operations by the alias address; it’s formatted as xxx@maillist.sendcloud.org
memberCount count of addresses in the list
description address list description
gmtCreated time of address list creation
gmtUpdated time of address list modification
memberUpdated time of address list member modification

Returned Value Example 

{
    statusCode: 200,
    info: {
        total: 1,
        count: 1,
        dataList: [{
            gmtCreated: "2015-09-15 20:29:01",
            gmtUpdated: "2015-09-15 20:29:01",
            memberUpdated: "2015-09-21 11:36:42",
            address: "developers4@sendcloud.com",
            description: "desc",
            memberCount: 0,
            name: "211"
        }]
    },
    message: "请求成功",
    result: true
}

Add address list

URL

https://api.sendcloud.net/apiv2/addresslist/add

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias addresses, you can call operations by the alias address; it’s formatted as xxx@maillist.sendcloud.org
name string yes list name
desc string no list description

Request Example 

https://api.sendcloud.net/apiv2/addresslist/add?apiUser=***&apiKey=***&address=justfortest@maillist.sendcloud.org&name=testlist&desc=test

Returned Value Description

Parameter Description
address alias addresses, you can call operations by the alias address
memberCount count of addresses in the list
name list name
description address list description
gmtCreated time of address list creation
gmtUpdated time of address list modification

Returned Value Example 

{
    statusCode: 200,
    info: {
        data: {
            gmtCreated: "2015-09-28 17:59:15",
            gmtUpdated: "2015-09-28 17:59:15",
            address: "developers41@sendcloud.com",
            memberCount: 0,
            description: "41",
            listType: 0,
            name: "developer41"
        }
    },
    message: "请求成功",
    result: true
}

Delete address list

URL

https://api.sendcloud.net/apiv2/addresslist/delete

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias addresses, you can call operations by the alias address; it’s formatted as xxx@maillist.sendcloud.org

Request Example 

https://api.sendcloud.net/apiv2/addresslist/delete?apiUser=***&apiKey=***&address=newtest@maillist.sendcloud.org

Returned Value Description

Parameter Description
count count of deleted lists

Returned Value Example

{
    statusCode: 200,
    info: {
        count: 1
    },
    message: "请求成功",
    result: true
}

Modify address list

URL

https://api.sendcloud.net/apiv2/addresslist/update

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias addresses, you can call operations by the alias address; it’s formatted as xxx@maillist.sendcloud.org
newAddress string no new alias address
name string no name of modified list
desc string no description of modified list

Description

【newAddress】,【name】 or 【description】can be modified individually or in combination

Request Example 

https://api.sendcloud.net/apiv2/addresslist/update?apiUser=***&apiKey=***&address=justfortest@maillist.sendcloud.org&name=newtest

Returned Value Description

Parameter Description
count count of modified lists

Returned Value Example

{
    statusCode: 200,
    info: {
        count: 1
    },
    message: "请求成功",
    result: true
}

Query list member (batch query)

URL

https://api.sendcloud.net/apiv2/addressmember/list

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias address in address list
start int no start position, [0-], defaults to 0
limit int no amount, [0-100],defaults to 100

Request Example

https://api.sendcloud.net/apiv2/addressmember/list?apiUser=***&apiKey=***&address=newtest@maillist.sendcloud.org

Return Value Description

Parameter Description
gmtCreated time of member creation
gmtUpdated time of member modification
address address list of member
member email address of member
name member name
vars variables

Returned Value Example

{
  "statusCode": 200,
  "info": {
    "dataList": [
      {
        "gmtCreated": "2015-04-30 11:15:43",
        "gmtUpdated": "2015-04-30 11:15:43",
        "address": "test@maillist.sendcloud.org",
        "member": "001@160it.com",
        "name": "001",
        "vars": ""
      },
      {
        "gmtCreated": "2015-04-30 11:17:01",
        "gmtUpdated": "2015-04-30 11:17:01",
        "address": "test@maillist.sendcloud.org",
        "member": "01@mail.yedao.cc",
        "name": "002",
        "vars": ""
      },
      {
        "gmtCreated": "2015-04-30 11:16:41",
        "gmtUpdated": "2015-04-30 11:16:41",
        "address": "test@maillist.sendcloud.org",
        "member": "057966@gmail.com",
        "vars": ""
      }
    ],
    "total": 11378,
    "count": 3
  },
  "message": "请求成功",
  "result": true
}

Query list member

URL

https://api.sendcloud.net/apiv2/addressmember/get

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias address in address list
members list yes addresses of list members

Request Example

http://api.sendcloud.net/apiv2/addressmember/get?apiUser=***&apiKey=***&address=newtest@maillist.sendcloud.org&members=ben@ifaxin.com

Returned Value Description

Parameter Description
gmtCreated time of member creation
gmtUpdated time of member modification
address address list of member
member email address of member
name member name
vars variables

Returned Value Example

{
  "statusCode": 200,
  "message": "请求成功",
  "result": true,
  "info": {
    "dataList": [
      {
        "gmtCreated": "2015-04-30 11:15:43",
        "gmtUpdated": "2015-04-30 11:15:43",
        "address": "***",
        "member": "001@160it.com",
        "name": "001",
        "vars": ""
      }
    ],
    "count": 1
  }
}

Add list member

URL

https://api.sendcloud.net/apiv2/addressmember/add

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias address in address list
members list yes lists of members addition. multiple addresses separated by semicolons
names list no member names are separated by semicolons
vars list no substitution variables are corresponding to members, and formatted as {“money”:”1000”}; separated by semicolons

Note

  1. You can add up to 1000 members on each request
  2. If “vars” or "names" is included, the amount of “vars” and "names" should be same as the count of members'
  3. When adding “vars”, do not attach “%” to “key”
  4. In the “vars“ , variables with a key of "name" will be ignored, meaning that the key cannot be "name"
  5. The maximum length of a single member variable in "vars" is 1024 characters
  6. Global variable “recipient” can be used when sending address list, and the value is recipient’s email address
  7. If the same member address already exists in the address list, the names of that address in this interface call will be used The corresponding value within vars is overwritten and updated. For example, the original variable {"money": "99"}, the requested variable {"location": "Shanghai"}, and the final variable is {"location": "Shanghai"}

Request Example

https://api.sendcloud.net/apiv2/addressmember/add?apiUser=***&apiKey=***&address=yourlist@maillist.sendcloud.org&members=1@1.com;2@2.com&vars={"money":"99"};{"money":"900"}

Returned Value Description

Parameter Description
count count of successfully added/updated addresses
invalidCount add the count of failed addresses and the number of duplicate addresses in this call
invalidAddressList add failed address list , duplicate address list in this call
reasonList reason array

Returned Value Example 

{
    "result": true,
    "statusCode": 200,
    "message": "请求成功",
    "info": {
        "count": 1,
        "invalidCount":3,
        "invalidAddressList": [
            "2.@qq.com",
            "3@qq.com",
            "4@qq.com"
        ],
        "reasonList": [
            "address invalid",
            "address duplicate",
            "vars invalid"
        ]
    }
}

Modify list member

URL

https://api.sendcloud.net/apiv2/addressmember/update

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias address in address list
members list yes former addresses of the updated members, separated by semicolons
newMembers list no updated addresses of the updated members, separated by semicolons; corresponding to the members
names list no names of list members, separated by semicolons
vars list no substitution variables, corresponding to members, are formatted as {“money”:”1000”}; separated by semicolons

Note

  1. You can modify up to 1000 members on each request
  2. If there is no member with the corresponding address, the update will fail
  3. If “vars” or "names" is included, the amount of “vars” and "names" should be same as the count of members'
  4. In the “vars“ , variables with a key of "name" will be ignored, meaning that the key cannot be "name"
  5. If there is a member with a corresponding address, the value corresponding to the same key in the existing vars will be overwritten, and the newly added variables will be added to the existing vars. For example: the original variable {"money": "99", "date": "2024-05-01"}, this request variable {"money": "100", "location": "Shanghai"}, the final variable is {"money": "100", "date": "2024-05-01", "location": "Shanghai"}

Request Example

https://api.sendcloud.net/apiv2/addressmember/update?apiUser=***&apiKey=***&address=yourlist@maillist.sendcloud.org&members=1@1.com;2@2.com&vars={"money":"199"};{"money":"1900"}

Returned Value Description

Parameter Description
count count of modified addresses

Returned Value Example

{
    "result": true,
    "statusCode": 200,
    "message": "请求成功",
    "info": {
        "count": 1,
        "invalidCount":4,
        "invalidAddressList": [
            "2.@qq.com",
            "3@qq.com",
            "4@qq.com",
        "5@qq.com"
        ],
        "reasonList": [
            "address invalid",
            "address duplicate",
            "vars invalid",
        "address not found"
        ]
    }
}

Delete list member

URL

https://api.sendcloud.net/apiv2/addressmember/delete

HTTP Request Method

post    get

Parameter Description

parameter type required or not description
apiUser string yes API_USER
apiKey string yes API_KEY
address string yes alias address in address list
members list yes addresses of the members to be deleted, separated by semicolons

Request Example

https://api.sendcloud.net/apiv2/addressmember/delete?apiUser=***&apiKey=***&address=newtest@maillist.sendcloud.org&members=3@3.com;4@4.com

Returned Value Description

Parameter Description
count count of deleted addresses

Returned Value Example

{
    statusCode: 200,
    info: {
        count: 2
    },
    message: "请求成功",
    result: true
}