跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

聯絡人

你寄送行銷郵件的對象,包含訂閱狀態與自訂屬性。

聯絡人就是團隊名單中的一個 Email 位址。每個位址只會出現一次(不分大小寫),你可以用分群與訂閱主題決定誰會收到群發。在控制台的聯絡人管理聯絡人,也可以透過 API 管理。

聯絡人包含的資料

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

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)。

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" }]'
{
  "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 欄(* 代表整個團隊)。位址永遠收不到信的資料列會被略過。付費方案的匯入對話框還可以驗證新增的位址,請見驗證。

事件

每次變更都會發出 Webhook 事件: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,既有聯絡人仍可更新。

这个页面有帮助吗?