From 564cca3bec933afbd34dd9928603995b1625ab56 Mon Sep 17 00:00:00 2001 From: Matt Kufchak Date: Tue, 18 Mar 2025 18:21:33 -0500 Subject: [PATCH 1/2] chore: add relative delays to mapi ref (#798) --- content/preferences/commercial-unsubscribe.mdx | 8 ++++++++ content/preferences/overview.mdx | 4 ++++ data/sidebar.ts | 5 +++++ 3 files changed, 17 insertions(+) create mode 100644 content/preferences/commercial-unsubscribe.mdx diff --git a/content/preferences/commercial-unsubscribe.mdx b/content/preferences/commercial-unsubscribe.mdx new file mode 100644 index 00000000..16529b9d --- /dev/null +++ b/content/preferences/commercial-unsubscribe.mdx @@ -0,0 +1,8 @@ +--- +title: "Commercial unsubscribe" +description: "Learn how to enable 1-click unsubscribe links for commercial notifications." +tags: ["recipients", "unsubscribe", "commercial", "prefs", "preferences"] +section: Preferences +--- + +To comply with CAN-SPAM, you can mark a workflow or broadcast as commercial if it sends commercial or promotional messages. You can include a 1-click unsubscribe link in your templates and Knock will handle sending the appropriate email headers. diff --git a/content/preferences/overview.mdx b/content/preferences/overview.mdx index 8b56f239..e27c82c3 100644 --- a/content/preferences/overview.mdx +++ b/content/preferences/overview.mdx @@ -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. +The default preference set also has the `commercial_unsubscribe` which determines if the recipient should receive notifications sent by commercial workflows or broadcasts. + A few examples: ```json title="Unsubscribe user from admin category notifications" @@ -241,6 +243,7 @@ When a workflow is triggered, Knock will evaluate the preferences for each `reci + ## 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). @@ -258,3 +261,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. diff --git a/data/sidebar.ts b/data/sidebar.ts index 85b199c2..12ade073 100644 --- a/data/sidebar.ts +++ b/data/sidebar.ts @@ -124,6 +124,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, + }, ], }, { From 7b77a5dbf79a9e93fb014e6ba77572058ca42067 Mon Sep 17 00:00:00 2001 From: Connor Lindsey Date: Thu, 20 Mar 2025 14:10:53 -0700 Subject: [PATCH 2/2] feat: first pass at 1-click unsubscribe docs --- .../preferences/commercial-unsubscribe.mdx | 69 +++++++++++++++++-- 1 file changed, 65 insertions(+), 4 deletions(-) diff --git a/content/preferences/commercial-unsubscribe.mdx b/content/preferences/commercial-unsubscribe.mdx index 16529b9d..6c30466e 100644 --- a/content/preferences/commercial-unsubscribe.mdx +++ b/content/preferences/commercial-unsubscribe.mdx @@ -1,8 +1,69 @@ --- -title: "Commercial unsubscribe" -description: "Learn how to enable 1-click unsubscribe links for commercial notifications." -tags: ["recipients", "unsubscribe", "commercial", "prefs", "preferences"] +title: "Commercial Unsubscribe" +description: "Learn how to manage commercial email unsubscribe functionality in Knock" +tags: ["preferences", "unsubscribe", "commercial", "broadcasts", "workflows"] section: Preferences --- -To comply with CAN-SPAM, you can mark a workflow or broadcast as commercial if it sends commercial or promotional messages. You can include a 1-click unsubscribe link in your templates and Knock will handle sending the appropriate email headers. +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 + +## 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 + +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. + +### 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" +Unsubscribe +``` + +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 %} +Unsubscribe +{% endif %} +``` + +## Configuring the confirmation page + +When a user unsubscribes by directly clicking the unsubscribe link in a message, Knock will display a confirmation page indicating they have been succesfully unsubscribed from commercial messages. You can customize this page by navigating to "Developers" > "Preferences", then clicking the "Unsubscribe" tab. + +### Standard confirmation page + +You can customize the title and body text that will appear on the Knock confirmation page. + +### Custom redirect URL + +You can provide a URL that recipient's should be redirected to after unsubscribing. + +## 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. + +## Learn more + +To learn more about managing recipient preferences and building preference centers with Knock, visit our [preferences overview](/preferences/overview).