# 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`) or your own custom domain (for example `https://unsubscribe.yourbrand.com`) — 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` |

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 URL at the hostname root
- **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`) when the subdomain is saved. The `/unsub` path on that host still works.

### 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  (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 the hostname 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 your branded hostname **without** `email` or `teamId`
3. The page uses the cookie and hostname to load the correct experience. `/unsub` on that host still works.

### 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/?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