Unsubscribe & preferences pages
The hosted pages Bitelio provides so recipients can opt out, opt back in, and manage their subscription
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 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/:idwith{ "subscribed": false }— unsubscribe a contact.PATCH /contacts/:idwith{ "subscribed": true }— resubscribe.
Either change fires the matching contact.subscribed / contact.unsubscribed event automatically, exactly as the hosted pages would.