Adding a compliant unsubscribe link to a HubSpot marketing email is straightforward on the surface: place {{ unsubscribe_link }} in the footer, and HubSpot handles the rest. In practice, HubSpot exposes three distinct unsubscribe mechanisms (default embedded, custom token placement, and account-wide global opt-out), plus a stricter one-click compliance path for Gmail and Yahoo bulk senders that most account owners misconfigure. This guide covers the exact setup for each mechanism, the UI paths, the RFC 8058 status, and the common issues that break unsubscribe flows in production.
HubSpot unsubscribe link: quick reference
| Item | Value |
|---|---|
| Per-subscription tag | {{ unsubscribe_link }} |
| Account-wide tag | {{ unsubscribe_link_all }} |
| Default placement | Auto-embedded in every marketing email footer |
| Config path | Marketing > Email > Settings > Subscription types |
| RFC 8058 one-click | Yes, generated automatically for Marketing Hub sends |
| Landing page | Hosted preference center, customizable brand and copy |
The three unsubscribe mechanisms in HubSpot
HubSpot treats unsubscribe management at the subscription type level, not the list level. A subscription type is a category of email the contact has consented to receive (product updates, newsletters, promotional offers, and so on). Each marketing email is tied to one subscription type, and the unsubscribe action removes the contact from that type specifically, not from the whole account.
Method 1: default embedded unsubscribe (recommended)
Every HubSpot marketing email includes a footer with a mandatory unsubscribe link by default. You cannot delete this footer without setting a Business Unit or an alternative footer template that also contains an unsubscribe token. This is the safest option because HubSpot enforces compliance automatically: correct token, correct URL, correct RFC 8058 headers on send. For most senders, this is the only method you need.
Method 2: custom placement with the unsubscribe token
When you want the unsubscribe option in the header, mid-email, or a specific styled block, insert the token manually inside a rich text or custom HTML module.
{{ unsubscribe_link }}Wrap it in an anchor tag for a proper hyperlink in the HTML source:
<a href="{{ unsubscribe_link }}">Unsubscribe from this list</a>The rendered URL points to a HubSpot-hosted preference center scoped to the current subscription type. If you use this method, the default footer link stays in place too. Do not try to remove it; HubSpot rejects sends without a footer unsubscribe token.
Method 3: account-wide global unsubscribe
For contacts who want to opt out of every marketing email from your account (not just the current subscription type), use the account-wide token. This is the equivalent of a global suppression flag.
{{ unsubscribe_link_all }}Use this in double opt-in confirmation emails or in transactional templates that also carry marketing content, where the recipient should be able to walk away from everything in one click. Do not use it as the default footer link in campaign emails; the per-subscription token is better for engagement metrics and re-permission strategies.
Step-by-step: where to configure each part
Edit the default footer and unsubscribe options
- In HubSpot, go to Marketing > Email
- Click Actions > Edit default email footer (top-right)
- Customize the footer copy, the unsubscribe link label, and the physical address block required by CAN-SPAM
- Save. The change applies to all future marketing sends from this account
Manage subscription types
- Go to Settings > Marketing > Email > Subscription types
- Add or edit types (Product updates, Newsletter, Promotions)
- Choose which types the contact sees by default on the preference center. Uncheck types you do not want to expose publicly
- Set the opt-out confirmation URL to your own branded thank-you page if you want to bypass the default HubSpot landing
Customize the preference center
- Go to Settings > Marketing > Email > Subscriptions > Preferences
- Edit the header logo, the intro copy, the confirmation copy, and (on Enterprise) the CSS
- Preview via the “Manage preferences” link in any test send
RFC 8058 one-click compliance in HubSpot
Since February 2024, Gmail and Yahoo require senders exceeding 5,000 emails per day to those providers to support one-click unsubscribe via the List-Unsubscribe-Post header defined in RFC 8058. HubSpot generates the correct headers automatically for every Marketing Hub send, including the mailto fallback defined in RFC 2369. You do not have to configure anything at the account level.
Two conditions must hold for the one-click path to actually function:
- Your sending domain must be authenticated with SPF, DKIM, and DMARC. Missing authentication causes Gmail to strip the List-Unsubscribe headers in transit
- The subscription type applied to the send must have at least one contact opted in and no domain-level suppression override. If HubSpot detects that the recipient is on a global unsubscribe or is a bounced address, no unsubscribe link is generated
Transactional emails sent from Marketing Hub carry the required headers only when the subscription type is explicitly marked as “one-to-one” or “transactional”. For pure product transactional email (order confirmations, password resets), consider a dedicated transactional platform like SendGrid, Mailgun, or Postmark, which handle transactional headers explicitly.
Testing your HubSpot unsubscribe link
Every unsubscribe link should be tested before the first production send, especially after any change to the default footer, the subscription types, or the preference center configuration.
- Send a test to a controlled Gmail address. In the email editor, click “Actions > Send test email” and pick a real address you own
- Click the footer unsubscribe link. Verify it lands on the preference center with the correct subscription type pre-selected. Confirm the opt-out
- Verify the RFC 8058 headers. In Gmail, open the message, click the three dots, then “Show original”. Look for these two lines in the source:
List-Unsubscribe: <mailto:...>, <https://track.hubspot.com/unsub/...>
List-Unsubscribe-Post: List-Unsubscribe=One-Click- Trigger the one-click flow. Copy the HTTPS URL from the header and simulate the POST request:
curl -X POST -d "List-Unsubscribe=One-Click" "https://track.hubspot.com/unsub/..."Expected response: HTTP 200 or 202. HubSpot processes the request and applies the unsubscribe within seconds. Check the contact record in your CRM to verify the subscription type is now opted out.
Common issues and how to fix them
“You cannot send this email without an unsubscribe link”
HubSpot blocks the send when the footer module has been removed or when a custom HTML template omits the token. Solution: reinsert the default footer module, or add {{ unsubscribe_link }} in a Rich Text module you control. Re-verify the send preview before proceeding.
The token renders as literal text in the delivered email
This happens when you place the token in a plain HTML module without HubL personalization enabled, or when you send from the “Transactional” send type without a subscription category. Move the token to a Rich Text module, or switch the send type to Marketing with a subscription category assigned.
Gmail does not show the one-click unsubscribe button
Two typical causes: your sending domain fails DMARC alignment (fix by aligning the From domain with the DKIM signing domain), or your send volume to that recipient’s domain is too low to trigger the Gmail promotional bar. Send volume needs to be consistent above roughly 100 emails per week to that domain before Gmail exposes the button.
The unsubscribe link uses track.hubspot.com instead of my domain
By default HubSpot uses its own tracking domain in unsubscribe URLs. To use your own subdomain (better brand consistency and better click-through on the preference center), configure an Email Sending Domain and a tracking subdomain in Settings > Website > Domains & URLs. This requires DNS access to add a CNAME record; propagation takes a few minutes to an hour.
Related unsubscribe guides
HubSpot competes and integrates with several other platforms; the unsubscribe mechanism differs materially in each:
- Mailchimp unsubscribe link: uses the
*|UNSUB|*merge tag, list-scoped by default, common HubSpot migration target - Klaviyo unsubscribe link: uses
{% unsubscribe %}, dominant on Shopify, often paired with HubSpot for the CRM side - Pardot unsubscribe link: uses
{{Unsubscribe}}, direct B2B alternative from Salesforce - Adobe Marketo unsubscribe link: uses
{{system.unsubscribeLink}}, enterprise B2B alternative - ActiveCampaign unsubscribe link: uses
%UNSUBSCRIBELINK%, marketing automation with CRM overlap - Keap unsubscribe link: CRM-plus-marketing alternative for small business
For the full 222-platform reference table and the underlying compliance landscape, see the pillar guide How to add an unsubscribe link: the complete 2026 guide. For the legal side, see CAN-SPAM Act, GDPR, and global unsubscribe laws.
HubSpot unsubscribe FAQ
Does the unsubscribe link apply to transactional emails from HubSpot?
Transactional emails sent from Marketing Hub with a transactional subscription type do not require an unsubscribe link under CAN-SPAM. GDPR is stricter: if the message contains any marketing content mixed with the transactional payload, you must still offer an opt-out for that marketing content. Best practice is to include a subscription preference link (not a full unsubscribe) in transactional footers.
Can an unsubscribed contact resubscribe on their own?
Yes. The HubSpot preference center lets contacts opt back in to any subscription type they previously unsubscribed from, unless the contact has been marked as a hard bounce or manually added to the never-send list. The re-opt-in event is logged in the contact timeline for audit purposes.
Can I use my own domain for the preference center URL?
Yes, but it requires the Content Hub (formerly CMS Hub) or Marketing Hub Enterprise, plus a connected subdomain configured in Settings > Website > Domains & URLs. Once connected, the preference center URL uses your subdomain (for example preferences.yourdomain.com) instead of track.hubspot.com.
Does HubSpot track unsubscribes per campaign?
Yes. Each marketing email in HubSpot exposes an “Unsubscribed” count in the performance report, plus a breakdown by unsubscribe reason if you enabled the reason picker on the preference center. The account-level unsubscribe rate is available under Marketing > Email > Analyze.
Can I import an unsubscribe list from another platform?
Yes. Import the list of email addresses via Contacts > Import, then use a workflow to apply the correct subscription opt-out to each imported contact. HubSpot honors the opt-out immediately once the workflow runs. Do not just add contacts to a “do not email” list; that flag does not persist across HubSpot updates the same way subscription opt-outs do.
About the Author
Alaa · LinkedIn
Email infrastructure specialist with 8+ years of hands-on experience in SMTP, deliverability, and email verification. I’ve configured and troubleshot mail systems across Postfix, Exchange, and cloud relays, managed IP reputation and warmup campaigns, and built verification pipelines processing millions of addresses. My work spans DNS authentication (SPF, DKIM, DMARC, BIMI), bounce handling, blocklist monitoring, and compliance frameworks including CAN-SPAM and GDPR. I write every article on SMTPedia to give email professionals, developers, and marketers the accurate, RFC-grounded reference they need.
About SMTPedia
SMTPedia is an independent email industry reference covering SMTP, IMAP, POP3, email deliverability, marketing platforms, DNS authentication, and email verification. Every article is researched from official provider documentation, IETF RFCs, and industry best practices. Settings and configurations are verified quarterly.
We are cited as a source by ChatGPT, Microsoft Copilot, and thousands of email professionals worldwide. Learn more about our editorial process.
