---
title: Unsubscribes and brands
description: Opt-outs are kept per sending domain, so each brand has its own list, its own unsubscribe page and its own link host.
---

An unsubscribe means "no more marketing mail". BillionSend records it for the sending domain whose email carried the link, so a team with several brands never mixes their lists. Someone who leaves one brand still hears from the others.

Transactional email (mail sent without a [topic](/docs/concepts/topics) and outside a [broadcast](/docs/concepts/broadcasts)) is never affected by an unsubscribe.

## Three scopes

| Scope | Who sets it | What it stops |
| --- | --- | --- |
| Domain | The recipient, with the unsubscribe link or their mail client's one-click button | Marketing mail from the domain that sent that email |
| Whole team | You, by setting a contact's `unsubscribed` to `true` (API, dashboard or CSV import) | Marketing mail from every domain of your team |
| Topic | The recipient, on the unsubscribe page | Mail sent with that [topic](/docs/concepts/topics) |

A recipient's own unsubscribe never changes the contact's `unsubscribed` flag. It is stored as a record for the domain, keyed by the email address, so it survives deleting and re-importing the contact.

Broadcasts and topic sends skip a recipient who has opted out of the sending domain, the whole team or the topic. A single email stopped this way ends `suppressed` with the reason `domain_unsubscribed`, `contact_unsubscribed` or `topic_unsubscribed`.

Unsubscribes are not [suppressions](/docs/concepts/suppressions). The suppression list holds addresses that bounced, complained or that you blocked, and it stops every email, transactional included. An unsubscribe stops marketing mail only.

## The unsubscribe page

Every broadcast and topic email carries one-click `List-Unsubscribe` headers (RFC 8058) and a link to a hosted unsubscribe page. Put `{{{UNSUBSCRIBE_URL}}}` in a body and it becomes the same link for each recipient. The page opens in the recipient's browser language (fourteen languages, English as the fallback). Besides leaving all marketing mail from the domain, the recipient can switch individual topics on and off.

A recipient who clicked by mistake can press **Resubscribe** on the confirmation page. It undoes only what that link opted them out of. A mail scanner that opens the link never re-subscribes anyone. When you set `unsubscribed: true` yourself, the page has no Resubscribe button.

### Each domain has its own look

The page looks like the domain that sent the email. Each domain can set:

- a brand name, a logo and the logo's corner radius,
- background, text and accent colors,
- the text above the button and the text shown after the choice is saved,
- a redirect URL to open after unsubscribing, instead of the message on the page.

In the dashboard, open the domain and use the **Unsubscribe page** tab, which previews the result. A field you leave empty falls back to the team's **Brand defaults** (Settings), then to BillionSend's plain look. The page shows only what belongs to that domain: it never names another domain of your team, and it lists only the topics bound to that domain plus the topics with no domain.

Through the API, send the fields in `unsubscribe_page` on `PATCH /domains/{id}`. A `null` clears a field. The logo is uploaded in the dashboard and is read only in the API.

```sh
curl -X PATCH "https://api.billionsend.com/domains/$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "unsubscribe_page": {
      "brand_name": "Acme",
      "message": "Sorry to see you go. Unsubscribe from Acme emails?",
      "success_message": "You are unsubscribed from Acme.",
      "accent_color": "#0a7d5a",
      "logo_radius": "rounded"
    }
  }'
```

A link made outside an email, such as the one from `POST /contacts/{id}/preferences-link`, opens the team's default page, and unsubscribing there opts the contact out of every domain.

### Your own unsubscribe subdomain

By default, links open on a BillionSend host. To open them on your own domain, give the domain an unsubscribe subdomain in its Configuration tab, or with `unsubscribe_subdomain` on `POST /domains` or `PATCH /domains/{id}` (a label such as `unsubscribe` for `unsubscribe.yourdomain.com`; `null` clears it). It works like the tracking subdomain, see [Domains](/docs/concepts/domains).

1. Add the CNAME that the domain's Records tab shows, pointing at `cname.billiondns.com`, as DNS only (grey cloud on Cloudflare).
2. The certificate is issued automatically once the CNAME resolves, usually within minutes. `unsubscribe_status` moves from `pending` to `active`, and `unsubscribe_error` says why when it does not.
3. New mail then uses your host in the link and in the `List-Unsubscribe` header. Until it is active, and after a `failed` result (72 hours without activating), the shared host is used.

A link already sent keeps the host it was sent with, so it stops working if you later remove the CNAME. A subdomain of yours opens only the links of its own domain; any other link answers `404`.

You can use one label for both tracking and unsubscribe, but separate names are safer: ad blockers block tracking hosts, and a shared name would take the unsubscribe link down with them.

## Read and change unsubscribes

`GET /contacts/{id}` returns `unsubscribed` (the team-wide flag) and `unsubscribed_domains`. In the dashboard, a contact's page lists both and lets you remove a domain's opt-out. The **Unsubscribes** tab under Audience lists every record.

```sh
# List, newest first. domain_id narrows to one domain.
curl "https://api.billionsend.com/unsubscribes?domain_id=$DOMAIN_ID" \
  -H "Authorization: Bearer bs_..."

# Record an opt-out from one domain (leave domain_id out for every domain)
curl -X POST "https://api.billionsend.com/unsubscribes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.org", "domain_id": "'"$DOMAIN_ID"'" }'

# Remove one record
curl -X DELETE "https://api.billionsend.com/unsubscribes/$UNSUBSCRIBE_ID" \
  -H "Authorization: Bearer bs_..."
```

A record with `domain_id` and `domain` both `null` opts the address out of every domain. The `POST` is idempotent: an existing record comes back unchanged. The same calls exist as the `list_unsubscribes`, `add_unsubscribe` and `delete_unsubscribe` MCP tools.

What lifts what:

- `PATCH /contacts/{id}` with `unsubscribed: false` lifts the team-wide opt-out only. Opt-outs from specific domains stay.
- `DELETE /unsubscribes/{id}` removes that one record.

If you delete a domain and add it again under the same name, its recipients' opt-outs apply again.

### Who may change them

Owners, admins and marketing members, and full-access API keys, can record unsubscribes. Only owners and admins can take one back. See [Team roles](/docs/team-roles).

An API key limited to one domain manages only that domain's unsubscribes: other domains return `403 restricted_api_key`.

## Import a list from CSV

To bring over an opt-out list from another provider, open **Audience → Unsubscribes** in the dashboard and choose **Import CSV**.

```csv
email,domain
ada@example.com,
grace@example.com,news.example.org
alan@example.com,*
```

- `email` is required. `domain` is optional. A header row is optional too.
- `domain` is one of your domains and limits the opt-out to mail from it. `*` means every domain. An empty cell uses the **Default domain** you pick in the dialog.
- A row with an unknown domain or an invalid address is skipped.

The dialog shows how many opt-outs were added, how many already existed and why rows were skipped. Importing the same file twice is safe.

## Events

A recipient's unsubscribe fires `contact.unsubscribed` with `source` set to `hosted_page` or `one_click`, plus `domain_id` and `domain_name` (both `null` for a whole-team opt-out). Taking it back fires `contact.resubscribed`. See [Webhooks](/docs/concepts/webhooks).

## Limits

| | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Unsubscribe page look (logo, colors, font, logo radius) | Default look | Your own look per domain |
| Own unsubscribe subdomain | No (shared host) | Yes |
| "Powered by BillionSend" on the page | Shown | Hidden |

On Free, setting a subdomain returns `403 plan_limit_reached`. You can save a page look, but recipients see the default look until you upgrade. After a downgrade, saved looks are kept and apply again when you upgrade, and subdomains you already set keep working.
