地址清單

地址清單為用戶批量發送時使用。

你可以使用 API 對地址清單進行査詢，添加，修改，删除操作。

也可以對地址清單中地址成員進行査詢，添加，修改，删除操作。

調用地址

數據中心	URL
新加坡	https://email.api.engagelab.cc
土耳其	https://emailapi-tr.engagelab.com

當使用REST API時，需要確認使用的數據中心選擇對應的base URL。

POST/v1/address_lists

査詢地址清單（批量査詢）

URL

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

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

此代碼塊在浮窗中顯示

HTTP 請求方式

GET

GET

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	説明
Authorization	string	true	Basic base64(api_user:api_key)

Query 參數説明

參數	類型	必須	説明
offset	int	否	査詢起始位置，取值區間 [0-]，默認為 0。
limit	int	否	査詢個數，取值區間 [0-100]，默認為 100。
name	string	否	清單名稱。模糊查詢。
address	striing	否	別稱地址。精確查詢。

請求示例

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='

此代碼塊在浮窗中顯示

響應説明

字段	説明
address_list_id	地址清單 id
name	清單名稱
address	別稱地址，使用該別稱地址進行調用，格式為 xxx@maillist.email.engagelab.com 。
member_count	地址清單包含的地址個數
desc	地址清單描述
create_time	地址清單創建時間
update_time	地址清單修改時間

響應示例

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
}

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

査詢地址清單

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

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

此代碼塊在浮窗中顯示

HTTP 請求方式

GET

GET

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	説明
Authorization	string	true	Basic base64(api_user:api_key)

請求示例

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>>"

此代碼塊在浮窗中顯示

響應説明

字段	説明
address_list_id	地址清單 id
name	清單名稱
address	別稱地址，使用該別稱地址進行調用，格式為 xxx@maillist.email.engagelab.com 。
member_count	地址清單包含的地址個數
desc	地址清單描述
create_time	地址清單創建時間
update_time	地址清單修改時間

響應示例

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"
            }
}

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

添加地址清單

URL

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

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

此代碼塊在浮窗中顯示

Content-Type:

application/json; charset=utf-8

              
              application/json; charset=utf-8

此代碼塊在浮窗中顯示

HTTP 請求方式

POST

              
              POST

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	説明
Authorization	string	true	Basic base64(api_user:api_key)

Body 參數

參數	類型	必須	説明
name	string	是	清單名稱。最長 48 字符。
address	string	是	別稱地址。郵箱地址格式，例如： marketing@maillist.email.engagelab.com。
desc	string	否	描述資訊。最長 255 字符。

請求示例

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@maillist.email.engagelab.com", "name":"Beijing", "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@maillist.email.engagelab.com",
"name":"Beijing",
"desc":""
}'

此代碼塊在浮窗中顯示

響應説明

字段	説明
address_list_id	清單 id
name	清單名稱
address	別稱地址
member_count	清單中地址數
desc	清單描述資訊
create_time	地址清單創建時間
update_time	地址清單修改時間

響應示例

Response-success

HTTP Status: 200

{ "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" } }

              
              
{
     "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

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

删除地址清單

URL

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

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

此代碼塊在浮窗中顯示

HTTP 請求方式

DELETE

              
              DELETE

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	説明
Authorization	string	true	Basic base64(api_user:api_key)

請求示例

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

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

此代碼塊在浮窗中顯示

響應説明

參數	説明
count	成功删除的個數

響應示例

Response-success

HTTP Status: 200

{ "count": 1 }

              
              {
  "count": 1   
}

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

修改地址清單

URL

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

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

此代碼塊在浮窗中顯示

HTTP 請求方式

PUT

PUT

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	説明
Authorization	string	true	Basic base64(api_user:api_key)

Body 參數説明

參數	類型	必須	説明
address	string	否	別稱地址，使用該別稱地址進行調用，格式為 xxx@@maillist.email.engagelab.com
name	string	否	修改後的清單名稱。最長 48 字符。
desc	string	否	修改後的清單描述資訊。最長 255 字符。

説明

【name】或者【desc】的組合

              
              【name】或者【desc】的組合

此代碼塊在浮窗中顯示

請求示例

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":"北京用户 2", "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":"北京用户 2",
"desc":"2"
}'

此代碼塊在浮窗中顯示

響應説明

字段	説明
count	成功修改的個數

響應示例

Response-success

HTTP Status: 200

{ "count": 1 }

              
               { 
   "count": 1
}

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

査詢清單成員

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

此代碼塊在浮窗中顯示

HTTP 請求方式

GET

GET

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	説明
Authorization	string	true	Basic base64(api_user:api_key)

Query 參數説明

參數	類型	必須	説明
offset	int	否	査詢起始位置，取值區間 [0-]，默認為 0
limit	int	否	査詢個數，取值區間 [0-100]，默認為 100
email	string	否	査詢成員郵箱地址。支持模糊搜索。
member_ids	string	否	成員 ID 多個用；號分隔。最多 100 個。

請求示例

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>>"

此代碼塊在浮窗中顯示

響應説明

字段	説明
member_id	成員 ID
email	成員郵箱地址
name	成員姓名
vars	變數
create_time	創建時間
update_time	更新時間

響應示例

Response-success

HTTP Status: 200

{ "result": [ { "member_id": "11719293", "email": "example2@abc.com", "name": null, "vars": {"loc":"sss"}, "create_time": "2022-11-13T11:23:44+0800", "update_time": "2022-11-13T11:23:44+0800" }, { "member_id": "11719294", "email": "example5@abc.com", "name": null, "vars": {"loc":"sss"}, "create_time": "2022-11-15T16:34:47+0800", "update_time": "2022-11-15T16:34:47+0800" } ], "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-13T11:23:44+0800",
            "update_time": "2022-11-13T11:23:44+0800"
        },
        {
            "member_id": "11719294",
            "email": "example5@abc.com",
            "name": null,
            "vars": {"loc":"sss"},
            "create_time": "2022-11-15T16:34:47+0800",
            "update_time": "2022-11-15T16:34:47+0800"
        }
    ],
    "total": 2,
    "count": 2,
    "address_list_id": "65499"
}

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

添加清單成員

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

此代碼塊在浮窗中顯示

Content-Type:

application/json; charset=utf-8

              
              application/json; charset=utf-8

此代碼塊在浮窗中顯示

HTTP 請求方式

POST

              
              POST

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	説明
Authorization	string	true	Basic base64(api_user:api_key)

Body 參數説明

參數	類型	必須	説明
members	array[object]	是	成員。最多 1000 個成員
email	string	是	成員郵箱地址，郵寄地址格式。
name	string	否	昵稱。最長 128 個字符。
vars	object	否	變數。最大不超過 1KB。

説明

1. 添加 vars 變數，注意 key 不需要帶上'%'，key 長度不得超過 32 個字符。 2. vars 變數中，key 為 name 的變數會被參數 name 覆蓋 3. 地址清單發送時，可以使用全域變數 recipient，值為收件人的郵箱地址

              
              1. 添加 vars 變數，注意 key 不需要帶上'%'，key 長度不得超過 32 個字符。
2. vars 變數中，key 為 name 的變數會被參數 name 覆蓋
3. 地址清單發送時，可以使用全域變數 recipient，值為收件人的郵箱地址

此代碼塊在浮窗中顯示

請求示例

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"}}]}'

此代碼塊在浮窗中顯示

響應説明

字段	説明
count	添加成功的地址數
invalid	添加失敗的地址
invalidCount	添加失敗的郵件地址數
reasonList	添加失敗的郵件地址原因(與地址明細一一對應)

響應示例

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"
        ]
    }
}

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

修改清單成員

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}

此代碼塊在浮窗中顯示

Content-Type:

application/json; charset=utf-8

              
              application/json; charset=utf-8

此代碼塊在浮窗中顯示

HTTP 請求方式

PUT

PUT

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	說明
Authorization	string	true	Basic base64(api_user:api_key)

Body 參數説明

參數	類型	必須	説明
email	string	否	成員郵箱地址，郵寄地址格式。
name	string	否	昵稱。最长 128 个字符。
vars	object	否	變數。最大不超过 1KB。key 長度不得超過 32 个字符。

請求示例

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 '{"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 '{"email":"x@engagelab.com","name":"jim"}'

此代碼塊在浮窗中顯示

響應説明

字段	説明
count	成功修改的記錄數
reason	失敗的原因(成功時沒有此字段)

響應示例

Response-success

HTTP Status: 200

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

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

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示

删除清單成員

URL

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

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

此代碼塊在浮窗中顯示

HTTP 請求方式

DELETE

              
              DELETE

此代碼塊在浮窗中顯示

請求 Headers

Header	類型	必須	說明
Authorization	string	true	Basic base64(api_user:api_key)

Query 參數説明

參數	類型	必須	説明
member_ids	string	是	需要删除成員的地址，多個地址用`;` 分隔，最多 100 個成員。

請求示例

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>>"

此代碼塊在浮窗中顯示

響應説明

字段	説明
count	成功删除地址數

響應示例

Response-success

HTTP Status: 200

{ "count": 1}

              
               { "count": 1}

此代碼塊在浮窗中顯示

Response-error

HTTP Status :401

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

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

此代碼塊在浮窗中顯示