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

# Custom Unsubscribe Page

> Host your own unsubscribe page, with your design and your own questions

You can send subscribers to an unsubscribe page on your own site instead of the
Sequenzy preferences page. You control the design and can ask anything you want
before they leave, such as why they are unsubscribing.

This works for marketing emails where you write the unsubscribe link yourself:

* Campaigns and sequence emails built in the editor: add the link in an HTML
  block, and turn off **Show unsubscribe** in the footer block if you have one.
* Campaigns created through the API with `html`.
* Emails sent through the [send endpoint](https://docs.sequenzy.com/api-reference/transactional/send.md)
  with `emailType` set to `marketing`. Transactional sends have no Sequenzy
  unsubscribe link, so `{{unsubscribeUrl}}` is empty there.

## 1. Link to your page

Add a link to your page in your email. Include two values in the link:

* A value that identifies the recipient, so your page knows who clicked. Use a
  signed token you store as a custom attribute, such as
  `{{subscriber.unsubscribe_token}}`. Avoid the plain email address: anyone
  could change it in the URL and unsubscribe someone else. Use only letters,
  numbers, `-` and `_` in the token, because the value is not URL-encoded. If
  a subscriber has no such attribute, the value is empty.
* `{{unsubscribeUrl}}`. This tells Sequenzy your email already has an
  unsubscribe link, so it does not add its own unsubscribe footer.

```html theme={null}
<a
  href="https://example.com/unsubscribe?member={{subscriber.unsubscribe_token}}&sequenzy={{unsubscribeUrl}}"
  >Unsubscribe</a
>
```

When the email is sent, each recipient gets their own values:

```text theme={null}
https://example.com/unsubscribe?member=tok_8f2c&sequenzy=https://sequenzylink.com/unsubscribe/eyJ...
```

The `sequenzy` value is the recipient's Sequenzy unsubscribe link. Your page
does not need to use it. You can use it as a fallback by redirecting there if
your own page cannot complete the request.

> [!WARNING]
>
> Write `{{unsubscribeUrl}}` exactly like this, inside the `href` of a link. If
> your email has no such link, Sequenzy appends its own unsubscribe footer, and
> the email has two unsubscribe links.

## 2. Unsubscribe the subscriber from your server

When the subscriber submits your form, look up their email from your token and
call [Update Subscriber](https://docs.sequenzy.com/api-reference/subscribers/update.md) with `status` set
to `unsubscribed`. The API key needs the `subscribers:write` scope.

```bash theme={null}
curl -X PATCH "https://api.sequenzy.com/api/v1/subscribers/jane%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "unsubscribed",
    "customAttributesStrategy": "merge",
    "customAttributes": {
      "unsubscribe_reason": "too_many_emails"
    }
  }'
```

This unsubscribes the subscriber from everything, like the Sequenzy page: they
leave their lists and their active sequences stop.

To keep the answers to your questions in Sequenzy, send them as
`customAttributes` in the same request, as shown above. Keep
`customAttributesStrategy` set to `merge`. Without it, the answers replace the
subscriber's other custom attributes.

Unsubscribes made through the API are not linked to the email they came from,
so they do not appear in that email's unsubscribe stats.

Make this call from your server. Never put your API key in the page itself.

## Unsubscribes that skip your page

Gmail, Yahoo, Apple Mail and other inbox providers show their own unsubscribe
button next to the sender name. It unsubscribes in one click through the
`List-Unsubscribe` header on marketing emails. Sequenzy always sets this header
to its own one-click link, and you cannot change it, so those subscribers never
see your page.

To keep your own records in sync, listen for the `subscriber.unsubscribed`
[webhook event](https://docs.sequenzy.com/integrations/outbound-webhooks.md#events). It fires whenever a
subscriber becomes unsubscribed, including through the inbox button, the
Sequenzy page and your API call.


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