:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(workflows): count unsubscribes against the email they came from (#107883)
Daniel Marchukcbbe60f7699f
diff --git a/products/messaging/backend/facade/preferences.py b/products/messaging/backend/facade/preferences.pyindex 8162858c7e62..d0e179cfe11b 100644--- a/products/messaging/backend/facade/preferences.py+++ b/products/messaging/backend/facade/preferences.py@@ -1,6 +1,6 @@"""Recipient opt-outs: who opted out of which message category, and changes to that list."""-from collections.abc import Iterator, Sequence+from collections.abc import Callable, Iterator, Sequencefrom datetime import datetimefrom enum import StrEnumfrom typing import Any@@ -13,6 +13,7 @@ from products.messaging.backend.models.message_preferences import MessageRecipiefrom products.messaging.backend.services import (customerio_sync_service,preferences as preferences_service,+ unsubscribe_metrics,)from products.messaging.backend.services.lazy_list import LazyListfrom products.messaging.backend.services.opt_out_service import BulkOptOutEntry, UnknownCategoryError@@ -164,16 +165,27 @@ def recipient_preferences(team_id: int, identifier: str) -> dict[str, Any] | Nonreturn None if row is None else row.preferences-def set_preferences_column(team_id: int, identifier: str, preferences: dict[str, Any]) -> None:- """Overwrite an existing recipient's preferences. Writes only that column, so updated_at stays."""- preferences_service.set_preferences_column(team_id, identifier, preferences)+def transition_preferences(+ team_id: int,+ identifier: str,+ build: Callable[[dict[str, Any]], dict[str, Any]],+ *,+ touch_updated_at: bool,+) -> dict[str, Any]:+ """Replace the recipient's preferences with `build(stored)` under a row lock, creating the row when it is missing.--def replace_preferences(team_id: int, identifier: str, preferences: dict[str, Any]) -> None:- """Overwrite the recipient's preferences with one full save, creating the row when it is missing."""- preferences_service.replace_preferences(team_id, identifier, preferences)+ Returns the stored preferences it replaced. `touch_updated_at=False` writes only the preferences column.+ """+ return preferences_service.transition_preferences(team_id, identifier, build, touch_updated_at=touch_updated_at)def sync_to_customerio(team_id: int, identifier: str, preferences: dict[str, Any]) -> None:"""Push the preferences to Customer.io now, when the team has track sync enabled."""customerio_sync_service.sync_preferences_to_customerio(team_id, identifier, preferences)+++def record_unsubscribe_metric(team_id: int, token_data: dict[str, Any], opted_out_category_ids: list[str]) -> None:+ """Count an opt-out against the workflow email whose preferences token it came through."""+ unsubscribe_metrics.record_email_unsubscribed_metric(+ team_id, unsubscribe_metrics.parse_unsubscribe_source(token_data), opted_out_category_ids+ )diff --git a/products/messaging/backend/presentation/views/recipient_preferences.py b/products/messaging/backend/presentation/views/recipient_preferences.pyindex 9801c4bfac08..0960c7c57294 100644--- a/products/messaging/backend/presentation/views/recipient_preferences.py+++ b/products/messaging/backend/presentation/views/recipient_preferences.py@@ -21,10 +21,9 @@ from products.messaging.backend.facade.preferences import (get_or_create_recipient,marketing_categories,preference_status,- recipient_preferences,- replace_preferences,- set_preferences_column,+ record_unsubscribe_metric,sync_to_customerio,+ transition_preferences,)from products.workflows.backend.facade.enums import EmailTrackingConsentMode@@ -136,29 +135,33 @@ def preferences_page(request: HttpRequest, token: str) -> HttpResponse:request.GET.get("one_click_unsubscribe") == "1" or request.POST.get("one_click_unsubscribe") == "1")if is_one_click_unsubscribe:- was_fully_opted_out = (- preference_status(recipient.preferences, ALL_MESSAGE_PREFERENCE_CATEGORY_ID) == PreferenceStatus.OPTED_OUT- )- # If one-click unsubscribe, set all preferences to opted out- preferences_dict = {str(cat.id): PreferenceStatus.OPTED_OUT.value for cat in categories}+ def opt_out_of_everything(stored: dict[str, Any]) -> dict[str, Any]:+ # If one-click unsubscribe, set all preferences to opted out+ opted_out = {str(cat.id): PreferenceStatus.OPTED_OUT.value for cat in categories}- # Also set the "$all" preference- preferences_dict[ALL_MESSAGE_PREFERENCE_CATEGORY_ID] = PreferenceStatus.OPTED_OUT.value+ # Also set the "$all" preference+ opted_out[ALL_MESSAGE_PREFERENCE_CATEGORY_ID] = PreferenceStatus.OPTED_OUT.value- # Unsubscribing is about which emails arrive, not how they're measured — a stored- # tracking-consent answer must survive the wholesale rebuild- tracking_pref = (recipient.preferences or {}).get(EMAIL_TRACKING_PREFERENCE_ID)- if tracking_pref is not None:- preferences_dict[EMAIL_TRACKING_PREFERENCE_ID] = tracking_pref+ # Unsubscribing is about which emails arrive, not how they're measured — a stored+ # tracking-consent answer must survive the wholesale rebuild+ tracking_pref = stored.get(EMAIL_TRACKING_PREFERENCE_ID)+ if tracking_pref is not None:+ opted_out[EMAIL_TRACKING_PREFERENCE_ID] = tracking_pref+ return opted_out- set_preferences_column(team_id, identifier, preferences_dict)+ prior_preferences = transition_preferences(team_id, identifier, opt_out_of_everything, touch_updated_at=False)+ was_fully_opted_out = (+ preference_status(prior_preferences, ALL_MESSAGE_PREFERENCE_CATEGORY_ID) == PreferenceStatus.OPTED_OUT+ )+ preferences_dict = opt_out_of_everything(prior_preferences)current_preferences = preferences_dictsync_to_customerio(team_id, identifier, preferences_dict)# Only a genuine transition emits, so token replays and scanner prefetches don't inflate eventsif not was_fully_opted_out:+ record_unsubscribe_metric(team_id, data, [ALL_MESSAGE_PREFERENCE_CATEGORY_ID])report_workflows_email_unsubscribed(team_id, identifier, [ALL_MESSAGE_PREFERENCE_CATEGORY_ID], "one_click")if request.method == "POST":@@ -233,13 +236,12 @@ def update_preferences(request: HttpRequest) -> JsonResponse:if not team_id or not identifier:return JsonResponse({"error": "Invalid recipient"}, status=400)- stored_preferences = recipient_preferences(team_id, identifier)-try:- prior_preferences = dict(stored_preferences or {})preferences = request.POST.getlist("preferences[]")+ # The form accepts any category id string, so unknown ids are dropped before they can derive "$all"+ known_ids = team_category_ids(team_id) | {ALL_MESSAGE_PREFERENCE_CATEGORY_ID, EMAIL_TRACKING_PREFERENCE_ID}# Convert to dict of category_id: status- preferences_dict = {}+ submitted: dict[str, str] = {}for pref in preferences:category_id, opted_in = pref.split(":")@@ -247,28 +249,34 @@ def update_preferences(request: HttpRequest) -> JsonResponse:if opted_in not in ["true", "false"]:return JsonResponse({"error": "Preference values must be 'true' or 'false'"}, status=400)+ if category_id not in known_ids:+ continuestatus = PreferenceStatus.OPTED_IN if opted_in == "true" else PreferenceStatus.OPTED_OUT- preferences_dict[category_id] = status.value+ submitted[category_id] = status.value- # $email_tracking is a measurement consent, not a subscription — it must neither- # block nor trigger the "unsubscribed from everything" $all computation- subscription_prefs = {k: v for k, v in preferences_dict.items() if k != EMAIL_TRACKING_PREFERENCE_ID}+ def apply_submitted(stored: dict[str, Any]) -> dict[str, Any]:+ updated = dict(submitted)+ # $email_tracking is a measurement consent, not a subscription — it must neither+ # block nor trigger the "unsubscribed from everything" $all computation+ subscription_prefs = {k: v for k, v in updated.items() if k != EMAIL_TRACKING_PREFERENCE_ID}- # If all preferences are opted out, add the "$all" preference- if subscription_prefs and all(v == PreferenceStatus.OPTED_OUT.value for v in subscription_prefs.values()):- preferences_dict[ALL_MESSAGE_PREFERENCE_CATEGORY_ID] = PreferenceStatus.OPTED_OUT.value+ # If all preferences are opted out, add the "$all" preference+ if subscription_prefs and all(v == PreferenceStatus.OPTED_OUT.value for v in subscription_prefs.values()):+ updated[ALL_MESSAGE_PREFERENCE_CATEGORY_ID] = PreferenceStatus.OPTED_OUT.value- # A save that doesn't include the tracking toggle (e.g. consent mode is off) must- # not erase a stored consent answer in the wholesale rebuild- if EMAIL_TRACKING_PREFERENCE_ID not in preferences_dict and EMAIL_TRACKING_PREFERENCE_ID in prior_preferences:- preferences_dict[EMAIL_TRACKING_PREFERENCE_ID] = prior_preferences[EMAIL_TRACKING_PREFERENCE_ID]+ # A save that doesn't include the tracking toggle (e.g. consent mode is off) must+ # not erase a stored consent answer in the wholesale rebuild+ if EMAIL_TRACKING_PREFERENCE_ID not in updated and EMAIL_TRACKING_PREFERENCE_ID in stored:+ updated[EMAIL_TRACKING_PREFERENCE_ID] = stored[EMAIL_TRACKING_PREFERENCE_ID]- # A tracking-only save (no category toggles rendered, e.g. a team without marketing- # categories) must not rebuild subscription state - it would drop a stored $all opt-out- if not subscription_prefs:- preferences_dict = {**prior_preferences, **preferences_dict}+ # A tracking-only save (no category toggles rendered, e.g. a team without marketing+ # categories) must not rebuild subscription state - it would drop a stored $all opt-out+ if not subscription_prefs:+ updated = {**stored, **updated}+ return updated- replace_preferences(team_id, identifier, preferences_dict)+ prior_preferences = transition_preferences(team_id, identifier, apply_submitted, touch_updated_at=True)+ preferences_dict = apply_submitted(prior_preferences)sync_to_customerio(team_id, identifier, preferences_dict)@@ -281,6 +289,7 @@ def update_preferences(request: HttpRequest) -> JsonResponse:and prior_preferences.get(category_id) != PreferenceStatus.OPTED_OUT.value]if newly_opted_out:+ record_unsubscribe_metric(team_id, data, newly_opted_out)report_workflows_email_unsubscribed(team_id, identifier, newly_opted_out, "preferences_page")new_tracking_consent = preferences_dict.get(EMAIL_TRACKING_PREFERENCE_ID)diff --git a/products/messaging/backend/services/preferences.py b/products/messaging/backend/services/preferences.pyindex 900299b36056..0e4d1a06f49d 100644--- a/products/messaging/backend/services/preferences.py+++ b/products/messaging/backend/services/preferences.py@@ -1,4 +1,4 @@-from collections.abc import Iterator+from collections.abc import Callable, Iteratorfrom typing import Anyfrom django.db import transaction@@ -145,17 +145,21 @@ def recipient_or_none(team_id: int, identifier: str) -> MessageRecipientPreferenreturn MessageRecipientPreference.objects.filter(team_id=team_id, identifier=identifier).first()-def set_preferences_column(team_id: int, identifier: str, preferences: dict[str, Any]) -> None:- recipient = MessageRecipientPreference.objects.get(team_id=team_id, identifier=identifier)- recipient.preferences = preferences- recipient.save(update_fields=["preferences"])+def transition_preferences(+ team_id: int,+ identifier: str,+ build: Callable[[dict[str, Any]], dict[str, Any]],+ *,+ touch_updated_at: bool,+) -> dict[str, Any]:+ """Replace the recipient's preferences with `build(stored)` under a row lock, and return the stored ones.--def replace_preferences(team_id: int, identifier: str, preferences: dict[str, Any]) -> None:- try:- recipient = MessageRecipientPreference.objects.get(team_id=team_id, identifier=identifier)- except MessageRecipientPreference.DoesNotExist:- recipient = MessageRecipientPreference(team_id=team_id, identifier=identifier)- # Update all preferences with a single DB write- recipient.preferences = preferences- recipient.save()+ Concurrent saves for one recipient run one after another, so each sees the result of the one before it.+ """+ with transaction.atomic():+ MessageRecipientPreference.objects.get_or_create(team_id=team_id, identifier=identifier)+ recipient = MessageRecipientPreference.objects.select_for_update().get(team_id=team_id, identifier=identifier)+ prior = dict(recipient.preferences or {})+ recipient.preferences = build(prior)+ recipient.save(update_fields=None if touch_updated_at else ["preferences"])+ return priordiff --git a/products/messaging/backend/services/unsubscribe_metrics.py b/products/messaging/backend/services/unsubscribe_metrics.pynew file mode 100644index 000000000000..3aea6d34e2ba--- /dev/null+++ b/products/messaging/backend/services/unsubscribe_metrics.py@@ -0,0 +1,77 @@+import re+import uuid+from typing import Any++import structlog++from posthog.dataclasses import frozen+from posthog.exceptions_capture import capture_exception+from posthog.kafka_client.routing import get_producer+from posthog.kafka_client.topics import KAFKA_APP_METRICS2+from posthog.models.event.util import format_clickhouse_timestamp+from posthog.utils import cast_timestamp_or_now++from products.messaging.backend.models.message_category import MessageCategory+from products.messaging.backend.models.message_preferences import ALL_MESSAGE_PREFERENCE_CATEGORY_ID++logger = structlog.get_logger(__name__)++_INSTANCE_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,128}$")+++@frozen+class UnsubscribeSource:+ """The workflow email a preferences link came from, read from the verified preferences token."""++ app_source_id: str+ instance_id: str+++def parse_unsubscribe_source(token_data: dict[str, Any]) -> UnsubscribeSource | None:+ app_source_id = token_data.get("app_source_id")+ instance_id = token_data.get("instance_id")+ if not isinstance(app_source_id, str) or not isinstance(instance_id, str):+ return None+ try:+ uuid.UUID(app_source_id)+ except ValueError:+ return None+ if not _INSTANCE_ID_PATTERN.match(instance_id):+ return None+ return UnsubscribeSource(app_source_id=app_source_id, instance_id=instance_id)+++def _includes_real_category(team_id: int, category_ids: list[str]) -> bool:+ # The preferences form accepts any category id string, so made-up ids must not add to the count.+ if ALL_MESSAGE_PREFERENCE_CATEGORY_ID in category_ids:+ return True+ real_ids = {+ str(category_id)+ for category_id in MessageCategory.objects.filter(team_id=team_id, deleted=False).values_list("id", flat=True)+ }+ return any(category_id in real_ids for category_id in category_ids)+++def record_email_unsubscribed_metric(+ team_id: int, source: UnsubscribeSource | None, opted_out_category_ids: list[str]+) -> None:+ """Count one opt-out against the workflow email it came from. Best-effort: never fails the opt-out."""+ if source is None:+ return+ try:+ if not _includes_real_category(team_id, opted_out_category_ids):+ return+ payload = {+ "team_id": team_id,+ "timestamp": format_clickhouse_timestamp(cast_timestamp_or_now(None)),+ "app_source": "hog_flow",+ "app_source_id": source.app_source_id,+ "instance_id": source.instance_id,+ "metric_kind": "email",+ "metric_name": "email_unsubscribed",+ "count": 1,+ }+ get_producer(topic=KAFKA_APP_METRICS2).produce(topic=KAFKA_APP_METRICS2, data=payload)+ except Exception as e:+ logger.warning("email_unsubscribed_metric_failed", team_id=team_id, error=str(e))+ capture_exception(e)diff --git a/products/messaging/backend/tests/api/test_message_preferences.py b/products/messaging/backend/tests/api/test_message_preferences.pyindex 4983422401cb..5866ce957a0d 100644--- a/products/messaging/backend/tests/api/test_message_preferences.py+++ b/products/messaging/backend/tests/api/test_message_preferences.py@@ -206,6 +206,122 @@ class TestMessagePreferencesViews(BaseTest):self.assertEqual(response.status_code, 400)self.assertEqual(json.loads(response.content), {"error": "Preference values must be 'true' or 'false'"})+ @parameterized.expand(+ [+ ("one_click", "one_click", {}, True),+ ("preferences_opt_out", "opt_out", {}, True),+ ("already_opted_out", "one_click", {"$all": PreferenceStatus.OPTED_OUT.value}, False),+ ("preferences_opt_in", "opt_in", {}, False),+ ("page_view", "view", {}, False),+ ("unknown_category_only", "junk_opt_out", {}, False),+ ("unknown_category_alone", "junk_alone", {}, False),+ ]+ )+ @patch("products.messaging.backend.services.unsubscribe_metrics.get_producer")+ @patch("products.messaging.backend.presentation.views.recipient_preferences.validate_messaging_preferences_token")+ def test_opt_out_records_unsubscribed_metric_for_the_sending_email(+ self, _name, action, prior_preferences, expect_metric, mock_validate, mock_get_producer+ ):+ run_id = "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"+ self.recipient.preferences = prior_preferences+ self.recipient.save()+ mock_validate.return_value = mock_response(+ 200,+ {+ "valid": True,+ "team_id": self.team.id,+ "identifier": self.recipient.identifier,+ "app_source_id": run_id,+ "instance_id": "action_function_email_1",+ },+ )++ if action in ("one_click", "view"):+ params = {"one_click_unsubscribe": "1"} if action == "one_click" else {}+ response = self.client.get(reverse("message_preferences", kwargs={"token": self.token}), params)+ else:+ prefs = {+ "opt_out": [f"{self.category.id}:false"],+ "opt_in": [f"{self.category.id}:true"],+ "junk_opt_out": [f"{self.category.id}:true", "not-a-real-category:false"],+ "junk_alone": ["not-a-real-category:false"],+ }[action]+ response = self.client.post(+ reverse("message_preferences_update"), {"token": self.token, "preferences[]": prefs}+ )++ self.assertEqual(response.status_code, 200)+ produce = mock_get_producer.return_value.produce+ if not expect_metric:+ produce.assert_not_called()+ return+ produce.assert_called_once()+ self.assertEqual(+ {k: v for k, v in produce.call_args.kwargs["data"].items() if k != "timestamp"},+ {+ "team_id": self.team.id,+ "app_source": "hog_flow",+ "app_source_id": run_id,+ "instance_id": "action_function_email_1",+ "metric_kind": "email",+ "metric_name": "email_unsubscribed",+ "count": 1,+ },+ )++ @parameterized.expand(+ [+ ("no_claims", {}),+ ("app_source_id_not_a_uuid", {"app_source_id": "../other", "instance_id": "action_1"}),+ ("instance_id_unsafe", {"app_source_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b", "instance_id": "a b"}),+ ("instance_id_missing", {"app_source_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"}),+ ]+ )+ @patch("products.messaging.backend.services.unsubscribe_metrics.get_producer")+ @patch("products.messaging.backend.presentation.views.recipient_preferences.validate_messaging_preferences_token")+ def test_one_click_without_usable_source_opts_out_without_metric(+ self, _name, claims, mock_validate, mock_get_producer+ ):+ mock_validate.return_value = mock_response(+ 200, {"valid": True, "team_id": self.team.id, "identifier": self.recipient.identifier, **claims}+ )++ response = self.client.get(+ reverse("message_preferences", kwargs={"token": self.token}), {"one_click_unsubscribe": "1"}+ )++ self.assertEqual(response.status_code, 200)+ self.recipient.refresh_from_db()+ self.assertEqual(+ self.recipient.get_all_preferences()[ALL_MESSAGE_PREFERENCE_CATEGORY_ID], PreferenceStatus.OPTED_OUT+ )+ mock_get_producer.return_value.produce.assert_not_called()++ @patch("products.messaging.backend.services.unsubscribe_metrics.get_producer")+ @patch("products.messaging.backend.presentation.views.recipient_preferences.validate_messaging_preferences_token")+ def test_one_click_opts_out_when_metric_produce_fails(self, mock_validate, mock_get_producer):+ mock_get_producer.return_value.produce.side_effect = RuntimeError("kafka down")+ mock_validate.return_value = mock_response(+ 200,+ {+ "valid": True,+ "team_id": self.team.id,+ "identifier": self.recipient.identifier,+ "app_source_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",+ "instance_id": "action_1",+ },+ )++ response = self.client.get(+ reverse("message_preferences", kwargs={"token": self.token}), {"one_click_unsubscribe": "1"}+ )++ self.assertEqual(response.status_code, 200)+ self.recipient.refresh_from_db()+ self.assertEqual(+ self.recipient.get_all_preferences()[ALL_MESSAGE_PREFERENCE_CATEGORY_ID], PreferenceStatus.OPTED_OUT+ )+def _enable_engagement_events(self):config = self.team.workflows_configconfig.capture_workflows_engagement_events = Truediff --git a/products/workflows/frontend/Broadcasts/BroadcastPerformance.tsx b/products/workflows/frontend/Broadcasts/BroadcastPerformance.tsxindex e1af23d4d020..2d940fba03e9 100644--- a/products/workflows/frontend/Broadcasts/BroadcastPerformance.tsx+++ b/products/workflows/frontend/Broadcasts/BroadcastPerformance.tsx@@ -41,6 +41,7 @@ export function BroadcastPerformance({{ label: 'Bounced', value: share(stats.bounced, stats.sent), detail: stats.bounced },{ label: 'Marked as spam', value: share(stats.markedAsSpam, stats.sent), detail: stats.markedAsSpam },{ label: 'Failed', value: share(stats.failed, stats.sent), detail: stats.failed },+ { label: 'Unsubscribed', value: share(stats.unsubscribed, stats.sent), detail: stats.unsubscribed },]const engagement = [...(trackingOff@@ -61,7 +62,7 @@ export function BroadcastPerformance({return (<div className="flex flex-col gap-4 rounded-lg border border-border bg-surface-primary p-4">- <div className="grid grid-cols-2 gap-4 @xl:grid-cols-5">+ <div className="grid grid-cols-2 gap-4 @xl:grid-cols-3 @4xl:grid-cols-6">{headline.map(({ label, value, detail }) => (<div key={label} className="flex flex-col"><span className="text-xl font-semibold">{value}</span>diff --git a/products/workflows/frontend/Broadcasts/broadcastPerformanceLogic.ts b/products/workflows/frontend/Broadcasts/broadcastPerformanceLogic.tsindex 3713ed6c341a..e48c87d92826 100644--- a/products/workflows/frontend/Broadcasts/broadcastPerformanceLogic.ts+++ b/products/workflows/frontend/Broadcasts/broadcastPerformanceLogic.ts@@ -22,6 +22,7 @@ export interface BroadcastPerformanceStats {bounced: numbermarkedAsSpam: numberfailed: number+ unsubscribed: number/** Sends with open and click tracking, the denominator for engagement rates. */trackedSends: number/** Recipients who met the broadcast's goal. */@@ -37,6 +38,7 @@ const TOTALS_METRICS = ['email_blocked','email_failed','email_untracked',+ 'email_unsubscribed','conversion',]@@ -211,6 +213,7 @@ export const broadcastPerformanceLogic = kea<broadcastPerformanceLogicType>([// Spam complaints are stored under email_blocked.markedAsSpam: totals.email_blocked ?? 0,failed: totals.email_failed ?? 0,+ unsubscribed: totals.email_unsubscribed ?? 0,trackedSends: Math.max(sent - (totals.email_untracked ?? 0), 0),converted: totals.conversion ?? 0,}