Address List

Last updated:2023-03-14

Address list is typically used when sending marketing emails.

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

Query address list (Batch)

URL

https://email.api.engagelab.cc/v1/address_lists
          https://email.api.engagelab.cc/v1/address_lists

        
This code block in the floating window

HTTP Request Method

GET
          GET

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Query Parameter Description

Parameter Type Required or not Description
offset int no offset position, [0-], defaults to 0
limit int no amount, [0-100],defaults to 100
name string no name of address list
address string no address of address list

Request Example

curl 'https://email.api.engagelab.cc/v1/address_lists' --header 'Authorization: Basic YXBpVXNlcjphcGlLZXk='
          curl  'https://email.api.engagelab.cc/v1/address_lists' --header 'Authorization: Basic YXBpVXNlcjphcGlLZXk='

        
This code block in the floating window

Returned Value Description

Parameter Description
address_list_id id of  list
name name of address list
address list of alias addresses, you can call operations by the alias address; it’s formatted as xxx@maillist.email.engagelab.com
member_count count of addresses in the list
desc address list Description
create_time time of address list creation
update_time time of address list modification

Returned Example

Response-success

HTTP Status: 200

{ "result": [ { "address_list_id": 65499, "address": "jg2@maillist.email.engagelab.com", "name": "1113-mailist", "member_count": 2, "Description": "desc222ss", "create_time": "2022-11-12T16:46:12+0800", "update_time": "2022-11-12T16:50:01+0800" } ], "total": 1, "count": 1 }
          {
  "result": [
            {
                "address_list_id": 65499,
                "address": "jg2@maillist.email.engagelab.com",
                "name": "1113-mailist",
                "member_count": 2,
                "Description": "desc222ss",
                "create_time": "2022-11-12T16:46:12+0800",
                "update_time": "2022-11-12T16:50:01+0800"
            }
        ],
        "total": 1,
        "count": 1
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Query address list

https://email.api.engagelab.cc/v1/address_lists/{address_list_id}
          https://email.api.engagelab.cc/v1/address_lists/{address_list_id}

        
This code block in the floating window

HTTP Request Method

GET
          GET

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Request Example

curl -X GET "https://email.api.engagelab.cc/v1/address_lists/2112423" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl -X GET "https://email.api.engagelab.cc/v1/address_lists/2112423" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Parameter Description
address_list_id 地址列表id
name 列表名称
address 别称地址,使用该别称地址进行调用,格式为xxx@maillist.email.engagelab.com
member_count 地址列表包含的地址个数
desc 地址列表描述
create_time 地址列表创建时间
update_time 地址列表修改时间

Returned Example

Response-success

HTTP Status: 200

{ "result": { "address_list_id": 65499, "address": "jg2@maillist.email.engagelab.com", "name": "1113-mailist", "member_count": 2, "Description": "desc222ss", "create_time": "2022-11-12T16:46:12+0800", "update_time": "2022-11-12T16:50:01+0800" } }
          {
  "result":
            {
                "address_list_id": 65499,
                "address": "jg2@maillist.email.engagelab.com",
                "name": "1113-mailist",
                "member_count": 2,
                "Description": "desc222ss",
                "create_time": "2022-11-12T16:46:12+0800",
                "update_time": "2022-11-12T16:50:01+0800"
            }
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Add address list

URL

https://email.api.engagelab.cc/v1/address_lists
          https://email.api.engagelab.cc/v1/address_lists

        
This code block in the floating window

Content-Type:

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

        
This code block in the floating window

HTTP Request Method

POST
          POST

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization string true Basic base64(api_user:api_key)

Body Parameter Description

Parameter Type Required or not Description
name string yes list name. Maximum 48 characters.
address string yes example: marketing@@maillist.email.engagelab.com
desc string no list Description

Request Example

curl -X POST "https://email.api.engagelab.cc/v1/address_lists" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{ "address":"scgd@email.engagelab.com", "name":"hongKong", "desc":"" }'
          curl -X POST "https://email.api.engagelab.cc/v1/address_lists" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{
"address":"scgd@email.engagelab.com",
"name":"hongKong",
"desc":""
}'

        
This code block in the floating window

Returned Value Description

Parameter Description
address_list_id id of  list
address address of list
member_count count of member in the list
name list name
desc address list Description
create_time time of address list creation
update_time time of address list modification

Returned Value Example

response success { "result": { "address_list_id": 65504, "address": "jg3@maillist.email.engagelab.com", "name": "1113-mailist", "member_count": 0, "desc": "desc", "create_time": "2022-11-15T16:25:02+0800", "update_time": "2022-11-15T16:25:02+0800" } } response error { "code": 30000, "message": "Authentication failed." }
          response success
{
     "result": {
            "address_list_id": 65504,
            "address": "jg3@maillist.email.engagelab.com",
            "name": "1113-mailist",
            "member_count": 0,
            "desc": "desc",
            "create_time": "2022-11-15T16:25:02+0800",
            "update_time": "2022-11-15T16:25:02+0800"
        }
}

response error
{ 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Delete address list

URL

https://email.api.engagelab.cc/v1/address_lists/{address_list_id}
          https://email.api.engagelab.cc/v1/address_lists/{address_list_id}

        
This code block in the floating window

HTTP Request Method

DELETE
          DELETE

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Request Example

curl -X DELETE "https://email.api.engagelab.cc/v1/address_list/2112423" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl -X DELETE "https://email.api.engagelab.cc/v1/address_list/2112423" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Parameter Description
count count of deleted lists

Returned Value Example

Response-success

HTTP Status: 200

{ "count": 1 }
          {
  "count": 1   
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Modify address list

URL

https://email.api.engagelab.cc/v1/address_lists/{address_list_id}
          https://email.api.engagelab.cc/v1/address_lists/{address_list_id}

        
This code block in the floating window

Content-Type:

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

        
This code block in the floating window

HTTP Request Method

PUT
          PUT

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Parameter Description

Parameter Type Required or not Description
address string no example: marketing@@maillist.email.engagelab.com
name string no name of modified list
desc string no Description of modified list

Tips:

【name】 or 【desc】can be modified individually or in combination
          【name】 or 【desc】can be modified individually or in combination

        
This code block in the floating window

Request Example

curl -X PUT "https://email.api.engagelab.cc/v1/address_lists" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{ "address":"new@maillist.email.engagelab.com", "name":"GZ", "desc":"2" }'
          curl -X PUT "https://email.api.engagelab.cc/v1/address_lists" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{
"address":"new@maillist.email.engagelab.com",
"name":"GZ",
"desc":"2"
}'

        
This code block in the floating window

Returned Value Description

Response-success

HTTP Status: 200

Parameter Description
count count of modified lists

Returned Value Description

Response-success

HTTP Status: 200

{ "count": 1 }
           { 
   "count": 1
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Query list member

URL

https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members
          https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members

        
This code block in the floating window

HTTP Request Method

GET
          GET

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Query Parameter Description

Parameter Type Required or not Description
offset int not offset position, [0-], defaults to 0.
limit int not amount, [0-100],defaults to 100.
email string note query member email address. Fuzzy search is supported.
member_ids string not multiple member IDs Separated by ';' . Up to 100.

Request Example

curl "https://email.api.engagelab.cc/v1/address_lists/123/members?offset=0&limit=20 --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl "https://email.api.engagelab.cc/v1/address_lists/123/members?offset=0&limit=20 --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Parameter Description
member_id ID of member
email email address of member
name member name
vars variables
create_time time of address list creation
update_time time of address list modification

Returned Value Example

Response-success

HTTP Status: 200

{ "result": [ { "member_id": "11719293", "email": "example2@abc.com", "name": null, "vars": "{\"loc\":\"sss\"}", "create_time": "2022-11-13 11:23:44", "update_time": "2022-11-13 11:23:44" }, { "member_id": "11719294", "email": "example5@abc.com", "name": null, "vars": "{\"loc\":\"sss\"}", "create_time": "2022-11-15 16:34:47", "update_time": "2022-11-15 16:34:47" } ], "total": 2, "count": 2, "address_list_id": "65499" }
          {
    "result": [
        {
            "member_id": "11719293",
            "email": "example2@abc.com",
            "name": null,
            "vars": "{\"loc\":\"sss\"}",
            "create_time": "2022-11-13 11:23:44",
            "update_time": "2022-11-13 11:23:44"
        },
        {
            "member_id": "11719294",
            "email": "example5@abc.com",
            "name": null,
            "vars": "{\"loc\":\"sss\"}",
            "create_time": "2022-11-15 16:34:47",
            "update_time": "2022-11-15 16:34:47"
        }
    ],
    "total": 2,
    "count": 2,
    "address_list_id": "65499"
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Add list member

URL

https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members
          https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members

        
This code block in the floating window

Content-Type:

application/json; charset=utf-8
          application/json; charset=utf-8

        
This code block in the floating window

HTTP Request Method

POST
          POST

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Body Parameter Description

Parameter Type Required or not Description
members array[object] yes lists of members .  Up to 1000 members.
email string yes email address.
name string no name of member.  Maximum 128 characters.
vars string no variables . Maximum is 1 KB.

Tips:

1. When adding vars variables, note that the key does not need to be marked with '%', and the length of the key cannot exceed 32 characters. 2. In the vars variable, the variable whose key is name will be overwritten by the Parameter name. 3. When sending the address list, you can use the global variable recipient, whose value is the recipient's email address.
          1. When adding vars variables, note that the key does not need to be marked with '%', and the length of the key cannot exceed 32 characters.
2. In the vars variable, the variable whose key is name will be overwritten by the Parameter name.
3. When sending the address list, you can use the global variable recipient, whose value is the recipient's email address.

        
This code block in the floating window

Request Example

curl -X POST "https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{"members":[{"email":"example6@abc.com","vars":{"loc":"sss"}}]}'
          curl -X POST "https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{"members":[{"email":"example6@abc.com","vars":{"loc":"sss"}}]}'

        
This code block in the floating window

Returned Value Description

Field Description
count count of added members
invalid Invalid member
invalidCount count of email addresses that failed to be added
reasonList the reason for the failed email address to be added (corresponding to the address details)

Returned Value Example

Response-success

HTTP Status: 200

{ "result": { "count": 2, "invalidCount": 1, "invalid": [ "wang.@yahoo.com" ], "reasonList": [ "Member email format erorr" ] } }
          {
    "result": {
        "count": 2,
        "invalidCount": 1,
        "invalid": [
            "wang.@yahoo.com"
        ],
        "reasonList": [
            "Member email format erorr"
        ]
    }
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Modify list member

URL

https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members/{member_id}
          https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members/{member_id}

        
This code block in the floating window

Content-Type:

application/json; charset=utf-8
          application/json; charset=utf-8

        
This code block in the floating window

HTTP Request Method

PUT
          PUT

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Body Parameter Description

Parameter Type Required or not Description
member object yes member of address list
email string yes email address
name string no name of member. Maximum 128 characters.
vars object no variables . Maximum is 1 KB. The length of the key cannot exceed 32 characters

Request Example

curl -X PUT "https://email.api.engagelab.cc/v1/address_lists/123/members/1222002" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>" --header "Content-Type: application/json" --data '{"member":{"email":"x@engagelab.com","name":"jim"}}'
          curl -X PUT "https://email.api.engagelab.cc/v1/address_lists/123/members/1222002" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>" 
--header "Content-Type: application/json" 
--data '{"member":{"email":"x@engagelab.com","name":"jim"}}'

        
This code block in the floating window

Returned Value Description

Field Description
count count of modified addresses
reason the reason for the failed email address to be updated

Returned Value Example

Response-success

HTTP Status: 200

{ "count": 0, "reason": "Member email format erorr" }
          {
    "count": 0,
    "reason": "Member email format erorr" 
}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window

Delete list member

URL

https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members
          https://email.api.engagelab.cc/v1/address_lists/{address_list_id}/members

        
This code block in the floating window

HTTP Request Method

DELETE
          DELETE

        
This code block in the floating window

Request Header

Header Type Required Description
Authorization String true Basic base64(api_user:api_key)

Query Parameter Description

Parameter Type Required or not Description
member_ids string yes A semicolon-separated list of  member's ID. Separated by ';', up to 100 members.

Request Example

curl -X DELETE "https://email.api.engagelab.cc/v1/address_lists/123/members?member_ids=12242;1224" --header "Authorization: Basic <<YOUR_API_KEY_HERE>>"
          curl -X DELETE "https://email.api.engagelab.cc/v1/address_lists/123/members?member_ids=12242;1224" 
--header "Authorization: Basic <<YOUR_API_KEY_HERE>>"

        
This code block in the floating window

Returned Value Description

Field Description
count count of deleted addresses

Returned Value Example

Response-success

HTTP Status: 200

{ "count": 1}
           { "count": 1}

        
This code block in the floating window

Response-error

HTTP Status :401

{ "code": 30000, "message": "Authentication failed." }
          { 
    "code": 30000,
    "message": "Authentication failed."
}

        
This code block in the floating window
在文档中心打开
icon
Contact Sales