> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理退订用户

> 按渠道记录并执行客户退订。

## 功能简介

退订记录表明客户已选择退订您企业在特定渠道上的消息。客户和渠道共同构成唯一记录。

## 开始之前

* 确定您的产品如何收集和记录同意信息。
* 将电话号码规范化为 E.164 格式。
* 选择正确的客户标识符类型和渠道。
* 确定退订如何与您的源系统同步。

## 工作原理

1. 当客户退订时创建退订记录。
2. 在发送前检查或列出记录（如果您的工作流尚未
   强制执行拦截抑制）。
3. 仅在客户有效重新订阅（Opt-in）时删除记录。
4. 处理退订 Webhook 事件以同步外部系统。

不要将删除记录视为自动获得同意的证明。您的应用程序必须保留重新订阅的证据和政策依据。

## 请求

### 创建退订用户

`POST /unsubscribers`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/unsubscribers \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "PHONE_NUMBER",
    "customer": "+16315551111",
    "channel": "whatsapp",
    "regionCode": "US"
  }'
```

### 在重新订阅后移除退订记录

`DELETE /unsubscribers/{customer}/{channel}`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request DELETE \
  https://api.ycloud.com/v2/unsubscribers/+16315551111/whatsapp \
  --header "X-API-Key: $YCLOUD_API_KEY"
```

当您的 HTTP 客户端需要时，对客户路径值进行 URL 编码。

## 响应

创建成功会返回已保存的记录。

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "PHONE_NUMBER",
  "customer": "+16315551111",
  "channel": "whatsapp",
  "regionCode": "US"
}
```

获取和删除会返回匹配的退订资源。不存在的记录会返回错误，而不是退订状态。

## 执行规则

将拦截抑制视为安全边界。在批量发送、政策要求的事务性工作流、重试以及手动操作中一致应用它。

使用 Webhook 事件同步新的退订记录和已删除的退订记录。

## 限制与问题排查

* 同一客户可以针对不同渠道拥有独立的记录。
* 为客户标识符使用正确的 `type`。
* 在没有有效重新订阅事件的情况下，请勿静默删除记录。
* 列表端点支持游标分页；请遵循 `cursor.after`。
* 设计并发订阅与退订处理，使最新的有效客户
  决定生效。

<CardGroup cols={2}>
  <Card title="创建退订用户" icon="user-slash" href="/api-reference/unsubscribers/create-an-unsubscriber">
    检查受支持的标识符类型和渠道。
  </Card>

  <Card title="退订 Webhooks" icon="webhook" href="/zh/api-reference/guides/examples/webhook-examples/contact-unsubscribe-created-webhook-examples">
    同步退订和重新订阅事件。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.