# Unsubscribe a customer with the API

> POST /api/v0/unsubscribe with your secret key opts a customer out of marketing messages by email address or phone number. Fields, curl, the External mode flow, response, errors and limits.

`POST https://releva.ai/api/v0/unsubscribe` opts one customer out of marketing messages in your shop. It records the opt-out and removes the subscriptions the customer could see.

## When to use it

* **Your shop manages consent (External mode).** When a customer lands on your unsubscribe page, mark them unsubscribed in your shop and call this endpoint. See [External mode](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/#external-mode).
* **A customer opts out somewhere else in your system**, for example in their account settings or through your support team. Call it so Releva stops sending too.

You do not need it for links that Releva renders in **Internal** mode: those unsubscribe the customer themselves (see [Unsubscribe links and one-click unsubscribe](https://releva.ai/documentation/reference/consent/unsubscribe-links-and-one-click/)). To remove a single subscription without opting the customer out, use [Subscribe a customer from your server](https://releva.ai/documentation/reference/consent/subscribe-a-customer/) with `removeSubscriptions`.

**Never call it from a browser or an app.** It needs your secret key.

## Authentication

Send your shop’s **secret key** as a bearer token:

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

Find it under **Settings › Shop & Integration**; see [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

Authentication failures answer `400`, not `401`:

| Problem                                                                | Message                                                                       |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| No `authorization` header                                              | `Authorization header is missing.`                                            |
| The header is not `Bearer` followed by a token                         | ``Authorization header is malformed. It should look like `Bearer <string>`.`` |
| The token is not a UUID                                                | `Authorization header contains an invalid Bearer token.`                      |
| No shop has this secret key (also when you send the access token here) | `Domain with the provided secret key cannot be found.`                        |

A shop that is switched off answers `402` with `Domain is disabled. Please reach out to support@releva.ai to enable it.`

## Request

`POST /api/v0/unsubscribe` with `content-type: application/json`. Send `email`, `phoneNumber` or both.

| Field          | Type   | Required                      | Notes                                                                                                                                                                                                                                                                  |
| -------------- | ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`        | string | One of `email`, `phoneNumber` | The customer’s email address.                                                                                                                                                                                                                                          |
| `phoneNumber`  | string | One of `email`, `phoneNumber` | International format with a leading `+` and digits only, for example `+15555550199`. A number without `+` gets your shop country’s dialling code added before it is checked.                                                                                           |
| `attributions` | object | No                            | Links the opt-out to a message: `emailId`, `campaignId`, `textMessageId`, `viberMessageId`, `whatsappMessageId`, all strings. When `campaignId` is one of your shop’s campaigns, the `unsubscribe` event is tagged with that campaign’s mode, for example `triggered`. |

No other field is allowed: an unknown field answers `400`.

By email address:

```plaintext
curl -X POST 'https://releva.ai/api/v0/unsubscribe' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{ "email": "maria@example.com" }'
```

By phone number:

```plaintext
curl -X POST 'https://releva.ai/api/v0/unsubscribe' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{ "phoneNumber": "+15555550199" }'
```

When you send both, Releva opts out the profile it finds by the email address and the profile it finds by the phone number.

## Response

`202` with the body `{}`. The profile has been written when the response arrives.

What changed on the profile:

* The customer is unsubscribed. **Opt-in Marketing** and **Opt-out Marketing** campaigns on email, SMS, Viber, WhatsApp and webhooks stop reaching them; **Transactional** campaigns still do.
* Your shop’s user-visible subscriptions are removed from the profile. Subscriptions that you set only through the API and never made visible stay. The `marketing` subscription is always removed, even if your shop does not show it.
* An `unsubscribe` event is recorded.
* **An email address or phone number that Releva does not know creates a new, unsubscribed profile.** A later import or subscribe of that address starts from an opt-out.

## External mode

When **Subscription Management** in **Settings › Messaging** is **External**, your shop owns consent and Releva links to your unsubscribe page instead of its own:

* The customer’s own link, if your integration sent an absolute `unsubscribeLink` for them (through `POST /api/v0/subscribe` or `POST /api/v0/profiles`). Releva uses it as it is.
* Otherwise the **Email Unsubscribe URL** from **Settings › Messaging**, with `encodedEmail` (the email address, base64-encoded), `encodedPhoneNumber` (the phone number, base64-encoded, when the profile has one) and `url` (your shop’s URL) added as query parameters.

Your page must:

1. Read the customer from the link: decode `encodedEmail` or `encodedPhoneNumber` from base64, or use your own per-customer link.
2. Mark the customer unsubscribed in your shop.
3. Call `POST /api/v0/unsubscribe` with the email address or phone number.

If you leave **Email Unsubscribe URL** empty, profiles without their own link are skipped by **Opt-in Marketing** and **Opt-out Marketing** campaigns, because their messages could not carry a link that identifies them. **Transactional** campaigns still reach them, with your shop’s URL as the link. Shops connected to Klaviyo are not affected, because Klaviyo adds its own unsubscribe link.

## Errors

Errors have the shape `{ "message": "..." }`. When several fields fail, the messages are joined with a space.

| Status | When                                        | Message                                                                                                           |
| ------ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `400`  | Authentication failed                       | See [Authentication](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/#authentication)                                                                             |
| `400`  | `{}` (neither `email` nor `phoneNumber`)    | `At least one of (email, phoneNumber) is required.`                                                               |
| `400`  | An extra field, for example `subscriptions` | `The object '' contains forbidden keys: 'subscriptions'.`                                                         |
| `400`  | `"email": "not-an-email"`                   | `The 'email' field must be a valid e-mail.`                                                                       |
| `400`  | `"phoneNumber": "12ab"`                     | `phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got 12ab instead.` |
| `402`  | The shop is switched off                    | See [Authentication](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/#authentication)                                                                             |
| `413`  | The body is larger than 800 KB              | `request entity too large`                                                                                        |

## Limits

* HTTPS only. A plain HTTP request answers `400` with `We do not support non-HTTPS requests.`
* Body size: 800 KB.
* Rate limits: none on this endpoint.
* One customer per request.

## Next steps

* [Unsubscribe links and one-click unsubscribe](https://releva.ai/documentation/reference/consent/unsubscribe-links-and-one-click/): See which unsubscribe links Releva puts in each message and what they do.
* [Subscribe a customer from your server](https://releva.ai/documentation/reference/consent/subscribe-a-customer/): Subscribe the customer again, or remove a single subscription without an opt-out.
* [Unsubscribe a customer from marketing messages](https://releva.ai/documentation/guides/consent/unsubscribe-a-customer/): Opt out one profile from the admin instead of the API.