---
title: 退订与品牌
description: 退订按发信域名记录，因此每个品牌都有自己的名单、自己的退订页面和自己的链接主机。
seo:
  title: 按域名一键退订
ai:
  exclude: true
---

退订的意思是「不再接收营销邮件」。BillionSend 会把它记录在带有该链接的邮件所用的发信域名上，所以有多个品牌的团队不会把各品牌的名单混在一起。离开某一个品牌的人，仍会收到其他品牌的邮件。

事务邮件（不带 [订阅主题](/docs/zh-hans/concepts/topics) 且不属于 [群发](/docs/zh-hans/concepts/broadcasts) 的邮件）永远不受退订影响。

## 三种范围

| 范围 | 由谁设置 | 阻止什么 |
| --- | --- | --- |
| 域名 | 收件人，通过退订链接或邮件客户端的一键退订按钮 | 发出该邮件的域名的营销邮件 |
| 整个团队 | 你，把联系人的 `unsubscribed` 设为 `true`（API、控制台或 CSV 导入） | 你团队所有域名的营销邮件 |
| 订阅主题 | 收件人，在退订页面上 | 带有该 [订阅主题](/docs/zh-hans/concepts/topics) 的邮件 |

收件人自己的退订永远不会改变联系人的 `unsubscribed` 标记。它会按邮箱地址作为键，存成该域名下的一条记录，所以即使联系人被删除后重新导入，它依然有效。

群发和订阅主题邮件会跳过已退出该发信域名、整个团队或该订阅主题的收件人。一封因此被拦截的单封邮件，最终状态为 `suppressed`，原因是 `domain_unsubscribed`、`contact_unsubscribed` 或 `topic_unsubscribed`。

退订不是 [抑制](/docs/zh-hans/concepts/suppressions)。抑制列表保存曾退信、投诉或被你屏蔽的地址，它会阻止所有邮件，包括事务邮件。退订只阻止营销邮件。

## 退订页面

每封群发和订阅主题邮件都带有一键式 `List-Unsubscribe` 头（RFC 8058）和一个指向托管退订页面的链接。在正文中写 `{{{UNSUBSCRIBE_URL}}}`，它就会为每位收件人变成同一个链接。页面按收件人浏览器的语言打开（14 种语言，回退为英文）。除了退出该域名的所有营销邮件，收件人还可以逐个开启或关闭订阅主题。

误点的收件人可以在确认页面点击 **重新订阅**。它只会撤销该链接所造成的退订。打开链接的邮件扫描器永远不会让任何人重新订阅。当你自己设置了 `unsubscribed: true` 时，页面上没有重新订阅按钮。

### 每个域名有自己的外观

页面的外观与发出邮件的域名一致。每个域名都可以设置：

- 品牌名称、Logo 和 Logo 的圆角；
- 背景色、文字颜色和强调色；
- 按钮上方的文字，以及保存选择后显示的文字；
- 退订后要打开的跳转 URL，用来代替页面上的提示信息。

在控制台中，打开域名并使用 **品牌** 标签页，它会预览效果。留空的字段会回退到团队的 **品牌默认值**（设置），再回退到 BillionSend 的朴素外观。页面只显示属于该域名的内容：它从不提及你团队的其他域名，只列出绑定到该域名的订阅主题，以及没有绑定域名的订阅主题。

通过 API，在 `PATCH /domains/{id}` 上用 `unsubscribe_page` 发送这些字段。`null` 会清除一个字段。Logo 在控制台中上传，在 API 中只读。

```sh
curl -X PATCH "https://api.billionsend.com/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribe_page": {
      "brand_name": "Acme",
      "message": "Sorry to see you go. Unsubscribe from Acme emails?",
      "success_message": "You are unsubscribed from Acme.",
      "accent_color": "#0a7d5a",
      "logo_radius": "rounded"
    }
  }'
```

在邮件之外生成的链接，例如 `POST /contacts/{id}/preferences-link` 返回的链接，会打开团队的默认页面，在那里退订会让联系人退出所有域名。

### 你自己的退订子域名

默认情况下，链接在 BillionSend 的主机上打开。要让它们在你自己的域名上打开，请在域名的 **链接** 标签页中为它设置退订子域名，或在 `POST /domains` 或 `PATCH /domains/{id}` 上使用 `unsubscribe_subdomain`（一个标签，例如 `unsubscribe` 对应 `unsubscribe.yourdomain.com`；`null` 会清除它）。它的工作方式与追踪子域名相同，参见 [域名](/docs/zh-hans/concepts/domains)。

1. 添加域名的 **DNS** 标签页中显示的 CNAME，指向 `cname.billiondns.com`，并设为仅 DNS（Cloudflare 上是灰色云朵）。
2. CNAME 解析生效后会自动签发证书，通常在几分钟内。`unsubscribe_status` 会从 `pending` 变为 `active`，没有生效时 `unsubscribe_error` 会说明原因。
3. 之后的新邮件会在链接和 `List-Unsubscribe` 头中使用你的主机。在激活之前，以及出现 `failed` 结果（72 小时内仍未激活）之后，会使用共享主机。

已经发出的链接会一直使用发送时的主机，所以如果你之后移除 CNAME，它们就会失效。你的子域名只会打开它所属域名的链接，任何其他链接都返回 `404`。

追踪和退订可以共用同一个标签，但分开命名更安全：广告拦截器会拦截追踪主机，共用的名称会让退订链接一起被拦截。

## 读取与修改退订

`GET /contacts/{id}` 返回 `unsubscribed`（整个团队的标记）和 `unsubscribed_domains`。在控制台中，联系人页面会列出这两项，并允许你移除某个域名的退订。**联系人** 下的 **退订** 标签页列出所有记录。

```sh
# List, newest first. domain_id narrows to one domain.
curl "https://api.billionsend.com/unsubscribes?domain_id=$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..."

# Record an opt-out from one domain (leave domain_id out for every domain)
curl -X POST "https://api.billionsend.com/unsubscribes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.org", "domain_id": "'"$DOMAIN_ID"'" }'

# Remove one record
curl -X DELETE "https://api.billionsend.com/unsubscribes/$UNSUBSCRIBE_ID" \
  -H "Authorization: Bearer bs_..."
```

`domain_id` 和 `domain` 都为 `null` 的记录，会让该地址退出所有域名。`POST` 是幂等的：已有的记录会原样返回。相同的调用也以 MCP 工具 `list_unsubscribes`、`add_unsubscribe` 和 `delete_unsubscribe` 的形式提供。

各操作的作用范围：

- 带 `unsubscribed: false` 的 `PATCH /contacts/{id}` 只解除整个团队的退订。针对具体域名的退订保持不变。
- `DELETE /unsubscribes/{id}` 只移除那一条记录。

如果你删除一个域名，之后用同一个名称重新添加，它的收件人的退订会重新生效。

### 谁可以修改

所有者、管理员和营销成员，以及完全访问权限的 API 密钥，可以记录退订。只有所有者和管理员可以撤销退订。参见 [团队角色](/docs/zh-hans/team-roles)。

限定在某一个域名的 API 密钥只能管理该域名的退订：其他域名返回 `403 restricted_api_key`。

## 从 CSV 导入名单

要迁移其他服务商的退订名单，请在控制台中打开 **联系人 → 退订**，选择 **导入 CSV**。

```csv
email,domain
ada@example.com,
grace@example.com,news.example.org
alan@example.com,*
```

- `email` 必填。`domain` 可选。表头行也是可选的。
- `domain` 是你的某个域名，把退订限定在从它发出的邮件。`*` 表示所有域名。空单元格会使用你在对话框中选择的 **默认域名**。
- 域名未知或地址无效的行会被跳过。

对话框会显示新增了多少条退订、已有多少条，以及行被跳过的原因。同一个文件导入两次是安全的。

## 事件

收件人退订时会触发 `contact.unsubscribed`，其中 `source` 为 `hosted_page` 或 `one_click`，并带有 `domain_id` 和 `domain_name`（整个团队退订时两者都为 `null`）。撤销退订会触发 `contact.resubscribed`。参见 [Webhook](/docs/zh-hans/concepts/webhooks)。

## 限制

| | Free | Starter、Pro、Scale |
| --- | --- | --- |
| 退订页面外观（Logo、颜色、字体、Logo 圆角） | 默认外观 | 每个域名使用你自己的外观 |
| 自有退订子域名 | 不可用（使用共享主机） | 可用 |
| 页面上的「Powered by BillionSend」 | 显示 | 隐藏 |

在 Free 套餐上设置子域名会返回 `403 plan_limit_reached`。你可以保存页面外观，但在升级之前，收件人看到的仍是默认外观。降级后，已保存的外观会保留，升级后重新生效，已经设置的子域名继续可用。
