Skip to content

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

feat(workflows): add the backend for an opt out of messages step (#121238)

Harley Alexander92af9b7e486a
diff --git a/posthog/jwt.py b/posthog/jwt.py
index 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.py
index 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 every
diff --git a/products/cdp/backend/flag_gated_templates.py b/products/cdp/backend/flag_gated_templates.py
index 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.py
index 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 timezone
from 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.py
index 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.py
index 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_ids
from products.workflows.backend.services.batch_jobs import create_batch_job
from 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[in
return 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.py
index 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.py
index 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.py
index 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 Iterator
from typing import TYPE_CHECKING, Any, Final
from 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":
continue
config = 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 a
diff --git a/products/workflows/backend/presentation/views/hog_flow.py b/products/workflows/backend/presentation/views/hog_flow.py
index 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_category
from products.messaging.backend.presentation.views.serializers import DesignOperationSerializer
from products.notifications.backend.facade.api import publish_resource_edited
from 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, matching
the 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.py
new file mode 100644
index 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.py
index 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.py
index 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.py
index 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, timedelta
from io import StringIO
from types import SimpleNamespace
from typing import Any, Optional
-from uuid import uuid4
+from uuid import UUID, uuid4
from posthog.test.base import APIBaseTest, ClickhouseTestMixin
from unittest.mock import ANY, MagicMock, patch
@@ -37,6 +37,8 @@ from products.cdp.backend.templates.fixtures import template_slack
from products.cdp.backend.templates.hog_function_template import sync_template_to_db
from products.cohorts.backend.models.cohort import Cohort, CohortType
from 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_test
from products.replay_vision.backend.models.replay_scanner import ReplayScanner
from products.replay_vision.backend.tests.helpers import create_experiment
from 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.py
new file mode 100644
index 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