> ## 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.

# Manage unsubscribers

> Record and enforce customer opt-outs by channel.

## What it is

An unsubscriber record indicates that a customer opted out of messages from
your business on a specific channel. The customer and channel together form
the unique record.

## Before you begin

* Define how your product collects and records consent.
* Normalize phone numbers to E.164 format.
* Choose the correct customer identifier type and channel.
* Decide how opt-outs synchronize with your source systems.

## How it works

1. Create an unsubscriber when a customer opts out.
2. Check or list records before sending when your workflow does not already
   enforce suppression.
3. Delete the record only when the customer validly opts back in.
4. Process unsubscribe webhook events to synchronize external systems.

Do not interpret deletion as automatic proof of consent. Your application must
retain the evidence and policy basis for resubscription.

## Request

### Create an unsubscriber

`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"
  }'
```

### Remove an unsubscriber after opt-in

`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"
```

URL-encode the customer path value when required by your HTTP client.

## Response

Creation returns the saved record.

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

Retrieval and deletion return the matching unsubscriber resource. A missing
record returns an error rather than an opted-out state.

## Enforcement

Treat suppression as a safety boundary. Apply it consistently across bulk
sends, transactional workflows where policy requires it, retries, and manual
operations.

Use Webhook events to synchronize new opt-outs and deleted opt-out records.

## Limits and troubleshooting

* The same customer can have separate records for different channels.
* Use the correct `type` for the customer identifier.
* Do not silently delete a record without a valid opt-in event.
* List endpoints support cursor pagination; follow `cursor.after`.
* Design concurrent opt-in and opt-out processing so the newest valid customer
  decision wins.

<CardGroup cols={2}>
  <Card title="Create an unsubscriber" icon="user-slash" href="/api-reference/unsubscribers/create-an-unsubscriber">
    Inspect supported identifier types and channels.
  </Card>

  <Card title="Unsubscribe webhooks" icon="webhook" href="/en/api-reference/guides/examples/webhook-examples/contact-unsubscribe-created-webhook-examples">
    Synchronize opt-out and resubscribe events.
  </Card>
</CardGroup>


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