联系人

您可以在仪表板的联系人 > 所有联系人中管理联系人，也可以在终端使用 bird contacts、调用联系人 API，或选用 SDKs。

向联系人发送消息

要向一个人发送电子邮件，请通过发送 API向其地址发送；联系人记录会保存其身份信息，供后续重复使用。要一次联系多人，可以批量发送，也可以将他们分组为一个受众，然后发送广播。存储联系人本身不会发送任何消息。

联系人页面

联系人页面显示联系人的姓名、标识符、受众成员关系和创建信息。按姓名、电子邮件或电话号码搜索，然后选择一行打开联系人。使用页面顶部的操作添加一个联系人或导入多个联系人。查看需要 email_marketing 读取权限。添加、编辑和删除需要写入权限。

联系人包含的信息

每个联系人都有电子邮件地址、电话号码或两者兼有，每个标识符在您的工作区中都是唯一的。您还可以填写姓名和自己的标识符：

字段	说明
email	电子邮件地址，在您的工作区中唯一。我们会去除首尾空白并转换为小写后存储，因此 Sam@Acme.com 和 sam@acme.com 会规范化为同一个标识符。
phone_number	电话号码，在您的工作区中唯一。格式会规范化为国际格式。存储号码不会验证号码规划元数据、归属权、可达性或同意状态。
first_name	可选的名字，用于个性化发送内容。
last_name	可选的姓氏。
external_id	可选。您为此人设置的主键（来自您数据库的用户 ID），设置后在工作区中唯一。它用于将联系人匹配回您自己的记录，无需依赖电子邮件地址。
data	自定义属性值，每个已注册的联系人属性对应一个值。

仪表板根据已有标识符生成电子邮件和 SMS 标签。API 返回 email 和 phone_number，不返回 channels 字段。这些标签不能证明您具有发送权限，也不能证明该渠道可达。

每个联系人还有一个以 con_ 为前缀的 ID，以及创建和更新时间戳。完整的字段约定请参阅 API 参考。

联系人属性

联系人属性为联系人的自定义字段定义类型。在工作区中注册一个属性后，每个联系人都可以在 data 下保存该属性的值。预先声明结构定义可以让个性化和分群更可靠：收到的值始终符合您声明的类型，因此模板或筛选器可以依赖这一点。

在联系人 > 联系人属性中管理属性。每个属性都有键、类型和可选的回退值：

键是引用值时使用的名称，例如 plan_tier。它必须使用小写字母并以字母开头（^[a-z][a-z0-9_]*$），创建后不可更改。
类型可以是 string、number、boolean 或 datetime，创建后同样不可更改。datetime 接收带明确时区偏移量的 RFC 3339 时间戳，例如 2026-01-15T11:30:00+02:00。我们会将其规范化为 UTC，精确到秒，因此该值会以 2026-01-15T09:30:00Z 的形式存储和返回。只有日期而没有时间的值会被拒绝。仪表板将这些类型标记为文本、数字、真 / 假和日期与时间。
回退值是联系人没有自己的属性值时读取到的值，因此缺少 plan_tier 时，可以得到 free，而不是空值。

属性采用归档方式保留，不会被删除。归档会停止对该键的新写入，同时保留所有已存储的值。键会保持保留状态，无法以其他类型重新使用。取消归档即可恢复使用。这也是类型不可更改的原因：已存储的 number 不能转而被当作 string 读取。一个工作区最多可注册 200 个属性，已归档属性也计入此上限，因为其键仍被保留。

您可以在编辑联系人的位置设置属性值。仪表板的联系人表单会为每个未归档的属性显示符合其类型的输入框，CLI 和 API 也在 data 下接收相同的键。

导入和同步联系人

要从联系人页面导入列表，请选择导入并上传 CSV、TSV 或 Excel 文件。每行填写一个联系人，并包含一行用于命名各列的表头。一个文件最多可包含 50,000 个联系人。CSV 文件最大为 50 MB，电子表格文件最大为 10 MB。

表头行有助于识别每个联系人字段。名为 "Email Address"、"E-Mail" 或 "Correo electrónico" 的列都会映射到电子邮件字段。如果一列包含完整姓名，则会拆分为名字和姓氏。如果两列都可以填入同一个字段，会选择内容与列名相符的那一列。每列会显示几个自身的值，方便您查看其中的内容；拆分后的姓名也会与其原始值一起显示。您可以通过各列的下拉菜单更改映射。同一次导入也可以将文件中的所有人添加到一个或多个受众。

每行会根据其标识符匹配现有联系人并更新；如果是新联系人，则创建记录。因此，重新导入同一个文件会执行更新或插入，而不会堆积重复记录。在写入任何数据之前，仪表板会报告最初的行中有多少行无法按当前映射导入。运行后，每个跳过的行都会列出源文件行号和错误。

要从您自己的数据库同步，请编写 CLI 脚本或调用批量端点。bird contacts create <email> 添加一个联系人。bird contacts batch 在一次调用中最多更新或插入 1,000 个联系人。每次运行使用一个批次，无需为每个人分别发送请求，即可使联系人列表与您的系统保持同步。

const contact = await bird.contacts.create({
  email: "jane@acme.com",
  first_name: "Jane",
});
console.log(contact.id); // "con_…"

contact = client.contacts.create(email="jane@acme.com", first_name="Jane")
print(contact.id, contact.email)

contact, err := client.Contacts.Create(context.Background(), bird.ContactCreateParams{
	Email:     bird.Ptr("jane@acme.com"),
	FirstName: bird.Ptr("Jane"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(contact.Id)

$contact = $bird->contacts->create(
    (new ContactCreateRequest())
        ->setEmail('jane@acme.com')
        ->setFirstName('Jane'),
);
echo $contact->getId(); // "con_…"

bird contacts create alice@acme.com \
  --first-name Alice \
  --last-name Anderson \
  --phone-number +31612345678

{
  "name": "contacts_create",
  "arguments": {
    "email": "alice@acme.com",
    "first_name": "Alice",
    "last_name": "Anderson",
    "phone_number": "+31612345678"
  }
}

curl -X POST "https://{region}.platform.bird.com/v1/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acme.com",
    "phone_number": "+31612345678",
    "first_name": "Alice",
    "last_name": "Anderson"
  }'

每个批次条目会根据其提供的标识符（电子邮件地址、电话号码或外部 ID）自动匹配；可选的 match_on 字段则会强制仅使用其中一个标识符进行匹配。条目还可以设置自定义属性值，并通过 audience_ids 将请求中的每个联系人直接加入受众。每个条目独立成功或失败，响应会按提交顺序为每个条目报告一个结果：

代码示例

{
  "data": [
    {
      "contact_id": "con_01ky7q5t51echr7mqj5c08423b",
      "entry": { "email": "alex@example.com", "phone_number": null, "external_id": null },
      "matched_on": "email",
      "status": "updated"
    },
    {
      "contact_id": "con_01ky7q6mxdfhe86c9dqyt866pz",
      "entry": { "email": "jamie@example.com", "phone_number": null, "external_id": null },
      "matched_on": null,
      "status": "created"
    },
    {
      "contact_id": "con_01ky7q7rv9e9pt4vkr0w0gxq5e",
      "entry": { "email": "casey@example.com", "phone_number": null, "external_id": "user_2214" },
      "matched_on": "external_id",
      "status": "updated"
    }
  ]
}

如果一个条目的标识符指向不同的现有联系人，该条目会因冲突而失败，需要检查。重试前请修正源记录；批次不会合并这些联系人。

同步时有两项有用的默认行为。批次会将 data 中的键合并到现有联系人数据，因此仅修改一个属性的导入不会清除其他属性。发送 null 值可以清空一个键，设置 data_mode: "replace" 可以覆盖整个映射。为每个联系人设置您自己的 external_id，这样即使电子邮件地址改变，后续同步也能找到同一个人。在批次示例中，user_2214 已存在，因此该条目会匹配到这个联系人，并将其原地址更新为新地址。

删除联系人

删除联系人是永久操作：记录及其受众成员关系会被删除，无法恢复。但屏蔽记录和偏好不受影响。删除联系人后，发生过硬退信的地址仍保留在您的屏蔽列表中，已退订的地址也会保留其拒绝接收偏好。因此，删除某人不会在无提示的情况下使其重新变得可发送。

后续步骤

受众：将联系人分组为可重复使用的列表
屏蔽列表：工作区中我们不会向其投递邮件的地址列表，与联系人分开管理
批量发送：通过一次调用联系多个收件人，每个请求最多 100 条消息
CLI：使用 bird 命令编写联系人、属性和受众操作脚本
API 参考：完整的请求和响应结构定义

相关资源