-
Notifications
You must be signed in to change notification settings - Fork 5
feat: 1-click unsubscribe docs #800
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
connorlindsey
merged 7 commits into
main
from
connor-kno-7966-docs-1-click-unsubscribe-link-docs
Apr 25, 2025
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
2a73463
chore: add relative delays to mapi ref (#798)
cellomatt 202e0f8
feat: first pass at 1-click unsubscribe docs
connorlindsey 29163fa
Apply feedback from Rachael
connorlindsey 5301fbd
chore: address feedback
cellomatt df3cb66
chore: add images
cellomatt 22d161c
include callout on merging
connorlindsey 8ef02f3
update reference in broadcast docs
connorlindsey File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,98 @@ | ||
--- | ||
title: "Commercial Unsubscribe" | ||
description: "Learn how to manage commercial email unsubscribe functionality in Knock." | ||
tags: ["preferences", "unsubscribe", "commercial", "broadcasts", "workflows"] | ||
section: Preferences | ||
--- | ||
|
||
Knock provides built-in support for commercial email unsubscribe functionality, allowing recipients to opt out of promotional or commercial messages with a single click. | ||
|
||
## How commercial unsubscribe works | ||
|
||
When you mark a workflow or broadcast as commercial, Knock automatically handles the necessary unsubscribe functionality: | ||
|
||
1. Adds required unsubscribe headers to all emails sent through that workflow or broadcast. | ||
1. Provides an unsubscribe URL variable that can be included in your email templates. | ||
1. Manages recipient opt-outs during [preference set evaluation](/preferences/overview#preference-evaluation-rules). | ||
|
||
## Configuring commercial workflows | ||
|
||
To enable commercial unsubscribe functionality for a workflow or broadcast: | ||
|
||
1. Navigate to the workflow or broadcast. | ||
1. For a workflow, click "Manage workflow." For a broadcast, click "Edit details." | ||
1. Toggle "Commercial." | ||
1. Save your changes. | ||
cellomatt marked this conversation as resolved.
Show resolved
Hide resolved
|
||
1. For a workflow, commit your changes. | ||
|
||
Once enabled, Knock will automatically include the necessary unsubscribe headers in all emails sent through that workflow. | ||
|
||
## Adding unsubscribe links to emails | ||
|
||
### Using footer links | ||
|
||
When configuring an email layout using the visual editor, you can toggle the "Include commercial unsubscribe link" input to include the unsubscribe link. | ||
cellomatt marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
<Image | ||
src="/images/integrations/email/layouts/commercial-unsubscribe-toggle.png" | ||
alt="Toggle to include commercial unsubscribe link in email layout" | ||
width="800" | ||
height="300" | ||
className="rounded-md mx-auto border border-gray-200" | ||
/> | ||
|
||
### Using the code editor | ||
|
||
You can add an unsubscribe link to your email layouts or templates using the built-in variable: | ||
|
||
```liquid title="Show unsubscribe link" | ||
<a href="{{vars.commercial_unsubscribe_url}}">Unsubscribe</a> | ||
``` | ||
|
||
You can conditionally include the link by checking if the variable is present: | ||
|
||
```liquid title="Show unsubscribe link only for commercial messages" | ||
{% if vars.commercial_unsubscribe_url %} | ||
<a href="{{vars.commercial_unsubscribe_url}}">Unsubscribe</a> | ||
{% endif %} | ||
``` | ||
|
||
## Configuring the confirmation page | ||
|
||
When a user unsubscribes by clicking the unsubscribe link, Knock displays a confirmation page showing they have been successfully unsubscribed from commercial messages. You can customize this page by navigating to **Developers** > **Preferences**, then clicking the **Unsubscribe** tab. | ||
|
||
<AccordionGroup> | ||
<Accordion title="Standard confirmation page" defaultOpen> | ||
You can customize the title and body text that will appear on the Knock confirmation page. | ||
|
||
<Image | ||
src="/images/concepts/preferences/customize-unsubscribe-confirmation.png" | ||
alt="Customizing the standard unsubscribe confirmation page" | ||
width="500" | ||
height="300" | ||
className="rounded-md mx-auto border border-gray-200" | ||
/> | ||
</Accordion> | ||
|
||
<Accordion title="Custom redirect URL"> | ||
You can provide a URL that recipients should be redirected to after unsubscribing. | ||
|
||
<Image | ||
src="/images/concepts/preferences/set-custom-redirect-url.png" | ||
alt="Setting a custom redirect URL for unsubscribe" | ||
width="500" | ||
height="200" | ||
className="rounded-md mx-auto border border-gray-200" | ||
/> | ||
</Accordion> | ||
</AccordionGroup> | ||
|
||
## Preference evaluation rules | ||
|
||
When a recipient clicks the unsubscribe link, their `default` preference set will be updated, marking `commercial_unsubscribe` as `true`. They will be opted-out of commercial messages, and they will continue to receive transactional messages based on their other preferences. | ||
|
||
This recipient-level preference will take precedence over other environment or tenant preferences. Learn more about [preference merging](/preferences/overview#preference-evaluation-rules). | ||
|
||
## Learn more | ||
|
||
To learn more about managing recipient preferences and building preference centers with Knock, visit our [preferences overview](/preferences/overview). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Binary file added
BIN
+43.2 KB
public/images/concepts/preferences/customize-unsubscribe-confirmation.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+57.9 KB
public/images/integrations/email/layouts/commercial-unsubscribe-toggle.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sentence casing