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

联系人

你发送营销邮件的对象,包含订阅状态和自定义属性,可在控制台或通过 API 管理。

联系人是团队名单中的一个邮箱地址。每个地址只会出现一次(不区分大小写),通过 分群 和 订阅主题 选择谁会收到群发。可以在控制台的 联系人 下管理联系人,也可以通过 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,也可以填它的邮箱地址。

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

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,还会从邮件历史、事件载荷和 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。已有联系人仍可更新。

这个页面有帮助吗?