# Branded Unsubscribe Subdomain Guide

This guide explains how to serve your public unsubscribe page on a **branded URL** — either a Last Chance subdomain (for example `https://your-brand.yourlastchance.app/unsub`) or your own custom domain (for example `https://unsubscribe.yourbrand.com/unsub`) — instead of the shared app URL with `teamId` in the query string.

## Overview

Branded URLs give each paid team a dedicated hostname for public unsubscribe traffic:

| Before (shared URL)                                     | After (branded URL)                           |
| ------------------------------------------------------- | --------------------------------------------- |
| `https://www.yourlastchance.app/unsub?email=…&teamId=…` | `https://your-brand.yourlastchance.app/unsub` |

After a subscriber validates (or when using a session cookie from a prior visit), the browser address bar stays **clean** — `email` and `teamId` are not required in the URL. Last Chance identifies your team from the hostname and stores the subscriber in an encrypted session cookie.

### What changes automatically

When a branded URL is active, Last Chance uses it in:

- **Page preview** (editor and versions) — opens your branded host, then lands on a clean `/unsub` URL
- **Klaviyo unsubscribe hosted page HTML** — redirect script targets your branded base URL (Settings → Email Providers → Klaviyo)
- **Public unsubscribe page** — production links can omit `teamId` when opened on your branded host

The main dashboard at [https://www.yourlastchance.app](https://www.yourlastchance.app) is unchanged. Only the public unsubscribe experience is served on your branded host.

---

## Requirements

- **Active paid subscription** — You need full access before claiming any branded hostname
- **Scale plan or higher** — Platform subdomain (`your-brand.yourlastchance.app`) requires the Scale plan ($99/mo) or above. Growth plans continue using the shared Last Chance URL with `teamId` in the link
- **Advanced plan or higher (custom domain)** — Your own hostname (for example `unsubscribe.yourbrand.com`) requires the Advanced plan ($199/mo) or above, when custom domains are enabled for your environment
- **Published unsubscribe page** — Subscribers must have a live page to land on
- **Platform subdomain** — No DNS setup on your side; choose a slug in the app (Scale+)
- **Custom domain (optional)** — Add the DNS records shown in **Account** after you enter your hostname (Advanced+)

If you downgrade below the required plan, existing branded hostnames keep working until you remove them; new claims or hostname changes require upgrading again.

---

## Platform subdomain

1. Sign in to Last Chance and open **Account** in the sidebar
2. Open the **Branded unsubscribe subdomain** section
3. Enter a slug (lowercase letters, numbers, hyphens; 3–63 characters)
4. Click **Save subdomain**

You will see your **live unsubscribe link** (for example `https://your-brand.yourlastchance.app/unsub`) when the subdomain is saved.

### Slug rules

- At least 3 characters, at most 63
- Lowercase letters, numbers, and hyphens only
- Cannot start or end with a hyphen
- Reserved names (for example `www`, `api`, `unsub`, `dashboard`) are blocked
- Slugs already used by another team return “This subdomain is already taken”

### Remove a subdomain

Click **Remove** in the same section. Public links revert to the shared app URL with `teamId` in query parameters.

---

## Custom domain (optional)

On **Advanced** plan and above (when custom domains are enabled), you can use a hostname you control (for example `unsubscribe.yourbrand.com`):

1. In **Account → Branded unsubscribe subdomain**, enter your hostname under **Custom domain** and click **Save custom domain**
2. Add the **DNS records** shown in the app at your domain registrar
3. Wait for verification — status updates automatically in the app (usually within a few minutes after DNS propagates)

When both a subdomain and custom domain are active, choose **Default link for Klaviyo & previews** to control which URL Last Chance uses in hosted-page HTML and editor preview.

---

## How subscribers reach your page

### Recommended: Klaviyo unsubscribe hosted page

Keep using the [Klaviyo unsubscribe hosted page setup](./klaviyo-hosted-page-setup.md). New HTML you copy from Last Chance uses your **branded base URL** in the `script src`.

### If you already pasted hosted page HTML before adding a branded URL

Klaviyo stores the HTML you pasted—it does not update automatically when you save a subdomain or custom domain in Last Chance.

1. Open **Settings → Email Providers → Klaviyo** in Last Chance and click **Copy Code** (unsubscribe and preference-center pages if you use both).
2. In [Klaviyo Hosted Pages](https://www.klaviyo.com/settings/other/hosted-pages), edit each Last Chance hosted page and replace the HTML.
3. You do **not** need to change which page is selected in Klaviyo consent settings—only the HTML content.

The redirect script sends subscribers to whatever origin is in the `script src` line. Old HTML pointing at `www.yourlastchance.app` keeps using the shared URL with `teamId` until you update it.

Flow (after hosted page HTML uses your branded `script src`):

```
Subscriber clicks Unsubscribe in email
  → Klaviyo consent / hosted page
  → Last Chance redirect script (your branded host)
  → Brief validation (sets a secure session)
  → https://your-brand.yourlastchance.app/unsub  (clean URL)
```

### Direct links and testing

You can still open the page with `email` (and optionally `teamId` on the shared host) in the query string. On a **valid** branded host, `teamId` in the URL is optional because the hostname identifies your team.

For a quick test without an email campaign:

1. Use **Preview** in the page editor with a test email
2. Or visit your branded URL with `email` once; after validation, refresh `/unsub` without query params

---

## Security: Klaviyo ID validation

When a branded URL is active, Last Chance recommends enabling **Require Klaviyo ID validation** on your unsubscribe page.

On a dedicated hostname, knowing someone’s email address can be enough to open their unsubscribe experience unless Klaviyo ID validation is enabled. With validation on, links must include a valid Klaviyo profile ID (typical for links from Klaviyo emails and hosted-page redirects).

Enable it in the page editor under page settings if you use a branded URL in production.

---

## Clean URLs and preview mode

### Production visits

1. Subscriber arrives with `email` (and optionally tracking params) in the URL or via the redirect from Klaviyo
2. Last Chance confirms the address, stores it in an encrypted cookie, and redirects to `/unsub` **without** `email` or `teamId`
3. `/unsub` uses the cookie and hostname to load the correct page

### Preview from the dashboard

Preview validates a test email on your branded host, then opens a clean URL such as:

`https://your-brand.yourlastchance.app/unsub?preview=1&version=2&unsubscribePageId=…`

Draft preview still requires a test email in the preview dialog; preview mode does not call Klaviyo for live profile updates.

### Share preview link (design approval)

Use **Copy share link** in the preview dialog to get a public URL you can send to stakeholders (Slack, email, etc.). Recipients open the link with **no login and no test email** — it works indefinitely until the page or version is removed.

The share URL looks like:

`https://your-brand.yourlastchance.app/api/unsub/share-preview?t=…`

Opening it loads the draft in preview mode (no Klaviyo writes, no analytics).

---

## Troubleshooting

| Issue                              | What to check                                                                                                                             |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Save subdomain disabled**        | Confirm you have an active paid subscription on the Account page                                                                          |
| **“Subdomain already taken”**      | Pick a different slug; slugs are global across teams                                                                                      |
| **Branded URL does not load**      | Typo in slug or hostname; wait a few minutes after saving. If the problem persists, [contact support](mailto:support@yourlastchance.app). |
| **Custom domain stuck on Pending** | Confirm DNS records match exactly what Account shows; propagation can take up to 48 hours                                                 |
| **Page Not Found on branded host** | Typo in slug, domain removed, or page not published; an unknown hostname shows the same 404 as a missing page                             |
| **Still seeing `teamId` in links** | Branded URL not saved, or link built against the shared app URL — re-copy Klaviyo hosted page HTML after activating branding              |
| **Preview opens wrong host**       | Refresh the Account page; preview uses your current default branded URL                                                                   |

---

## Related guides

- [Billing & Account](./billing-account.md) — Subscription required for branded URLs
- [Klaviyo Unsubscribe Hosted Page Setup](./klaviyo-hosted-page-setup.md) — Redirects use your branded URL when configured
- [Klaviyo email links & consent](./klaviyo-email-links-and-consent-pages.md) — How unsubscribe clicks reach hosted pages
- [Subscriber Experience](./subscriber-experience.md) — What subscribers see on your page