Skip to content

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
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/concepts/broadcasts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ Additionally, developer tools and extensions are available for broadcasts as the

Broadcasts respect all [user preferences](/concepts/preferences) that are configured in Knock. That means for any categories added to a broadcast, preferences linked to those categories will be respected. Additionally, any channel type preferences set for a user will be respected during the execution of a broadcast.

We're also working on a new set of promotional preference settings that will automatically add a 1-click unsubscribe header and link to your email messages, to respect CAN-SPAM compliance. This will be available in the coming weeks.
Knock also supports [commercial unsubscribe](/preferences/commercial-unsubscribe) preferences that will automatically add a 1-click unsubscribe header and link to your email messages, to respect CAN-SPAM compliance.

## Frequently asked questions

Expand Down
98 changes: 98 additions & 0 deletions content/preferences/commercial-unsubscribe.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
---
title: "Commercial Unsubscribe"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
title: "Commercial Unsubscribe"
title: "Commercial unsubscribe"

Sentence casing

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

<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).
5 changes: 5 additions & 0 deletions content/preferences/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ When Knock runs a workflow for a user, we evaluate their `PreferenceSet`. A mess

A preference set is built using three keys: `categories`, `channel_types`, `workflows`. These keys resolve to boolean values to determine if a user has opted out of receiving a notification.

A recipient's `default` preference set also has a `commercial_unsubscribe` key which determines if the recipient should receive notifications sent by commercial workflows or broadcasts. Read more about commercial unsubscribe [here](/preferences/commercial-unsubscribe).

A few examples:

```json title="Unsubscribe user from admin category notifications"
Expand Down Expand Up @@ -218,6 +220,7 @@ When a workflow is triggered, Knock will evaluate the preferences for each `reci
<AccordionGroup>
<Accordion title="General preference rules">
- If you do not set a preference for a given channel, workflow, or workflow category, Knock defaults them to `true`.
- When a recipient clicks an 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. Read more about commercial unsubscribe [here](/preferences/commercial-unsubscribe).
</Accordion>
<Accordion title="Resolving preference conflicts">
Knock only sends a notification if all preference combinations that exist on the recipient evaluate to `true`.
Expand All @@ -241,6 +244,7 @@ When a workflow is triggered, Knock will evaluate the preferences for each `reci

</Accordion>
</AccordionGroup>

## Bulk set user preferences

You can update the preferences of up to 1000 users in a single batch by using the `users.bulkSetPreferences` method. This executes an asynchronous job which will overwrite any existing preferences for the users provided. You can track the progress of the `BulkOperation` returned via the [bulk operation API](/reference#bulk-operations).
Expand All @@ -258,3 +262,4 @@ You can update the preferences of up to 1000 users in a single batch by using th
- [Object preferences](/preferences/object-preferences). In the guide above, we referred to user preferences. You can also set preferences for objects.
- [Preference conditions](/preferences/preference-conditions). You can build advanced conditions and store them on Knock’s preference model to power use cases such as per-resource muting (example: mute notifications about this task) or threshold alerts (example: only notify me if my account balance is below $5).
- Workflow overrides. If you need to override a recipient's notification preferences to send notifications like a password reset email, you can override the preferences model. To do this, go to your workflow, click "Manage workflow," and enable "Override recipient preferences." You will need to commit this change for it to take effect. When enabled, the workflow will send to all of its channels, regardless of the recipient's preferences.
- [Commercial unsubscribe](/preferences/commercial-unsubscribe). You can configure 1-click unsubscribe links to help users opt-out of commercial or promotional notifications and comply with CAN-SPAM requirements.
5 changes: 5 additions & 0 deletions data/sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,11 @@ const sidebarContent: SidebarSection[] = [
{ slug: "/tenant-preferences", title: "Tenant preferences" },
{ slug: "/object-preferences", title: "Object preferences" },
{ slug: "/preference-conditions", title: "Preferences conditions" },
{
slug: "/commercial-unsubscribe",
title: "Commercial unsubscribe",
isBeta: true,
},
],
},
{
Expand Down
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.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading