# Unsubscribe & preferences pages (/guides/unsubscribe-pages)

Whenever Bitelio sends an email that a recipient is allowed to unsubscribe from (marketing or headless templates), it embeds a personalized link to a hosted subscription-management page. There's nothing for you to build: hosting the pages, applying the state changes, and recording the events are all handled by Bitelio.

## The three URL variables

On every send, three template variables are injected automatically, each resolving to a signed URL unique to that recipient:

| Variable             | Page it links to           | What the recipient can do                                   |
| -------------------- | -------------------------- | ----------------------------------------------------------- |
| `{{unsubscribeUrl}}` | One-click unsubscribe page | Confirm they want to stop receiving marketing emails        |
| `{{subscribeUrl}}`   | Resubscribe page           | Opt back in after previously unsubscribing                  |
| `{{manageUrl}}`      | Preferences page           | View their current state and toggle subscription either way |

They can appear anywhere in a template's body or subject. At render time, each placeholder becomes a URL specific to that contact.

## Default behaviour by template type

The template type determines whether Bitelio adds these links for you:

| Template type     | Auto footer with `{{unsubscribeUrl}}`?   | Notes                                                                                                                  |
| ----------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **Marketing**     | Yes — Bitelio appends a localized footer | Nothing required on your end. The footer follows the recipient's `locale`.                                             |
| **Headless**      | No                                       | Include `{{unsubscribeUrl}}` (or `{{manageUrl}}`) in the body yourself — otherwise recipients have no way to opt out.  |
| **Transactional** | No                                       | Subscription checks don't apply to transactional email, so no unsubscribe link is injected (nor should one be needed). |

Marketing templates with a hand-built footer can either keep relying on the auto-injected one, or replace it by placing their own `{{unsubscribeUrl}}` link.

## Inside transactional sends

The same variables work in `/v1/send` requests. Whether a footer gets appended comes down to which template the send references:

* No template at all (just `subject` + `body`) → no auto footer.
* A marketing template → footer auto-injected.
* A headless or transactional template → no footer; the body is entirely yours.

And in any inline body, you're free to reference `{{unsubscribeUrl}}` / `{{manageUrl}}` to render a link of your own.

## What happens when the recipient acts

Clicking one of the links and confirming has these effects:

| Action                 | Effect                                                                       |
| ---------------------- | ---------------------------------------------------------------------------- |
| Unsubscribe            | Contact's `subscribed` flips to `false`. `contact.unsubscribed` event fires. |
| Resubscribe            | Contact's `subscribed` flips to `true`. `contact.subscribed` event fires.    |
| Update via preferences | Same as above, depending on which way they toggle.                           |

Those `contact.unsubscribed` / `contact.subscribed` events make good workflow triggers — a "sorry to see you go" survey on the way out, or a winback sequence when someone opts back in.

## Localization

Both the hosted pages and the auto-appended footer render in the contact's `locale` when one is set, falling back to the project's default language otherwise. The supported languages are listed in the [Localization](/guides/localization) guide.

## Branding

Your project's name and logo (set under **Settings → Project**) appear on the pages. If you want deeper control, send your marketing through **headless** templates and put the unsubscribe experience inside your own product — wiring your in-product controls to the same `{{unsubscribeUrl}}` keeps one-click revocation intact.

## API reference

When subscription changes should happen through code instead of the hosted pages — say you've built your own preferences screen — the contacts API covers it:

* `PATCH /contacts/:id` with `{ "subscribed": false }` — unsubscribe a contact.
* `PATCH /contacts/:id` with `{ "subscribed": true }` — resubscribe.

Either change fires the matching `contact.subscribed` / `contact.unsubscribed` event automatically, exactly as the hosted pages would.