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.

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