---
title: 订阅主题
description: 订阅分类让收件人只退出某一类邮件，继续接收其余邮件。订阅主题可以绑定到某一个发信域名。
seo:
  title: 邮件订阅主题
ai:
  exclude: true
---

订阅主题是邮件的一个类别，例如「产品更新」「新闻简报」或「促销活动」。收件人可以只退出其中一个主题，继续订阅其余的。在控制台的 **联系人 → 订阅主题** 中管理订阅主题，也可以通过 API 管理。

每个订阅主题都有 `default_subscription`，创建时设置，之后不能更改：

- `opt_in`：所有联系人都已订阅，除非他们主动退出。
- `opt_out`：联系人只有主动加入后才算订阅。

订阅主题还有 `visibility`。`public` 主题会列在退订页面上，`private` 主题只能通过它自己的链接出现。

## 订阅主题如何生效

- **群发。** 群发可以指定一个订阅主题，邮件会发给订阅了该主题的联系人（按联系人自己的选择，或该主题的默认值）。对整个团队退订的联系人，以及已退出该发信域名的联系人，始终会被排除。
- **单封邮件。** 发送邮件时带上 `topic_id`，就会遵循该订阅主题。如果 `to` 中的所有地址都已退出，发送会返回 `422 all_recipients_suppressed`。
- **退订页面。** 页面会列出公开的订阅主题，收件人可以关闭其中一个，或退出该域名发出的所有营销邮件。没有带 `topic_id` 且不属于群发的邮件永远不受影响。参见 [退订](/docs/zh-hans/concepts/unsubscribes)。

如果某个订阅主题正被群发使用，或被仍在等待发送的邮件使用，就不能删除：在这些邮件发出或取消之前，调用会返回 `409 conflict`。

```sh
curl -X POST "https://api.billionsend.com/topics" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product updates", "default_subscription": "opt_in" }'
```

用 `PATCH /contacts/{id}/topics` 设置联系人的选择，传入形如 `{ "id": "<topic-id>", "subscription": "opt_in" }` 的条目。`GET /contacts/{id}/topics` 列出所有订阅主题，并附上该联系人的 `subscription` 和 `explicit` 标记（使用订阅主题默认值时为 false）。

## 每个品牌一个订阅主题

如果你的每个域名都是一个独立品牌，可以通过设置 `domain_id`，把订阅主题绑定到它所属的域名：创建时设置，之后用 `PATCH /topics/{id}` 设置，或在控制台中选择域名。

- 已绑定的订阅主题只会列在该域名的退订页面上，其他域名的页面都不会显示它的名称。
- 使用该 `topic_id` 发送时，必须从该域名发出。从其他任何域名发送，`POST /emails` 和群发相关的调用都会返回 `422`。
- 没有绑定域名的订阅主题会列在所有域名的页面上，可以从任何域名发送。设置 `"domain_id": null` 可让已绑定的订阅主题重新成为团队通用。
- 只要还有订阅主题绑定在某个域名上，该域名就不能删除（`409`）。

[分群](/docs/zh-hans/concepts/segments) 也可以用同样的方式绑定。

## 限定域名的 API 密钥

限定在某一个域名的 API 密钥，只能创建绑定到该域名的订阅主题，不能创建团队通用的订阅主题。
