---
title: 訂閱主題
description: 訂閱類別：收件者可以只退訂其中一種信件，其餘仍維持訂閱。訂閱主題可綁定到單一寄件網域。
seo:
  title: Email 訂閱主題
ai:
  exclude: true
---

訂閱主題是信件的類別，例如「產品更新」、「電子報」或「促銷活動」。收件者可以退出其中一個主題，其餘仍維持訂閱。在控制台的**聯絡人 → 訂閱主題**管理，也可以透過 API 管理。

每個訂閱主題都有 `default_subscription`，在建立時設定，之後無法更改：

- `opt_in`：除非聯絡人選擇退出，否則每位聯絡人都已訂閱。
- `opt_out`：聯絡人要先選擇加入，才算訂閱。

訂閱主題也有 `visibility`。`public` 的主題會列在退訂頁面上，`private` 的主題則只會透過它自己的連結出現。

## 訂閱主題如何運作

- **群發。** 群發可以指定一個訂閱主題。它會寄給訂閱該主題的聯絡人（依其自己的選擇，或主題的預設值）。在團隊層級退訂，或已退訂該寄件網域的聯絡人，一律會被排除。
- **單封 Email。** 寄信時帶上 `topic_id`，就會遵守該主題。如果每個 `to` 位址都已退出，寄送會回傳 `422 all_recipients_suppressed`。
- **退訂頁面。** 頁面會列出公開的訂閱主題，收件者可以關閉其中一個，或退出該網域的所有行銷郵件。沒有帶 `topic_id` 且不屬於群發的信件，永遠不受影響。請見[退訂](/docs/zh-hant/concepts/unsubscribes)。

被群發使用的訂閱主題，或仍在等待寄出的 Email 使用過的主題，無法刪除：在那些信件寄出或取消之前，呼叫會回傳 `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-hant/concepts/segments)也可以用同樣的方式綁定。

## 限制在單一網域的 API 金鑰

限制在單一網域的 API 金鑰，只能建立綁定到該網域的訂閱主題，不能建立團隊層級的主題。
