---
title: 联系人
description: 你发送营销邮件的对象，包含订阅状态和自定义属性，可在控制台或通过 API 管理。
ai:
  exclude: true
---

联系人是团队名单中的一个邮箱地址。每个地址只会出现一次（不区分大小写），通过 [分群](/docs/zh-hans/concepts/segments) 和 [订阅主题](/docs/zh-hans/concepts/topics) 选择谁会收到群发。可以在控制台的 **联系人** 下管理联系人，也可以通过 API 管理。

## 联系人包含什么

- `email`：邮箱地址。用相同地址再创建一个联系人会返回 `409`。永远收不到邮件的地址（例如 `example.com`、`.test` 域名，或没有邮件服务器的域名）会返回 `422`。
- `first_name`、`last_name`。
- `unsubscribed`：你为整个团队设置的退订开关。为 `true` 时，该联系人不会收到你任何域名发出的营销邮件。只有你可以设置它，收件人自己的退订不会改变它。
- `unsubscribed_domains`：只读。联系人通过退订链接离开的域名，每项包含 `domain_id`、`name` 和 `unsubscribed_at`。这些域名发出的邮件会跳过该联系人，你的其他域名仍能触达他。参见 [退订](/docs/zh-hans/concepts/unsubscribes)。
- `verification_status` 和 `verified_at`：只读。联系人最近一次深度验证的结果，未验证时为 `null`。参见 [邮箱验证](/docs/zh-hans/concepts/verification)。
- `properties`：自定义值，例如 `plan: "pro"` 或 `city: "Berlin"`。值为字符串或数字（嵌套对象或数组会返回 `422`），每位联系人最多 100 个键。属性会填入模板的合并字段和分群筛选条件。`PATCH` 按键合并属性，值为 `null` 会删除该键。

## 创建与读取

`POST /contacts`、`GET /contacts`、`GET /contacts/{id}`、`PATCH /contacts/{id}` 和 `DELETE /contacts/{id}`。`{id}` 处可以填联系人的 id，也可以填它的邮箱地址。

```sh
curl -X POST "https://api.billionsend.com/contacts" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana@acme.com",
    "first_name": "Ana",
    "properties": { "plan": "pro" }
  }'
```

给 `GET /contacts` 或 `GET /segments/{id}/contacts` 加上 `include=properties,topics`，就能在同一个响应里拿到每位联系人的属性和订阅主题选择。`POST /contacts/batch/get` 一次调用最多按 id 或邮箱读取 1,000 位联系人，结果按请求顺序返回；没有匹配到的地址列在 `missing` 下。

`PATCH /contacts/{id}/topics` 设置联系人的订阅主题选择，`GET /contacts/{id}/topics` 读回这些选择，并应用订阅主题的默认值。

`POST /contacts/{id}/preferences-link` 返回联系人偏好页面的链接，方便你在产品的设置页里打开它。该链接不会过期，持有者可以修改该联系人的选择，所以只能交给联系人本人。它打开的是团队的默认页面，并让联系人退出所有域名。

## 批量创建

`POST /contacts/batch` 一次请求接收 1 到 1,000 位联系人，并一起写入。

`on_conflict` 指定地址已存在或在批量中重复时的处理方式：

- `error`（默认）：该项失败，已存在时返回 `409`，重复时返回 `422`。
- `skip`：保持已有联系人不变。
- `upsert`：把该项合并到已有联系人。姓名只在你传入时更新，属性按键合并，分群为追加，订阅主题为更新。

批量写入永远不会让任何人重新订阅：对已退订的联系人传 `unsubscribed: false` 会被忽略。要重新订阅请用 `PATCH /contacts/{id}`。

`x-batch-validation` 头可选 `strict`（默认：只要有一项无效，整批都会被拒绝）或 `permissive`（有效的项会写入，失败的项列在 `errors` 中）。

```sh
curl -X POST "https://api.billionsend.com/contacts/batch?on_conflict=upsert" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "x-batch-validation: permissive" \
  -d '[{ "email": "ana@acme.com", "properties": { "plan": "pro" } }, { "email": "not-an-address" }]'
```

```json
{
  "data": [{ "object": "contact", "index": 0, "id": "9b2f…", "status": "updated" }],
  "counts": { "created": 0, "updated": 1, "skipped": 0, "failed": 1 },
  "errors": [{ "index": 1, "statusCode": 422, "name": "validation_error", "message": "email: Invalid email address" }]
}
```

## 批量删除

`POST /contacts/batch/remove` 按 `ids` 或 `emails`（二选一）一次最多删除 1,000 位联系人，并返回已删除的联系人。加上 `erase: true`，还会从邮件历史、事件载荷和 API 日志中移除每个地址。`DELETE /contacts/{id}?erase=true` 对单个联系人做同样的事。

## CSV 导入与导出

在控制台中，**联系人** 页面可以导入 CSV，也可以把当前视图（包括分群、订阅主题或域名筛选）导出为 CSV。导出文件包含 `unsubscribed` 列和 `unsubscribed_domains` 列（`*` 表示整个团队）。地址永远收不到邮件的行会被跳过。付费套餐下，导入对话框还可以验证新地址，参见 [邮箱验证](/docs/zh-hans/concepts/verification)。

## 事件

每次变更都会发布一个 [Webhook](/docs/zh-hans/concepts/webhooks) 事件：`contact.created`、`contact.updated`、`contact.deleted`、`contact.unsubscribed`、`contact.resubscribed`、`contact.topic_opt_in` 和 `contact.topic_opt_out`。

## 限制

| | Free | Starter、Pro、Scale |
| --- | --- | --- |
| 每个团队的联系人数 | 1,000 | 不限 |

超过上限后，创建联系人会返回 `403 plan_limit_reached`。已有联系人仍可更新。
