Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Unsubscribes and brands

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 and outside a broadcast) 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

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. 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.

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.

  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.

# 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.

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.

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.

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.

Was this page helpful?