: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): add the backend for an opt out of messages step (#121238)
Harley Alexander92af9b7e486a
diff --git a/posthog/jwt.py b/posthog/jwt.pyindex e6321961bfb6..058bbd8b9eee 100644--- a/posthog/jwt.py+++ b/posthog/jwt.py@@ -40,6 +40,7 @@ class PosthogJwtAudience(Enum):WORKFLOW_CLASSIFY = "posthog:workflows:classify"WORKFLOW_VISION_REQUEST = "posthog:workflows:vision_request"WORKFLOW_ADD_TO_STATIC_COHORT = "posthog:workflows:add_to_static_cohort"+ WORKFLOW_MESSAGE_OPT_OUT = "posthog:workflows:message_opt_out"CONVERSATIONS_TICKETS = "posthog:conversations:tickets"CUSTOMER_ANALYTICS_ACCOUNTS = "posthog:customer_analytics:accounts"SECURITY_HUB_RULES = "posthog:security_hub:rules"diff --git a/posthog/settings/data_stores.py b/posthog/settings/data_stores.pyindex 65ee1d48aa99..2185b49cbfea 100644--- a/posthog/settings/data_stores.py+++ b/posthog/settings/data_stores.py@@ -649,6 +649,15 @@ WORKFLOW_ADD_TO_STATIC_COHORT_JWT_SECRETS = get_list())+# Signs the tokens a workflow's "Opt out of messages" step calls back with. The dev/test value must match the+# plugin server's minting default.+WORKFLOW_MESSAGE_OPT_OUT_JWT_SECRETS = get_list(+ get_from_env(+ "WORKFLOW_MESSAGE_OPT_OUT_JWT_SECRET",+ "local-dev-workflow-message-opt-out-jwt" if DEBUG or TEST else "",+ )+)+# Verifies the scoped JWTs the CDP worker's conversations ticket actions send to the internal# ticket route (the worker mints, Django verifies; products/conversations/backend/api/internal.py).# Comma-separated, newest first. Empty outside dev/test, so the internal route rejects everydiff --git a/products/cdp/backend/flag_gated_templates.py b/products/cdp/backend/flag_gated_templates.pyindex 0e6942b50835..4f828c4f7b26 100644--- a/products/cdp/backend/flag_gated_templates.py+++ b/products/cdp/backend/flag_gated_templates.py@@ -16,6 +16,7 @@ FLAG_GATED_TEMPLATE_IDS = {"template-posthog-create-task": "workflow-ai-task-action","template-posthog-classify": "workflow-classify-action","template-posthog-add-to-static-cohort": "workflow-add-to-static-cohort-action",+ "template-posthog-opt-out-of-messages": "workflow-opt-out-of-messages-action",}diff --git a/products/messaging/backend/models/message_preferences.py b/products/messaging/backend/models/message_preferences.pyindex 6946079aca49..b8451f22b3dd 100644--- a/products/messaging/backend/models/message_preferences.py+++ b/products/messaging/backend/models/message_preferences.py@@ -1,6 +1,10 @@from typing import Optional-from django.db import models+from django.db import models, router+from django.db.models import F, Value+from django.db.models.expressions import CombinedExpression+from django.db.models.functions import Coalesce+from django.utils import timezonefrom posthog.models.utils import UUIDTModel@@ -42,8 +46,17 @@ class MessageRecipientPreference(UUIDTModel):if not isinstance(status, PreferenceStatus):raise ValueError(f"Status must be a PreferenceStatus enum, got {type(status)}")- self.preferences[str(category_id)] = status.value- self.save(update_fields=["preferences", "updated_at"])+ # Merge the one key in the database. Saving the whole column would drop a category that another request+ # set after this row was read.+ type(self).objects.filter(pk=self.pk, team_id=self.team_id).update(+ preferences=CombinedExpression(+ Coalesce(F("preferences"), Value({}, output_field=models.JSONField())),+ "||",+ Value({str(category_id): status.value}, output_field=models.JSONField()),+ ),+ updated_at=timezone.now(),+ )+ self.refresh_from_db(using=router.db_for_write(type(self)), fields=["preferences", "updated_at"])def get_preference(self, category_id: str) -> PreferenceStatus:"""Get preference for a specific category"""diff --git a/products/messaging/backend/tests/test_message_preferences.py b/products/messaging/backend/tests/test_message_preferences.pyindex d407cd79afd2..1cd0649db13a 100644--- a/products/messaging/backend/tests/test_message_preferences.py+++ b/products/messaging/backend/tests/test_message_preferences.py@@ -72,6 +72,18 @@ class TestMessagePreferences(BaseTest):recipient.set_preference(self.category.id, PreferenceStatus.OPTED_OUT)self.assertEqual(recipient.get_preference(self.category.id), PreferenceStatus.OPTED_OUT)+ def test_set_preference_keeps_a_category_another_request_set(self):+ MessageRecipientPreference.objects.create(team=self.team, identifier="[email protected]", preferences={})+ first = MessageRecipientPreference.objects.get(team=self.team, identifier="[email protected]")+ second = MessageRecipientPreference.objects.get(team=self.team, identifier="[email protected]")++ first.set_preference(self.category.id, PreferenceStatus.OPTED_OUT)+ second.set_preference(self.category2.id, PreferenceStatus.OPTED_OUT)++ stored = MessageRecipientPreference.objects.get(team=self.team, identifier="[email protected]")+ self.assertEqual(stored.get_preference(self.category.id), PreferenceStatus.OPTED_OUT)+ self.assertEqual(stored.get_preference(self.category2.id), PreferenceStatus.OPTED_OUT)+def test_get_preference(self):recipient = MessageRecipientPreference.objects.create(team=self.team, identifier="[email protected]", preferences={}diff --git a/products/workflows/backend/facade/api.py b/products/workflows/backend/facade/api.pyindex a75309846cb8..7cf10cd1e02b 100644--- a/products/workflows/backend/facade/api.py+++ b/products/workflows/backend/facade/api.py@@ -25,7 +25,7 @@ from products.workflows.backend.facade.contracts import (WorkflowVisionScanDailyLimits,)from products.workflows.backend.models import HogFlow, TeamWorkflowsConfig-from products.workflows.backend.models.hog_flow.hog_flow import static_cohort_ids+from products.workflows.backend.models.hog_flow.hog_flow import opt_out_category_ids, static_cohort_idsfrom products.workflows.backend.services.batch_jobs import create_batch_jobfrom products.workflows.backend.services.default_email_sender import (clear_default_email_sender,@@ -151,6 +151,14 @@ def get_workflow_static_cohort_ids(*, team_id: int, workflow_id: UUID) -> set[inreturn static_cohort_ids(actions)+def get_workflow_opt_out_category_ids(*, team_id: int, workflow_id: UUID) -> set[str]:+ try:+ actions = HogFlow.objects.values_list("actions", flat=True).get(team_id=team_id, id=workflow_id)+ except HogFlow.DoesNotExist:+ raise WorkflowNotFound() from None+ return opt_out_category_ids(actions)++def workflow_exists(*, team_id: int, workflow_id: UUID) -> bool:return HogFlow.objects.filter(team_id=team_id, id=workflow_id).exists()diff --git a/products/workflows/backend/facade/service_jwt.py b/products/workflows/backend/facade/service_jwt.pyindex db781ddbb1d6..66c92e71c1b6 100644--- a/products/workflows/backend/facade/service_jwt.py+++ b/products/workflows/backend/facade/service_jwt.py@@ -1,13 +1,14 @@"""The scoped service JWT purposes that the workflow callback endpoints verify.The plugin server mints tokens for the "Create AI task", "Run scout", "Classify with AI",-"Replay Vision" and "Add to static cohort" workflow steps.+"Replay Vision", "Add to static cohort" and "Opt out of messages" workflow steps."""from products.workflows.backend.service_jwt import (TASKS_CREATE_PURPOSE,WORKFLOW_ADD_TO_STATIC_COHORT_PURPOSE,WORKFLOW_CLASSIFY_PURPOSE,+ WORKFLOW_MESSAGE_OPT_OUT_PURPOSE,WORKFLOW_SCOUT_RUN_PURPOSE,WORKFLOW_VISION_REQUEST_PURPOSE,)@@ -16,6 +17,7 @@ __all__ = ["TASKS_CREATE_PURPOSE","WORKFLOW_ADD_TO_STATIC_COHORT_PURPOSE","WORKFLOW_CLASSIFY_PURPOSE",+ "WORKFLOW_MESSAGE_OPT_OUT_PURPOSE","WORKFLOW_SCOUT_RUN_PURPOSE","WORKFLOW_VISION_REQUEST_PURPOSE",]diff --git a/products/workflows/backend/facade/workflows.py b/products/workflows/backend/facade/workflows.pyindex f2939fa994a9..34874856df62 100644--- a/products/workflows/backend/facade/workflows.py+++ b/products/workflows/backend/facade/workflows.py@@ -3,15 +3,19 @@ each with its secret inputs masked."""from products.workflows.backend.models.hog_flow.hog_flow import (ADD_TO_STATIC_COHORT_TEMPLATE_ID,+ ALL_MARKETING_CATEGORY_ID,BILLABLE_ACTION_TYPES,COHORT_TRIGGER_TRANSITIONS,+ OPT_OUT_OF_MESSAGES_TEMPLATE_ID,PERSON_DEPENDENT_ACTION_TYPES,ROW_SCOPED_TRIGGER_TYPES,SUPPORTED_ACTION_TYPES,TRIGGER_TYPES,WORKFLOW_SAFE_INTERNAL_EVENTS,exit_condition_that_runs,+ literal_opt_out_category_id,literal_static_cohort_id,+ opt_out_category_ids,static_cohort_ids,)from products.workflows.backend.services.hog_flow_reads import (@@ -29,6 +33,8 @@ from products.workflows.backend.services.hog_flow_reads import (__all__ = ["ADD_TO_STATIC_COHORT_TEMPLATE_ID",+ "ALL_MARKETING_CATEGORY_ID",+ "OPT_OUT_OF_MESSAGES_TEMPLATE_ID","BILLABLE_ACTION_TYPES","COHORT_TRIGGER_TRANSITIONS","PERSON_DEPENDENT_ACTION_TYPES",@@ -36,7 +42,9 @@ __all__ = ["SUPPORTED_ACTION_TYPES","TRIGGER_TYPES","WORKFLOW_SAFE_INTERNAL_EVENTS",+ "literal_opt_out_category_id","literal_static_cohort_id",+ "opt_out_category_ids","static_cohort_ids","BROADCAST_STATUSES","WORKFLOW_FIELD_FILTER_PARAMS",diff --git a/products/workflows/backend/models/hog_flow/hog_flow.py b/products/workflows/backend/models/hog_flow/hog_flow.pyindex 4689448e5185..0006761dd448 100644--- a/products/workflows/backend/models/hog_flow/hog_flow.py+++ b/products/workflows/backend/models/hog_flow/hog_flow.py@@ -1,3 +1,4 @@+from collections.abc import Iteratorfrom typing import TYPE_CHECKING, Any, Finalfrom django.db import models, transaction@@ -128,22 +129,49 @@ def literal_static_cohort_id(inputs: Any) -> int | None:return cohort_id-def static_cohort_ids(actions: Any) -> set[int]:- """The cohorts that the "Add to static cohort" steps in these actions add people to.+def _function_step_inputs(actions: Any, template_id: str) -> Iterator[Any]:+ """The inputs of each function action that runs the template.- Only function actions count, because the serializer checks cohort access for those alone.+ Only function actions count, because the serializer validates template inputs for those alone."""- cohort_ids: set[int] = set()for action in actions if isinstance(actions, list) else []:if not isinstance(action, dict) or action.get("type") != "function":continueconfig = action.get("config")- if not isinstance(config, dict) or config.get("template_id") != ADD_TO_STATIC_COHORT_TEMPLATE_ID:- continue- cohort_id = literal_static_cohort_id(config.get("inputs"))- if cohort_id is not None:- cohort_ids.add(cohort_id)- return cohort_ids+ if isinstance(config, dict) and config.get("template_id") == template_id:+ yield config.get("inputs")+++def static_cohort_ids(actions: Any) -> set[int]:+ """The cohorts that the "Add to static cohort" steps in these actions add people to."""+ cohort_ids = (+ literal_static_cohort_id(inputs) for inputs in _function_step_inputs(actions, ADD_TO_STATIC_COHORT_TEMPLATE_ID)+ )+ return {cohort_id for cohort_id in cohort_ids if cohort_id is not None}+++# The "Opt out of messages" step. Its template lives in the plugin server.+OPT_OUT_OF_MESSAGES_TEMPLATE_ID: Final[str] = "template-posthog-opt-out-of-messages"+# The step's category value for all marketing messages. Matches the messaging product's reserved preference key.+ALL_MARKETING_CATEGORY_ID: Final[str] = "$all"+++def literal_opt_out_category_id(inputs: Any) -> str | None:+ """The message category id an "Opt out of messages" step names as a plain value, or None."""+ category_input = inputs.get("category_id") if isinstance(inputs, dict) else None+ category_id = category_input.get("value") if isinstance(category_input, dict) else None+ if not isinstance(category_id, str) or not category_id.strip():+ return None+ return category_id.strip()+++def opt_out_category_ids(actions: Any) -> set[str]:+ """The message categories that the "Opt out of messages" steps in these actions opt people out of."""+ category_ids = (+ literal_opt_out_category_id(inputs)+ for inputs in _function_step_inputs(actions, OPT_OUT_OF_MESSAGES_TEMPLATE_ID)+ )+ return {category_id for category_id in category_ids if category_id is not None}# Trigger types the executor re-checks before each step: an event trigger against its filters, and adiff --git a/products/workflows/backend/presentation/views/hog_flow.py b/products/workflows/backend/presentation/views/hog_flow.pyindex 8f5fb89134af..678bdfc1cedb 100644--- a/products/workflows/backend/presentation/views/hog_flow.py+++ b/products/workflows/backend/presentation/views/hog_flow.py@@ -129,6 +129,7 @@ from products.cdp.backend.presentation.serializers import (require_viewer_access_to_added_actions,)from products.cohorts.backend.facade.api import get_cohort_ref+from products.messaging.backend.facade.categories import MessageCategoryMissing, get_categoryfrom products.messaging.backend.presentation.views.serializers import DesignOperationSerializerfrom products.notifications.backend.facade.api import publish_resource_editedfrom products.replay_vision.backend.facade.api import (@@ -295,9 +296,11 @@ from products.workflows.backend.facade.validation import ()from products.workflows.backend.facade.workflows import (ADD_TO_STATIC_COHORT_TEMPLATE_ID,+ ALL_MARKETING_CATEGORY_ID,BILLABLE_ACTION_TYPES,BROADCAST_STATUSES,COHORT_TRIGGER_TRANSITIONS,+ OPT_OUT_OF_MESSAGES_TEMPLATE_ID,PERSON_DEPENDENT_ACTION_TYPES,ROW_SCOPED_TRIGGER_TYPES,SUPPORTED_ACTION_TYPES,@@ -310,7 +313,9 @@ from products.workflows.backend.facade.workflows import (get_workflow_edit_state,get_workflow_ref,list_workflows,+ literal_opt_out_category_id,literal_static_cohort_id,+ opt_out_category_ids,static_cohort_ids,workflow_from_fields,workflow_publish_impact,@@ -1709,6 +1714,48 @@ class HogFlowActionSerializer(serializers.Serializer):{"inputs": {"cohort_id": "You need edit access to this cohort to add people to it."}})+ def _validate_opt_out_of_messages_action(self, inputs: dict, *, strict: bool) -> None:+ """The step edits the team-wide opt-out list as a service, so whoever saves it needs the access that list needs.++ Runs on lenient draft saves too, because the callback endpoint accepts only the categories the saved+ workflow names. A draft save may keep a category that no longer exists, but never a transactional one."""+ category_id = literal_opt_out_category_id(inputs)+ if category_id is None:+ if strict:+ raise serializers.ValidationError({"inputs": {"category_id": "Choose a message category."}})+ return+ get_team = self.context.get("get_team")+ if get_team is None:+ return+ team = get_team()+ user = getattr(self.context.get("request"), "user", None)+ # Same resource-level check as the opt-out list API: access to one workflow isn't access to the team's list.+ # Someone already passed it for a category the saved workflow names, so other editors can keep saving.+ if (+ category_id not in (self.context.get("stored_opt_out_category_ids") or set())+ and user is not None+ and user.is_authenticated+ and not isinstance(user, SyntheticUser)+ and not UserAccessControl(user=user, team=team).check_access_level_for_resource("hog_flow", "editor")+ ):+ raise serializers.ValidationError(+ {"inputs": {"category_id": "You need edit access to all workflows to change the opt-out list."}}+ )+ if category_id == ALL_MARKETING_CATEGORY_ID:+ return+ try:+ category = get_category(team.id, category_id)+ except MessageCategoryMissing:+ if strict:+ raise serializers.ValidationError(+ {"inputs": {"category_id": "This message category doesn't exist. Choose another category."}}+ )+ return+ if category.category_type != "marketing":+ raise serializers.ValidationError(+ {"inputs": {"category_id": "Transactional messages ignore opt-outs. Choose a marketing category."}}+ )+def _validate_run_scout_action(self) -> None:"""Save-time check for the "Run scout" step: reject it in a child environment, matchingthe runtime refusal in start_workflow_scout_run, so a broken step fails at save instead of@@ -1949,6 +1996,8 @@ class HogFlowActionSerializer(serializers.Serializer):# validation but still stores the cohort ID that the callback later trusts.if data.get("type") == "function" and template_id == ADD_TO_STATIC_COHORT_TEMPLATE_ID:self._validate_add_to_static_cohort_action(config.get("inputs") or {}, strict=strict)+ if data.get("type") == "function" and template_id == OPT_OUT_OF_MESSAGES_TEMPLATE_ID:+ self._validate_opt_out_of_messages_action(config.get("inputs") or {}, strict=strict)template = get_function_template_schema(template_id)gating_flag = FLAG_GATED_TEMPLATE_IDS.get(template_id)already_stored = data.get("id") in (self.context.get("stored_gated_template_action_ids") or set())@@ -3333,6 +3382,7 @@ class HogFlowSerializer(HogFlowMinimalSerializer):}self.context["stored_static_cohort_ids"] = static_cohort_ids(instance.actions if instance else None)+ self.context["stored_opt_out_category_ids"] = opt_out_category_ids(instance.actions if instance else None)self.context["stored_cohort_triggers"] = {action["id"]: {diff --git a/products/workflows/backend/presentation/views/workflow_message_opt_outs.py b/products/workflows/backend/presentation/views/workflow_message_opt_outs.pynew file mode 100644index 000000000000..aae128fee949--- /dev/null+++ b/products/workflows/backend/presentation/views/workflow_message_opt_outs.py@@ -0,0 +1,168 @@+import uuid+from typing import Any, cast++from django.db import models++from drf_spectacular.utils import OpenApiResponse, extend_schema+from rest_framework import serializers, status, viewsets+from rest_framework.permissions import IsAuthenticated+from rest_framework.request import Request+from rest_framework.response import Response++from posthog.auth import InternalAPIUser+from posthog.event_usage import report_team_action+from posthog.models import Team++from products.messaging.backend.facade.categories import MessageCategoryMissing, get_category+from products.messaging.backend.facade.preferences import (+ ALL_MESSAGE_PREFERENCE_CATEGORY_ID,+ MessageCategoryNotFound,+ PreferenceStatus,+ add_opt_out,+ preference_status,+ recipient_preferences,+)+from products.workflows.backend.facade.api import WorkflowNotFound, get_workflow_opt_out_category_ids+from products.workflows.backend.facade.service_jwt import WORKFLOW_MESSAGE_OPT_OUT_PURPOSE+from products.workflows.backend.facade.workflows import ALL_MARKETING_CATEGORY_ID+from products.workflows.backend.presentation.views.workflow_step_auth import WorkflowStepJWTAuthentication+++class WorkflowMessageOptOutJWTAuthentication(WorkflowStepJWTAuthentication):+ purpose = WORKFLOW_MESSAGE_OPT_OUT_PURPOSE+++class WorkflowMessageOptOutRequestSerializer(serializers.Serializer):+ category_id = serializers.CharField(+ max_length=64,+ help_text='ID of the message category to opt out of, or "$all" for all marketing messages.',+ )+ identifier = serializers.CharField(+ max_length=512,+ allow_blank=True,+ help_text="The recipient to opt out, usually the person's email address.",+ )+++class WorkflowMessageOptOutResult(models.TextChoices):+ OPTED_OUT = "opted_out", "Opted out"+ ALREADY_OPTED_OUT = "already_opted_out", "Already opted out"+ MISSING_IDENTIFIER = "missing_identifier", "Missing identifier"+ NOT_ON_SAVED_WORKFLOW = "not_on_saved_workflow", "Not on the saved workflow"+ CATEGORY_UNUSABLE = "category_unusable", "Category deleted or transactional"+ WORKFLOW_MISSING = "workflow_missing", "Workflow missing"+++class WorkflowMessageOptOutResponseSerializer(serializers.Serializer):+ result = serializers.ChoiceField(+ choices=WorkflowMessageOptOutResult.choices, help_text="Machine-readable result of the opt-out."+ )+ detail = serializers.CharField(help_text="A short result message for the workflow log.")+++class _Refused(Exception):+ def __init__(self, result: WorkflowMessageOptOutResult, http_status: int, detail: str) -> None:+ self.result, self.http_status, self.detail = result, http_status, detail+++class WorkflowMessageOptOutViewSet(viewsets.GenericViewSet):+ """Opt the run's recipient out of a message category, for the workflow's "Opt out of messages" step.++ Authenticated by a scoped service JWT the plugin server mints. A test run or a draft sends its own copy of the+ step, so the endpoint only accepts a category the saved workflow names. Saving the step checked the access."""++ authentication_classes = [WorkflowMessageOptOutJWTAuthentication]+ permission_classes = [IsAuthenticated]+ serializer_class = WorkflowMessageOptOutRequestSerializer++ @extend_schema(+ request=WorkflowMessageOptOutRequestSerializer,+ responses={+ 200: WorkflowMessageOptOutResponseSerializer,+ **{+ code: OpenApiResponse(response=WorkflowMessageOptOutResponseSerializer) for code in (400, 403, 409, 422)+ },+ },+ summary="Opt a workflow recipient out of a message category",+ )+ def create(self, request: Request, **kwargs: Any) -> Response:+ # Both come from the verified token, not the URL or body.+ team_id = cast(int, cast(InternalAPIUser, request.user).current_team_id)+ hog_flow_id = cast(uuid.UUID, request.auth)+ serializer = WorkflowMessageOptOutRequestSerializer(data=request.data)+ serializer.is_valid(raise_exception=True)+ category_id: str = serializer.validated_data["category_id"]++ try:+ result, detail = _opt_out(team_id, hog_flow_id, category_id, serializer.validated_data["identifier"])+ http_status: int = status.HTTP_200_OK+ except _Refused as refused:+ result, detail, http_status = refused.result, refused.detail, refused.http_status+ report_team_action(+ Team.objects.get(id=team_id),+ "workflow opt out step ran",+ {+ "result": result,+ "all_marketing": category_id == ALL_MARKETING_CATEGORY_ID,+ "hog_flow_id": str(hog_flow_id),+ },+ )+ return Response(+ WorkflowMessageOptOutResponseSerializer({"result": result, "detail": detail}).data, status=http_status+ )+++def _opt_out(+ team_id: int, hog_flow_id: uuid.UUID, category_id: str, identifier: str+) -> tuple[WorkflowMessageOptOutResult, str]:+ if not identifier:+ raise _Refused(+ WorkflowMessageOptOutResult.MISSING_IDENTIFIER,+ status.HTTP_400_BAD_REQUEST,+ "There is no email to opt out. Check the step's recipient field, for example {person.properties.email}.",+ )+ try:+ allowed_category_ids = get_workflow_opt_out_category_ids(team_id=team_id, workflow_id=hog_flow_id)+ except WorkflowNotFound:+ raise _Refused(+ WorkflowMessageOptOutResult.WORKFLOW_MISSING,+ status.HTTP_422_UNPROCESSABLE_ENTITY,+ "Workflow no longer exists.",+ )+ if category_id not in allowed_category_ids:+ raise _Refused(+ WorkflowMessageOptOutResult.NOT_ON_SAVED_WORKFLOW,+ status.HTTP_403_FORBIDDEN,+ "The saved workflow doesn't opt people out of this category. Save or publish the workflow, then try again.",+ )++ unusable = _Refused(+ WorkflowMessageOptOutResult.CATEGORY_UNUSABLE,+ status.HTTP_409_CONFLICT,+ "The message category was deleted or is transactional. Choose a marketing category in the step.",+ )+ if category_id == ALL_MARKETING_CATEGORY_ID:+ category_key, preference_id, label = None, ALL_MESSAGE_PREFERENCE_CATEGORY_ID, "all marketing messages"+ else:+ try:+ category = get_category(team_id, category_id)+ except MessageCategoryMissing:+ raise unusable+ # Transactional sends ignore opt-outs, so an opt-out there would report success and change nothing.+ if category.category_type != "marketing":+ raise unusable+ category_key, preference_id, label = category.key, str(category.id), category.name++ preferences = recipient_preferences(team_id, identifier) or {}+ try:+ already_opted_out = preference_status(preferences, preference_id) == PreferenceStatus.OPTED_OUT+ except ValueError:+ already_opted_out = False+ # Opt out even when already opted out, so a retry after a failed Customer.io sync queues that sync again.+ try:+ add_opt_out(team_id, identifier, category_key, created_by_id=None)+ except MessageCategoryNotFound:+ raise unusable+ if already_opted_out:+ return WorkflowMessageOptOutResult.ALREADY_OPTED_OUT, f"Already opted out of {label}."+ return WorkflowMessageOptOutResult.OPTED_OUT, f"Opted out of {label}."diff --git a/products/workflows/backend/routes.py b/products/workflows/backend/routes.pyindex af65ad870b57..ebd9c987c400 100644--- a/products/workflows/backend/routes.py+++ b/products/workflows/backend/routes.py@@ -12,6 +12,7 @@ from products.workflows.backend.presentation.views import (people_imports,workflow_classifications,workflow_data_suggestions,+ workflow_message_opt_outs,workflow_scout_runs,workflow_sending_rules,workflow_setup,@@ -86,6 +87,12 @@ def register_routes(routers: RouterRegistry) -> None:"project_workflow_static_cohort_members",["team_id"],)+ routers.projects.register(+ r"workflow_message_opt_outs",+ workflow_message_opt_outs.WorkflowMessageOptOutViewSet,+ "project_workflow_message_opt_outs",+ ["team_id"],+ )routers.projects.register(r"hog_flow_templates",hog_flow_template.HogFlowTemplateViewSet,diff --git a/products/workflows/backend/service_jwt.py b/products/workflows/backend/service_jwt.pyindex 29f9bdd3dbf2..f71f11671162 100644--- a/products/workflows/backend/service_jwt.py+++ b/products/workflows/backend/service_jwt.py@@ -34,3 +34,9 @@ WORKFLOW_ADD_TO_STATIC_COHORT_PURPOSE = ScopedServiceJwtPurpose(audience=PosthogJwtAudience.WORKFLOW_ADD_TO_STATIC_COHORT,settings_name="WORKFLOW_ADD_TO_STATIC_COHORT_JWT_SECRETS",)++# Its own key, for the same narrowest-scope reason as WORKFLOW_SCOUT_RUN_PURPOSE.+WORKFLOW_MESSAGE_OPT_OUT_PURPOSE = ScopedServiceJwtPurpose(+ audience=PosthogJwtAudience.WORKFLOW_MESSAGE_OPT_OUT,+ settings_name="WORKFLOW_MESSAGE_OPT_OUT_JWT_SECRETS",+)diff --git a/products/workflows/backend/tests/api/test_hog_flow.py b/products/workflows/backend/tests/api/test_hog_flow.pyindex 3e9d032cc8b3..24c44f55ef75 100644--- a/products/workflows/backend/tests/api/test_hog_flow.py+++ b/products/workflows/backend/tests/api/test_hog_flow.py@@ -4,7 +4,7 @@ from datetime import UTC, datetime, timedeltafrom io import StringIOfrom types import SimpleNamespacefrom typing import Any, Optional-from uuid import uuid4+from uuid import UUID, uuid4from posthog.test.base import APIBaseTest, ClickhouseTestMixinfrom unittest.mock import ANY, MagicMock, patch@@ -37,6 +37,8 @@ from products.cdp.backend.templates.fixtures import template_slackfrom products.cdp.backend.templates.hog_function_template import sync_template_to_dbfrom products.cohorts.backend.models.cohort import Cohort, CohortTypefrom products.feature_flags.backend.user_blast_radius import BlastRadiusResult+from products.messaging.backend.facade.categories import update_category+from products.messaging.backend.facade.testing import create_message_category_for_testfrom products.replay_vision.backend.models.replay_scanner import ReplayScannerfrom products.replay_vision.backend.tests.helpers import create_experimentfrom products.skills.backend.models.skills import LLMSkill@@ -8604,3 +8606,99 @@ class TestAddToStaticCohortActionValidation(APIBaseTest):)assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()+++class TestOptOutOfMessagesActionValidation(APIBaseTest):+ def setUp(self):+ super().setUp()+ template = deepcopy(webhook_template)+ template["id"] = "template-posthog-opt-out-of-messages"+ template["inputs_schema"] = [+ {"key": "category_id", "type": "string", "label": "Message category", "required": True},+ {"key": "identifier", "type": "string", "label": "Recipient", "required": True},+ ]+ sync_template_to_db(template)++ def _step(self, category_id: str | None) -> dict:+ inputs: dict = {"identifier": {"value": "{person.properties.email}"}}+ if category_id is not None:+ inputs["category_id"] = {"value": category_id}+ return {+ "id": "opt_out",+ "name": "opt_out",+ "type": "function",+ "config": {"template_id": "template-posthog-opt-out-of-messages", "inputs": inputs},+ }++ def _request(self, method: str, path: str, data: dict, strict: bool = True):+ with patch("products.workflows.backend.presentation.views.hog_flow.gated_template_enabled", return_value=True):+ return getattr(self.client, method)(+ f"/api/projects/{self.team.id}/hog_flows{path}",+ data,+ format="json",+ headers={"X-PostHog-Client": "mcp"} if strict else None,+ )++ def _category(self, category_type: str = "marketing") -> UUID:+ category_id = create_message_category_for_test(team_id=self.team.id, key="updates", name="Updates")+ if category_type != "marketing":+ update_category(self.team.id, category_id, {"category_type": category_type})+ return category_id++ @parameterized.expand(+ [+ ("all_marketing", "$all", status.HTTP_201_CREATED),+ ("marketing_category", "marketing", status.HTTP_201_CREATED),+ ("transactional_category", "transactional", status.HTTP_400_BAD_REQUEST),+ ("unknown_category", str(uuid4()), status.HTTP_400_BAD_REQUEST),+ ("no_category", None, status.HTTP_400_BAD_REQUEST),+ ]+ )+ def test_saving_the_step_needs_a_marketing_category_the_project_has(+ self, _name: str, category_id: str | None, expected: int+ ) -> None:+ if category_id in ("marketing", "transactional"):+ category_id = str(self._category(category_id))++ response = self._request("post", "", {"name": "Unsubscribe", "actions": [_TRIGGER, self._step(category_id)]})++ assert response.status_code == expected, response.json()++ @parameterized.expand([("draft_save", False), ("strict_save", True)])+ def test_a_workflow_only_editor_cannot_change_the_opt_out_list(self, _name: str, strict: bool) -> None:+ self.organization.available_product_features = [+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL}+ ]+ self.organization.save()+ AccessControl.objects.create(team=self.team, resource="hog_flow", access_level="viewer")+ flow = HogFlow.objects.create(+ team=self.team, name="Unsubscribe", trigger=_TRIGGER["config"], actions=[_TRIGGER]+ )+ AccessControl.objects.create(+ team=self.team,+ resource="hog_flow",+ resource_id=str(flow.id),+ access_level="editor",+ organization_member=self.organization_membership,+ )++ response = self._request("patch", f"/{flow.id}", {"actions": [_TRIGGER, self._step("$all")]}, strict=strict)++ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()+ assert "edit access to all workflows" in str(response.json()), response.json()++ @parameterized.expand([("deleted", {"deleted": True}), ("made_transactional", {"category_type": "transactional"})])+ def test_enabling_rechecks_a_category_the_draft_already_saved(self, _name: str, change: dict) -> None:+ category_id = self._category()+ flow = HogFlow.objects.create(+ team=self.team,+ name="Unsubscribe",+ trigger=_TRIGGER["config"],+ actions=[_TRIGGER, self._step(str(category_id))],+ edges=[],+ )+ update_category(self.team.id, category_id, change)++ response = self._request("patch", f"/{flow.id}", {"status": "active"})++ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()diff --git a/products/workflows/backend/tests/api/test_workflow_message_opt_outs_api.py b/products/workflows/backend/tests/api/test_workflow_message_opt_outs_api.pynew file mode 100644index 000000000000..566c576326ef--- /dev/null+++ b/products/workflows/backend/tests/api/test_workflow_message_opt_outs_api.py@@ -0,0 +1,125 @@+from datetime import timedelta+from typing import Any+from uuid import UUID++from posthog.test.base import APIBaseTest+from unittest.mock import patch++from django.test import override_settings++from parameterized import parameterized+from rest_framework import status++from posthog.jwt import PosthogJwtAudience, encode_jwt+from posthog.test.authentication_checks import covers_authentication++from products.messaging.backend.facade.categories import update_category+from products.messaging.backend.facade.preferences import add_opt_out, list_opt_outs, recipient_preferences+from products.messaging.backend.facade.testing import create_message_category_for_test+from products.workflows.backend.models import HogFlow+from products.workflows.backend.presentation.views.workflow_message_opt_outs import (+ WorkflowMessageOptOutJWTAuthentication,+)++SECRET = "test-workflow-message-opt-out-jwt"+_VIEW = "products.workflows.backend.presentation.views.workflow_message_opt_outs"+++def _step(category_id: str) -> dict[str, Any]:+ return {+ "id": "opt_out",+ "name": "opt_out",+ "type": "function",+ "config": {+ "template_id": "template-posthog-opt-out-of-messages",+ "inputs": {"category_id": {"value": category_id}, "identifier": {"value": "{person.properties.email}"}},+ },+ }+++# Both settings share a value so the audience is the only thing that differs in the wrong-audience case.+@override_settings(WORKFLOW_MESSAGE_OPT_OUT_JWT_SECRETS=[SECRET], WORKFLOW_ADD_TO_STATIC_COHORT_JWT_SECRETS=[SECRET])+class TestWorkflowMessageOptOutsAPI(APIBaseTest):+ def setUp(self) -> None:+ super().setUp()+ self.client.logout()+ self.category_id = str(create_message_category_for_test(team_id=self.team.id, key="updates", name="Updates"))+ self.hog_flow = HogFlow.objects.create(+ team=self.team,+ name="Unsubscribe",+ created_by=self.user,+ trigger={"type": "manual"},+ actions=[_step(self.category_id), _step("$all")],+ )++ def _post(+ self,+ *,+ category_id: str | None = None,+ identifier: str = "[email protected]",+ audience: PosthogJwtAudience = PosthogJwtAudience.WORKFLOW_MESSAGE_OPT_OUT,+ ) -> Any:+ token = encode_jwt(+ {"team_id": self.team.id, "hog_flow_id": str(self.hog_flow.id)},+ timedelta(minutes=5),+ audience,+ signing_key=SECRET,+ )+ return self.client.post(+ f"/api/projects/{self.team.id}/workflow_message_opt_outs/",+ {"category_id": category_id or self.category_id, "identifier": identifier},+ format="json",+ HTTP_AUTHORIZATION=f"Bearer {token}",+ )++ def _opted_out(self, category_key: str | None) -> list[str]:+ return [row.identifier for row in list_opt_outs(self.team.id, category_key, None)]++ @parameterized.expand([("one_category", None, "updates"), ("all_marketing", "$all", None)])+ @covers_authentication(WorkflowMessageOptOutJWTAuthentication)+ def test_opting_out_twice_leaves_one_opt_out(+ self, _name: str, category_id: str | None, category_key: str | None+ ) -> None:+ with patch(f"{_VIEW}.add_opt_out", wraps=add_opt_out) as opt_out:+ first = self._post(category_id=category_id)+ second = self._post(category_id=category_id)++ # The repeat still writes, so a retry after a failed Customer.io sync queues the sync again.+ assert opt_out.call_count == 2++ assert first.status_code == status.HTTP_200_OK, first.json()+ assert first.json()["result"] == "opted_out"+ assert second.status_code == status.HTTP_200_OK, second.json()+ assert second.json()["result"] == "already_opted_out"+ assert self._opted_out(category_key) == ["[email protected]"]++ def test_a_token_for_another_step_is_rejected(self) -> None:+ response = self._post(audience=PosthogJwtAudience.WORKFLOW_ADD_TO_STATIC_COHORT)++ assert response.status_code in (status.HTTP_401_UNAUTHORIZED, status.HTTP_403_FORBIDDEN), response.json()+ assert self._opted_out("updates") == []++ @parameterized.expand(+ [+ ("category_not_on_the_saved_workflow", "other", "[email protected]", status.HTTP_403_FORBIDDEN),+ ("deleted_category", "deleted", "[email protected]", status.HTTP_409_CONFLICT),+ ("empty_identifier", None, " ", status.HTTP_400_BAD_REQUEST),+ ("transactional_category", "transactional", "[email protected]", status.HTTP_409_CONFLICT),+ ]+ )+ def test_refuses_without_opting_anyone_out(+ self, _name: str, category_change: str | None, identifier: str, expected: int+ ) -> None:+ category_id = None+ if category_change == "other":+ category_id = str(create_message_category_for_test(team_id=self.team.id, key="other", name="Other"))+ elif category_change == "deleted":+ update_category(self.team.id, UUID(self.category_id), {"deleted": True})+ elif category_change == "transactional":+ update_category(self.team.id, UUID(self.category_id), {"category_type": "transactional"})++ response = self._post(category_id=category_id, identifier=identifier)++ assert response.status_code == expected, response.json()+ assert response.json()["detail"]+ assert recipient_preferences(self.team.id, "[email protected]") is None