---
title: 聯絡人
description: 你寄送行銷郵件的對象，包含訂閱狀態與自訂屬性。
ai:
  exclude: true
---

聯絡人就是團隊名單中的一個 Email 位址。每個位址只會出現一次（不分大小寫），你可以用[分群](/docs/zh-hant/concepts/segments)與[訂閱主題](/docs/zh-hant/concepts/topics)決定誰會收到群發。在控制台的**聯絡人**管理聯絡人，也可以透過 API 管理。

## 聯絡人包含的資料

- `email`：位址。用相同位址建立第二個聯絡人會回傳 `409`。永遠收不到信的位址（例如 `example.com`、`.test` 結尾的名稱，或沒有郵件伺服器的網域）會回傳 `422`。
- `first_name`、`last_name`。
- `unsubscribed`：你的團隊層級退訂。當它是 `true` 時，聯絡人不會收到你任何網域寄出的行銷郵件。只有你能設定它，收件者自己的退訂不會改動它。
- `unsubscribed_domains`：唯讀。聯絡人透過退訂連結離開的網域，每個都有 `domain_id`、`name` 與 `unsubscribed_at`。這些網域寄出的信會略過該聯絡人，你的其他網域仍然寄得到。請見[退訂](/docs/zh-hant/concepts/unsubscribes)。
- `verification_status` 與 `verified_at`：唯讀。聯絡人最近一次深度驗證的結果，尚未驗證時為 `null`。請見[驗證](/docs/zh-hant/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 或 Email 位址。

```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 或 Email 讀取 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`，會一併從 Email 歷史記錄、事件內容與 API 日誌中移除每個位址。`DELETE /contacts/{id}?erase=true` 對單一聯絡人做同樣的事。

## CSV 匯入與匯出

在控制台的**聯絡人**可以匯入 CSV，也能把目前的檢視（包含分群、訂閱主題或網域篩選）匯出成 CSV。匯出檔有 `unsubscribed` 欄與 `unsubscribed_domains` 欄（`*` 代表整個團隊）。位址永遠收不到信的資料列會被略過。付費方案的匯入對話框還可以驗證新增的位址，請見[驗證](/docs/zh-hant/concepts/verification)。

## 事件

每次變更都會發出 [Webhook](/docs/zh-hant/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`，既有聯絡人仍可更新。
