退订与品牌
退订按发信域名记录,因此每个品牌都有自己的名单、自己的退订页面和自己的链接主机。
退订的意思是「不再接收营销邮件」。BillionSend 会把它记录在带有该链接的邮件所用的发信域名上,所以有多个品牌的团队不会把各品牌的名单混在一起。离开某一个品牌的人,仍会收到其他品牌的邮件。
事务邮件(不带 订阅主题 且不属于 群发 的邮件)永远不受退订影响。
三种范围
| 范围 | 由谁设置 | 阻止什么 |
|---|---|---|
| 域名 | 收件人,通过退订链接或邮件客户端的一键退订按钮 | 发出该邮件的域名的营销邮件 |
| 整个团队 | 你,把联系人的 unsubscribed 设为 true(API、控制台或 CSV 导入) |
你团队所有域名的营销邮件 |
| 订阅主题 | 收件人,在退订页面上 | 带有该 订阅主题 的邮件 |
收件人自己的退订永远不会改变联系人的 unsubscribed 标记。它会按邮箱地址作为键,存成该域名下的一条记录,所以即使联系人被删除后重新导入,它依然有效。
群发和订阅主题邮件会跳过已退出该发信域名、整个团队或该订阅主题的收件人。一封因此被拦截的单封邮件,最终状态为 suppressed,原因是 domain_unsubscribed、contact_unsubscribed 或 topic_unsubscribed。
退订不是 抑制。抑制列表保存曾退信、投诉或被你屏蔽的地址,它会阻止所有邮件,包括事务邮件。退订只阻止营销邮件。
退订页面
每封群发和订阅主题邮件都带有一键式 List-Unsubscribe 头(RFC 8058)和一个指向托管退订页面的链接。在正文中写 {{{UNSUBSCRIBE_URL}}},它就会为每位收件人变成同一个链接。页面按收件人浏览器的语言打开(14 种语言,回退为英文)。除了退出该域名的所有营销邮件,收件人还可以逐个开启或关闭订阅主题。
误点的收件人可以在确认页面点击 重新订阅。它只会撤销该链接所造成的退订。打开链接的邮件扫描器永远不会让任何人重新订阅。当你自己设置了 unsubscribed: true 时,页面上没有重新订阅按钮。
每个域名有自己的外观
页面的外观与发出邮件的域名一致。每个域名都可以设置:
- 品牌名称、Logo 和 Logo 的圆角;
- 背景色、文字颜色和强调色;
- 按钮上方的文字,以及保存选择后显示的文字;
- 退订后要打开的跳转 URL,用来代替页面上的提示信息。
在控制台中,打开域名并使用 品牌 标签页,它会预览效果。留空的字段会回退到团队的 品牌默认值(设置),再回退到 BillionSend 的朴素外观。页面只显示属于该域名的内容:它从不提及你团队的其他域名,只列出绑定到该域名的订阅主题,以及没有绑定域名的订阅主题。
通过 API,在 PATCH /domains/{id} 上用 unsubscribe_page 发送这些字段。null 会清除一个字段。Logo 在控制台中上传,在 API 中只读。
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 会清除它)。它的工作方式与追踪子域名相同,参见 域名。
- 添加域名的 DNS 标签页中显示的 CNAME,指向
cname.billiondns.com,并设为仅 DNS(Cloudflare 上是灰色云朵)。 - CNAME 解析生效后会自动签发证书,通常在几分钟内。
unsubscribe_status会从pending变为active,没有生效时unsubscribe_error会说明原因。 - 之后的新邮件会在链接和
List-Unsubscribe头中使用你的主机。在激活之前,以及出现failed结果(72 小时内仍未激活)之后,会使用共享主机。
已经发出的链接会一直使用发送时的主机,所以如果你之后移除 CNAME,它们就会失效。你的子域名只会打开它所属域名的链接,任何其他链接都返回 404。
追踪和退订可以共用同一个标签,但分开命名更安全:广告拦截器会拦截追踪主机,共用的名称会让退订链接一起被拦截。
读取与修改退订
GET /contacts/{id} 返回 unsubscribed(整个团队的标记)和 unsubscribed_domains。在控制台中,联系人页面会列出这两项,并允许你移除某个域名的退订。联系人 下的 退订 标签页列出所有记录。
# 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 密钥,可以记录退订。只有所有者和管理员可以撤销退订。参见 团队角色。
限定在某一个域名的 API 密钥只能管理该域名的退订:其他域名返回 403 restricted_api_key。
从 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。
限制
| Free | Starter、Pro、Scale | |
|---|---|---|
| 退订页面外观(Logo、颜色、字体、Logo 圆角) | 默认外观 | 每个域名使用你自己的外观 |
| 自有退订子域名 | 不可用(使用共享主机) | 可用 |
| 页面上的「Powered by BillionSend」 | 显示 | 隐藏 |
在 Free 套餐上设置子域名会返回 403 plan_limit_reached。你可以保存页面外观,但在升级之前,收件人看到的仍是默认外观。降级后,已保存的外观会保留,升级后重新生效,已经设置的子域名继续可用。