联系人API

概述

通过 EffiLink 联系人 API 创建、更新、批量导入、获取与删除联系人。支持名单分配与沙盒测试。

添加或更新单个联系人

POST /v5/contacts/upsert 创建新联系人或更新现有联系人。必须至少提供 email 或 phoneNumber 之一。

请求体

string

联系人的显示名称。若省略,默认为邮箱地址。

string

必填

联系人的邮箱地址。如果未提供 phoneNumber,则必填。

string

必填

联系人的电话号码。如果未提供 email,则必填。

string

更新插入后将该联系人添加到的现有联系人组名称。

boolean

为 true 时,操作被模拟且不持久化任何数据。

响应

int

成功时为 200。

string

成功时为空字符串;失败时为错误描述。

curl --request POST \
  --url https://api.effilink.co/v5/contacts/upsert \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phoneNumber": "18800008888",
    "listName": "Newsletter Subscribers"
  }'

Response

{
  "code": 200,
  "message": ""
}

批量导入联系人

POST /v5/contacts/imports 使用二维数组格式配合列映射定义,在一次请求中导入多个联系人。

请求体

array[array]

必填

联系人值的二维数组。每个内部数组代表一条联系人行;列顺序必须与 contactDataMapping 匹配。

array[object]

必填

描述每列映射到的属性。

显示 contactDataMapping 对象

int

必填

contactData 中列的从零开始的索引。

string

必填

列的属性标识符(例如 email、name)。请参见联系人属性参考了解有效值。

int

必填

控制现有联系人的处理方式:

1 — 创建新联系人并更新现有联系人。
2 — 仅创建新联系人;跳过现有联系人。
3 — 仅更新现有联系人;跳过新联系人。

string

将所有导入的联系人添加到的联系人组名称。

string

通过 listName 创建新联系人组时应用的描述。

boolean

为 true 时,操作被模拟且不持久化任何数据。

响应

int

成功时为 200。

string

成功时为空字符串;失败时为错误描述。

curl --request POST \
  --url https://api.effilink.co/v5/contacts/imports \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{
    "contactData": [
      ["alice@example.com", "Alice Chen"],
      ["bob@example.com", "Bob Wang"]
    ],
    "contactDataMapping": [
      {"columnNum": 0, "propertyName": "email"},
      {"columnNum": 1, "propertyName": "name"}
    ],
    "updateMode": 1,
    "listName": "Q2 Campaign"
  }'

Response

{
  "code": 200,
  "message": ""
}

获取联系人

POST /v5/contacts/get 按邮箱地址获取单个联系人记录。

请求体

string

必填

要获取的联系人的邮箱地址。

响应

int

成功时为 200。

string

成功时为空字符串;失败时为错误描述。

object

匹配的联系人记录。

显示 contact 对象

string

联系人的唯一标识符。

string

联系人的显示名称。

string

联系人的邮箱地址。

string

联系人的电话号码。

object

自定义和系统属性的键值映射(例如 company、email_bounced_flag、email_open_count)。所有值均为字符串。

string

联系人创建时间的 ISO 8601 时间戳。

string

最近一次更新的 ISO 8601 时间戳。

int

创建联系人的用户的 ID。

curl --request POST \
  --url https://api.effilink.co/v5/contacts/get \
  --header 'Content-Type: application/json' \
  --header 'ApiKey: YOUR_API_KEY' \
  --data '{"email": "alice@example.com"}'

Response

{
  "code": 200,
  "message": "",
  "contact": {
    "id": "653f663a17e04f6e5a263de6",
    "name": "Alice Chen",
    "email": "alice@example.com",
    "phoneNumber": "18800008888",
    "properties": {
      "company": "Acme Inc",
      "email_bounced_flag": "0",
      "email_open_count": "5"
    },
    "createDate": "2024-01-15T08:00:00.000Z",
    "modifyTime": "2025-04-21T05:53:01.089Z",
    "createUserId": 42
  }
}

获取组中的联系人

POST /v5/contacts/list/get 返回属于指定联系人组的分页联系人列表。

请求体

string

必填

要从中获取联系人的联系人组名称。

int

每页返回的联系人数。默认为 200;最大值为 1000。

int

从 1 开始的页码。默认为 1。

string

查询属于其他团队的组。需要特殊的跨团队权限。

响应

int

成功时为 200。

string

成功时为空字符串;失败时为错误描述。

array[object]

联系人记录数组。每个对象包含与获取联系人响应相同的字段:id、name、email、phoneNumber、properties、createDate、modifyTime 和 createUserId。

int

跨所有页面组中的联系人总数。

删除联系人

POST /v5/contacts/delete 按邮箱地址永久删除联系人。

请求体

string

必填

要删除的联系人的邮箱地址。

boolean

为 true 时,操作被模拟且不删除任何数据。

响应

int

成功时为 200。

string

成功时为空字符串;失败时为错误描述。

Response

{
  "code": 200,
  "message": ""
}

事务性邮件

营销邮件

短信

联系人与名单

Webhooks

身份验证

概述

添加或更新单个联系人

请求体

响应

批量导入联系人

请求体

响应

获取联系人

请求体

响应

获取组中的联系人

请求体

响应

删除联系人

请求体

响应

​概述

​添加或更新单个联系人

​请求体

​响应

​批量导入联系人

​请求体

​响应

​获取联系人

​请求体

​响应

​获取组中的联系人

​请求体

​响应

​删除联系人

​请求体

​响应

概述

添加或更新单个联系人

请求体

响应

批量导入联系人

请求体

响应

获取联系人

请求体

响应

获取组中的联系人

请求体

响应

删除联系人

请求体

响应