: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 transactional email log api (#127746)
Daniel Marchukd141e959089f
diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.pyindex 09c8a1cbd802..4ccec6f91f8f 100644--- a/products/messaging/backend/facade/contracts.py+++ b/products/messaging/backend/facade/contracts.py@@ -233,3 +233,80 @@ class EmailStatus:status_at: datetime# Why a send failed, or the bounce type of a bounced email.reason: str | None = None+++class EmailLogEventKind(LabeledStrEnum):+ QUEUED = "queued", "Queued"+ FAILED = "failed", "Failed"+ SENT = "sent", "Sent"+ DELIVERED = "delivered", "Delivered"+ BOUNCED = "bounced", "Bounced"+ COMPLAINED = "complained", "Complained"+ OPENED = "opened", "Opened"+ CLICKED = "clicked", "Clicked"+++class EmailStatsGroupBy(LabeledStrEnum):+ TEMPLATE = "template", "Template"+ SENDING_DOMAIN = "sending_domain", "Sending domain"+++@frozen+class TransactionalEmailLogEntry:+ message_id: str+ created_at: datetime+ status: EmailDeliveryStatus+ status_at: datetime+ # Why a send failed, or the bounce type of a bounced email.+ reason: str | None+ recipient: str+ workflow_id: str+ template_id: str | None+ # Empty when the template was deleted.+ template_name: str+ sending_domain: str+ opened: bool+ clicked: bool+++@frozen+class TransactionalEmailLogEvent:+ kind: EmailLogEventKind+ at: datetime+ reason: str | None+++@frozen+class TransactionalEmailLogDetail:+ entry: TransactionalEmailLogEntry+ timeline: list[TransactionalEmailLogEvent]+ # Empty when the send never reached the provider, so nothing was rendered.+ subject: str+ distinct_id: str+ # The step that sent the email, which the rendered email is stored under. Empty when none was stored.+ action_id: str+ # True when the template keeps no rendered body.+ sensitive: bool+++@frozen+class TransactionalEmailStatsRow:+ # The template id or the sending domain.+ key: str+ label: str+ sent: int+ delivered: int+ bounced: int+ complained: int+ opened: int+ clicked: int+ failed: int+++@frozen+class TransactionalEmailResults:+ recipients: int+ converted: int+ revenue: float+ # Hours from the send to the first conversion, for the median converted recipient. None when nobody converted.+ median_hours_to_convert: float | Nonediff --git a/products/messaging/backend/facade/transactional_email_log.py b/products/messaging/backend/facade/transactional_email_log.pynew file mode 100644index 000000000000..9cf31fbf50f4--- /dev/null+++ b/products/messaging/backend/facade/transactional_email_log.py@@ -0,0 +1,19 @@+"""The transactional email log: every send of a project, its timeline, and its delivery stats."""++from products.messaging.backend.models.email_status_sql import EMAIL_STATUS_RETENTION_DAYS+from products.messaging.backend.services.transactional_email_log import (+ MAX_CONVERSION_WINDOW_DAYS,+ get_transactional_email,+ list_transactional_emails,+ transactional_email_results,+ transactional_email_stats,+)++__all__ = [+ "EMAIL_STATUS_RETENTION_DAYS",+ "MAX_CONVERSION_WINDOW_DAYS",+ "get_transactional_email",+ "list_transactional_emails",+ "transactional_email_results",+ "transactional_email_stats",+]diff --git a/products/messaging/backend/presentation/query_concurrency.py b/products/messaging/backend/presentation/query_concurrency.pynew file mode 100644index 000000000000..df7156e180be--- /dev/null+++ b/products/messaging/backend/presentation/query_concurrency.py@@ -0,0 +1,41 @@+from collections.abc import Iterator+from contextlib import contextmanager++from django.conf import settings++from rest_framework.exceptions import Throttled++from posthog.api.query import CONCURRENCY_LIMIT_RETRY_AFTER_SECONDS, CONCURRENCY_LIMIT_USER_MESSAGE+from posthog.clickhouse.client.limit import (+ ConcurrencyLimitExceeded,+ app_org_concurrency_slot,+ get_api_team_rate_limiter,+)+from posthog.clickhouse.query_tagging import get_query_tag_value, is_api_key_access_method+from posthog.constants import AvailableFeature+from posthog.models.team import Team+++def _api_key_concurrency_limit(team: Team) -> int | None:+ if not settings.EE_AVAILABLE or not settings.API_QUERIES_ENABLED:+ return None+ feature = team.organization.get_available_feature(AvailableFeature.API_QUERIES_CONCURRENCY)+ return feature.get("limit") if feature else None+++@contextmanager+def query_concurrency_slots(team: Team) -> Iterator[None]:+ """Hold the slots a query runner holds, so the log's reads count against the same limits as a query."""+ is_api_key_access = is_api_key_access_method(get_query_tag_value("access_method"))+ try:+ with (+ get_api_team_rate_limiter().run(+ is_api=is_api_key_access,+ team_id=team.pk,+ limit=_api_key_concurrency_limit(team) if is_api_key_access else None,+ ),+ app_org_concurrency_slot(team),+ ):+ yield+ except ConcurrencyLimitExceeded as error:+ raise Throttled(wait=CONCURRENCY_LIMIT_RETRY_AFTER_SECONDS, detail=CONCURRENCY_LIMIT_USER_MESSAGE) from errordiff --git a/products/messaging/backend/presentation/views/transactional_email_log.py b/products/messaging/backend/presentation/views/transactional_email_log.pynew file mode 100644index 000000000000..2c8dafad1b07--- /dev/null+++ b/products/messaging/backend/presentation/views/transactional_email_log.py@@ -0,0 +1,321 @@+from dataclasses import asdict+from typing import Any, cast+from uuid import UUID++from drf_spectacular.openapi import AutoSchema+from drf_spectacular.types import OpenApiTypes+from drf_spectacular.utils import OpenApiParameter, OpenApiResponse, extend_schema+from rest_framework import serializers, viewsets+from rest_framework.decorators import action+from rest_framework.exceptions import NotFound+from rest_framework.request import Request+from rest_framework.response import Response++from posthog.api.mixins import ValidatedRequest, validated_request+from posthog.api.routing import TeamAndOrgViewSetMixin+from posthog.models import User++from products.messaging.backend.facade.contracts import (+ EmailDeliveryStatus,+ EmailLogEventKind,+ EmailStatsGroupBy,+ TransactionalEmailLogEntry,+)+from products.messaging.backend.facade.transactional_email_log import (+ EMAIL_STATUS_RETENTION_DAYS,+ MAX_CONVERSION_WINDOW_DAYS,+ get_transactional_email,+ list_transactional_emails,+ transactional_email_results,+ transactional_email_stats,+)+from products.messaging.backend.presentation.query_concurrency import query_concurrency_slots+from products.messaging.backend.presentation.views.message_templates import require_transactional_email_api+from products.workflows.backend.facade.api import get_workflow_view_access+from products.workflows.backend.facade.contracts import WorkflowViewAccess++RETENTION_NOTE = f"The log keeps sends for {EMAIL_STATUS_RETENTION_DAYS} days."+++class DateRangeQuerySerializer(serializers.Serializer):+ date_from = serializers.DateTimeField(+ required=False,+ help_text=f"Only sends queued at or after this time. Defaults to 7 days ago. {RETENTION_NOTE}",+ )+ date_to = serializers.DateTimeField(+ required=False, help_text="Only sends queued before this time. Defaults to now."+ )+++class TransactionalEmailLogListQuerySerializer(DateRangeQuerySerializer):+ search = serializers.CharField(+ required=False,+ allow_blank=True,+ help_text="A `message_id` for an exact match, or part of the recipient's email address.",+ )+ status = serializers.ChoiceField(+ choices=EmailDeliveryStatus.choices, required=False, help_text="Only sends in this delivery status."+ )+ workflow_id = serializers.UUIDField(+ required=False, help_text="Only sends of the transactional email backed by this workflow."+ )+ limit = serializers.IntegerField(required=False, default=50, min_value=1, max_value=200, help_text="Page size.")+ offset = serializers.IntegerField(required=False, default=0, min_value=0, help_text="Sends to skip.")+++class TransactionalEmailLogEntrySerializer(serializers.Serializer):+ message_id = serializers.CharField(help_text="The `message_id` that the send returned.")+ created_at = serializers.DateTimeField(help_text="When the send was queued.")+ status = serializers.ChoiceField(+ choices=EmailDeliveryStatus.choices,+ help_text="The email's delivery status. `queued` waits to go out, `sent` reached the email provider, "+ "`delivered` was accepted by the recipient's mail server, `bounced` and `complained` came back later, and "+ "`failed` was not sent.",+ )+ status_at = serializers.DateTimeField(help_text="When the email reached its delivery status.")+ reason = serializers.CharField(+ allow_null=True, help_text="Why a failed email was not sent, or the bounce type. Null otherwise."+ )+ recipient = serializers.CharField(help_text="The address the email was sent to.")+ workflow_id = serializers.CharField(help_text="The workflow behind the transactional email.")+ template_id = serializers.CharField(+ allow_null=True, help_text="The transactional email template. Null when it no longer exists."+ )+ template_name = serializers.CharField(help_text="The template's name. Empty when it was deleted.")+ sending_domain = serializers.CharField(help_text="The domain the email was sent from. Empty before it was sent.")+ opened = serializers.BooleanField(help_text="Whether the recipient opened the email.")+ clicked = serializers.BooleanField(help_text="Whether the recipient clicked a link in the email.")+++class TransactionalEmailLogListSerializer(serializers.Serializer):+ results = TransactionalEmailLogEntrySerializer(many=True, help_text="Sends, newest first.")+ has_more = serializers.BooleanField(help_text="Whether another page follows.")+++class TransactionalEmailLogEventSerializer(serializers.Serializer):+ kind = serializers.ChoiceField(+ choices=EmailLogEventKind.choices,+ help_text="What happened. The delivery statuses, plus `opened` and `clicked` for what the recipient did.",+ )+ at = serializers.DateTimeField(help_text="When it happened.")+ reason = serializers.CharField(allow_null=True, help_text="Why a send failed, or the bounce type. Null otherwise.")+++class TransactionalEmailLogDetailSerializer(TransactionalEmailLogEntrySerializer):+ timeline = TransactionalEmailLogEventSerializer(many=True, help_text="Everything that happened, oldest first.")+ subject = serializers.CharField(help_text="The subject the email went out with. Empty when it was never sent.")+ distinct_id = serializers.CharField(help_text="The distinct ID the send named. Empty when it named none.")+ action_id = serializers.CharField(+ help_text="The workflow step that sent the email, which the rendered email is stored under. Empty when no "+ "rendered email was stored."+ )+ sensitive = serializers.BooleanField(+ help_text="True when the template is marked sensitive, so no rendered body or subject values are kept."+ )+++class TransactionalEmailStatsQuerySerializer(DateRangeQuerySerializer):+ group_by = serializers.ChoiceField(+ choices=EmailStatsGroupBy.choices,+ default=EmailStatsGroupBy.TEMPLATE,+ help_text="Count per template or per sending domain.",+ )+++class TransactionalEmailStatsRowSerializer(serializers.Serializer):+ key = serializers.CharField(help_text="The template ID or the sending domain.")+ label = serializers.CharField( # type: ignore[assignment]+ help_text="The template name or the sending domain. Empty for a deleted template."+ )+ sent = serializers.IntegerField(help_text="Emails that reached the email provider.")+ delivered = serializers.IntegerField(help_text="Emails the recipient's mail server accepted.")+ bounced = serializers.IntegerField(help_text="Emails that bounced.")+ complained = serializers.IntegerField(help_text="Emails the recipient marked as spam.")+ opened = serializers.IntegerField(help_text="Emails the recipient opened.")+ clicked = serializers.IntegerField(help_text="Emails where the recipient clicked a link.")+ failed = serializers.IntegerField(help_text="Emails that were not sent.")+++class TransactionalEmailStatsSerializer(serializers.Serializer):+ results = TransactionalEmailStatsRowSerializer(many=True, help_text="One row per group, busiest first.")+++class TransactionalEmailResultsQuerySerializer(DateRangeQuerySerializer):+ workflow_id = serializers.UUIDField(help_text="The workflow behind the transactional email.")+ event = serializers.CharField(help_text="The event that counts as a conversion, such as `signed_up`.")+ window_days = serializers.IntegerField(+ required=False,+ default=7,+ min_value=1,+ max_value=MAX_CONVERSION_WINDOW_DAYS,+ help_text="How many days after the first send the event still counts.",+ )+ revenue_property = serializers.CharField(+ required=False, allow_blank=True, help_text="An event property holding a revenue amount to add up."+ )+++class TransactionalEmailResultsSerializer(serializers.Serializer):+ recipients = serializers.IntegerField(help_text="People the email was sent to in the date range.")+ converted = serializers.IntegerField(help_text="Of those, people who did the event within the window.")+ revenue = serializers.FloatField(help_text="The sum of the revenue property on those events.")+ median_hours_to_convert = serializers.FloatField(+ allow_null=True, help_text="Median hours from the first send to the first conversion. Null when none converted."+ )+++def _entry_data(entry: TransactionalEmailLogEntry) -> dict[str, Any]:+ return {+ "message_id": entry.message_id,+ "created_at": entry.created_at,+ "status": entry.status.value,+ "status_at": entry.status_at,+ "reason": entry.reason,+ "recipient": entry.recipient,+ "workflow_id": entry.workflow_id,+ "template_id": entry.template_id,+ "template_name": entry.template_name,+ "sending_domain": entry.sending_domain,+ "opened": entry.opened,+ "clicked": entry.clicked,+ }+++class _PageSchema(AutoSchema):+ # The list returns one page object with `has_more`, so drf-spectacular must not wrap it in an array.+ def _is_list_view(self, serializer: object = None) -> bool:+ return False+++class TransactionalEmailLogViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):+ schema = _PageSchema()+ scope_object = "hog_flow"+ scope_object_read_actions = ["list", "retrieve", "stats", "results"]++ def initial(self, request: Request, *args: Any, **kwargs: Any) -> None:+ super().initial(request, *args, **kwargs)+ require_transactional_email_api(self.team)++ def dangerously_get_required_scopes(self, request: Request, view: Any) -> list[str] | None:+ # Sends name their recipients and distinct IDs, the person data the workflow invocation and asset endpoints guard.+ if self.action in ("list", "retrieve"):+ return ["hog_flow:read", "person:read"]+ # Results count any event the caller names, so they read event data the way a query does.+ if self.action == "results":+ return ["hog_flow:read", "query:read"]+ return None++ def _workflow_access(self) -> WorkflowViewAccess:+ # Sends inherit the access of the workflow behind their email.+ return get_workflow_view_access(team_id=self.team_id, user_access_control=self.user_access_control)++ @validated_request(+ query_serializer=TransactionalEmailLogListQuerySerializer,+ responses={200: OpenApiResponse(response=TransactionalEmailLogListSerializer)},+ summary="List transactional email sends",+ operation_id="transactional_email_log_list",+ description=f"List the project's transactional email sends, newest first. {RETENTION_NOTE}",+ )+ def list(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:+ query = request.validated_query_data+ with query_concurrency_slots(self.team):+ entries, has_more = list_transactional_emails(+ self.team_id,+ search=query.get("search"),+ status=EmailDeliveryStatus(query["status"]) if query.get("status") else None,+ workflow_id=str(query["workflow_id"]) if query.get("workflow_id") else None,+ date_from=query.get("date_from"),+ date_to=query.get("date_to"),+ limit=query["limit"],+ offset=query["offset"],+ access=self._workflow_access(),+ )+ return Response(+ TransactionalEmailLogListSerializer(+ {"results": [_entry_data(entry) for entry in entries], "has_more": has_more}+ ).data+ )++ @extend_schema(+ parameters=[+ OpenApiParameter(+ name="id",+ type=OpenApiTypes.UUID,+ location=OpenApiParameter.PATH,+ description="The `message_id` that the send returned.",+ )+ ],+ responses={+ 200: TransactionalEmailLogDetailSerializer,+ 404: OpenApiResponse(description="No send of this project has this ID, or it is older than the log keeps."),+ },+ summary="Get a transactional email send",+ description="Get one send with its timeline: when it was queued, sent, delivered, opened and clicked.",+ )+ def retrieve(self, request: Request, *args: Any, pk: str | None = None, **kwargs: Any) -> Response:+ try:+ message_id = UUID(str(pk))+ except ValueError:+ raise NotFound()+ detail = get_transactional_email(self.team_id, message_id, access=self._workflow_access())+ if detail is None:+ raise NotFound()+ data = {+ **_entry_data(detail.entry),+ "timeline": [+ {"kind": event.kind.value, "at": event.at, "reason": event.reason} for event in detail.timeline+ ],+ "subject": detail.subject,+ "distinct_id": detail.distinct_id,+ "action_id": detail.action_id,+ "sensitive": detail.sensitive,+ }+ return Response(TransactionalEmailLogDetailSerializer(data).data)++ @validated_request(+ query_serializer=TransactionalEmailStatsQuerySerializer,+ responses={200: OpenApiResponse(response=TransactionalEmailStatsSerializer)},+ summary="Get transactional email delivery stats",+ description="Count sends by delivery status, opens and clicks, per template or per sending domain.",+ )+ @action(detail=False, methods=["GET"])+ def stats(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:+ query = request.validated_query_data+ with query_concurrency_slots(self.team):+ rows = transactional_email_stats(+ self.team_id,+ EmailStatsGroupBy(query["group_by"]),+ date_from=query.get("date_from"),+ date_to=query.get("date_to"),+ access=self._workflow_access(),+ )+ return Response(TransactionalEmailStatsSerializer({"results": [asdict(row) for row in rows]}).data)++ @validated_request(+ query_serializer=TransactionalEmailResultsQuerySerializer,+ responses={+ 200: OpenApiResponse(response=TransactionalEmailResultsSerializer),+ 404: OpenApiResponse(description="The project has no such workflow, or the user may not view it."),+ },+ summary="Get what happened after a transactional email",+ description="Of the people a transactional email was sent to, count those who did an event within a window "+ "after their first send, and add up the revenue on those events.",+ )+ @action(detail=False, methods=["GET"])+ def results(self, request: ValidatedRequest, *args: Any, **kwargs: Any) -> Response:+ query = request.validated_query_data+ workflow_id = str(query["workflow_id"])+ if workflow_id not in self._workflow_access().viewable_ids:+ raise NotFound()+ with query_concurrency_slots(self.team):+ outcome = transactional_email_results(+ self.team,+ cast(User, request.user),+ workflow_id,+ query["event"],+ window_days=query["window_days"],+ revenue_property=query.get("revenue_property") or None,+ date_from=query.get("date_from"),+ date_to=query.get("date_to"),+ )+ return Response(TransactionalEmailResultsSerializer(asdict(outcome)).data)diff --git a/products/messaging/backend/routes.py b/products/messaging/backend/routes.pyindex 97aa185f092e..60be98827d07 100644--- a/products/messaging/backend/routes.py+++ b/products/messaging/backend/routes.py@@ -15,6 +15,7 @@ from products.messaging.backend.presentation.views.supabase_auth_emails import (SupabaseSendEmailHookView,)from products.messaging.backend.presentation.views.topic_preferences import TopicPreferencesViewSet+from products.messaging.backend.presentation.views.transactional_email_log import TransactionalEmailLogViewSetfrom products.messaging.backend.presentation.views.transactional_email_status import MessagingEmailsViewSetwebhook_urlpatterns: list[URLPattern] = [@@ -54,3 +55,6 @@ def register_routes(routers: RouterRegistry) -> None:routers.projects.register(r"messaging/preferences", TopicPreferencesViewSet, "project_messaging_set_preferences", ["team_id"])+ routers.projects.register(+ r"transactional_email_log", TransactionalEmailLogViewSet, "project_transactional_email_log", ["team_id"]+ )diff --git a/products/messaging/backend/services/transactional_email_log.py b/products/messaging/backend/services/transactional_email_log.pynew file mode 100644index 000000000000..f934cb4a29a4--- /dev/null+++ b/products/messaging/backend/services/transactional_email_log.py@@ -0,0 +1,525 @@+"""The transactional email log: every send of a project, read from the email_status_events table.++A send writes one row per status change. The queued row carries the recipient and the workflow, the sent row the+sending domain, and opens and clicks add rows of their own. The delivery status of a send is its highest-ranked+delivery row, so an open never hides a bounce.+"""++from collections.abc import Sequence+from datetime import UTC, datetime, timedelta+from statistics import median+from typing import Any, cast+from uuid import UUID++from posthog.hogql import ast+from posthog.hogql.query import execute_hogql_query++from posthog.clickhouse.client.connection import Workload+from posthog.clickhouse.client.execute import sync_execute+from posthog.clickhouse.query_tagging import Feature, Product, tag_queries+from posthog.dataclasses import frozen+from posthog.models import Team, User++from products.messaging.backend.facade.contracts import (+ EmailDeliveryStatus,+ EmailLogEventKind,+ EmailStatsGroupBy,+ TransactionalEmailLogDetail,+ TransactionalEmailLogEntry,+ TransactionalEmailLogEvent,+ TransactionalEmailResults,+ TransactionalEmailStatsRow,+)+from products.messaging.backend.models.email_status_sql import (+ EMAIL_ENGAGEMENT_STATUSES,+ EMAIL_STATUS_EVENTS_TABLE,+ EMAIL_STATUS_RETENTION_DAYS,+)+from products.messaging.backend.models.message_template import MessageTemplate+from products.messaging.backend.models.transactional_email_key import TransactionalEmailKey+from products.workflows.backend.facade.contracts import WorkflowViewAccess+from products.workflows.backend.facade.message_assets import (+ fetch_first_email_sends,+ fetch_message_assets_for_invocations,+)++RETENTION = timedelta(days=EMAIL_STATUS_RETENTION_DAYS)+# The send API stamps a message id with its own clock, which can run ahead of this one.+_CLOCK_SKEW = timedelta(minutes=5)+# A conversion window longer than this would reach past what the log keeps.+MAX_CONVERSION_WINDOW_DAYS = 30+# The results read at most this many recipients, newest sends first.+MAX_RESULTS_RECIPIENTS = 10_000++# A message's rows sit together in the table's sort key, so grouping can finish each message as it reads on.+_GROUP_AS_READ: dict[str, int] = {"optimize_aggregation_in_order": 1}+# Reading newest first is slow when few rows match, so a search reads in any order and sorts what it finds.+_SEARCH: dict[str, int] = {"optimize_read_in_order": 0}++_ENGAGEMENT = "(" + ", ".join(f"'{status}'" for status in EMAIL_ENGAGEMENT_STATUSES) + ")"++# One row per message. `argMaxIf` keeps the delivery status, and the `anyIf` columns read the one row that sets each.+_MESSAGE_COLUMNS = f"""+ message_id,+ min(created_at) AS queued_at,+ argMaxIf(status, version, status NOT IN {_ENGAGEMENT}) AS delivery_status,+ argMaxIf(status_at, version, status NOT IN {_ENGAGEMENT}) AS delivery_status_at,+ argMaxIf(reason, version, status NOT IN {_ENGAGEMENT}) AS delivery_reason,+ anyIf(recipient, recipient != '') AS message_recipient,+ anyIf(function_id, function_id != '') AS message_function_id,+ anyIf(sending_domain, sending_domain != '') AS message_sending_domain,+ countIf(status = 'opened') > 0 AS was_opened,+ countIf(status = 'clicked') > 0 AS was_clicked+""".strip()+++@frozen+class _Period:+ start: datetime+ end: datetime+++def _window(date_from: datetime | None, date_to: datetime | None) -> _Period:+ now = datetime.now(UTC)+ start = max(date_from or now - timedelta(days=7), now - RETENTION)+ # The send API stamps a message with its own clock, so "now" reaches a little ahead. A given end stays exact.+ end = min(date_to, now + _CLOCK_SKEW) if date_to else now + _CLOCK_SKEW+ return _Period(start=start, end=end)+++def _queued_at(message_id: UUID) -> datetime | None:+ """When a message was queued, which its id starts with, or None when the log can't hold a message with this id."""+ queued_ms = int.from_bytes(message_id.bytes[:6], "big")+ now = datetime.now(UTC)+ if not (now - RETENTION).timestamp() * 1000 <= queued_ms <= (now + _CLOCK_SKEW).timestamp() * 1000:+ return None+ return datetime.fromtimestamp(queued_ms / 1000, tz=UTC)+++def _execute(team_id: int, query: str, params: dict[str, Any], settings: dict[str, int] | None = None) -> list[tuple]:+ tag_queries(product=Product.MESSAGING, feature=Feature.QUERY)+ # The log is read by a person looking at the page, or by an agent answering one.+ return cast(+ list,+ sync_execute(+ query, {"team_id": team_id, **params}, settings=settings, workload=Workload.ONLINE, team_id=team_id+ ),+ )+++def _templates_by_workflow(team_id: int, workflow_ids: Sequence[str]) -> dict[str, MessageTemplate]:+ ids = [UUID(workflow_id) for workflow_id in set(workflow_ids) if _is_uuid(workflow_id)]+ if not ids:+ return {}+ templates = MessageTemplate.objects.filter(team_id=team_id, transactional_hog_flow_id__in=ids)+ return {str(template.transactional_hog_flow_id): template for template in templates}+++def _access_condition(column: str, access: WorkflowViewAccess, params: dict[str, Any]) -> str:+ if not access.can_view_deleted:+ params["viewable_workflows"] = list(access.viewable_ids)+ return f"{column} IN %(viewable_workflows)s"+ if not access.blocked_ids:+ return f"{column} != ''"+ params["blocked_workflows"] = list(access.blocked_ids)+ return f"{column} != '' AND {column} NOT IN %(blocked_workflows)s"+++def _sees_no_sends(access: WorkflowViewAccess | None) -> bool:+ return access is not None and not access.can_view_deleted and not access.viewable_ids+++def _code_send_keys(team_id: int, workflow_ids: Sequence[str]) -> dict[str, str]:+ """The `template_key` of each workflow behind a send from code, which has no template to name it."""+ ids = [UUID(workflow_id) for workflow_id in set(workflow_ids) if _is_uuid(workflow_id)]+ if not ids:+ return {}+ keys = TransactionalEmailKey.objects.for_team(team_id, canonical=True).filter(hog_flow_id__in=ids)+ return {str(hog_flow_id): key for hog_flow_id, key in keys.values_list("hog_flow_id", "key")}+++def _is_uuid(value: str) -> bool:+ try:+ UUID(value)+ except ValueError:+ return False+ return True+++def _build_entries(team_id: int, rows: list[tuple]) -> list[TransactionalEmailLogEntry]:+ templates = _templates_by_workflow(team_id, [row[6] for row in rows])+ code_send_keys = _code_send_keys(team_id, [row[6] for row in rows])+ entries = []+ for row in rows:+ (message_id, queued_at, status, status_at, reason, recipient, workflow_id, domain, opened, clicked) = row+ if status not in EmailDeliveryStatus.values:+ continue+ template = templates.get(workflow_id)+ if template and template.deleted:+ template = None+ entries.append(+ TransactionalEmailLogEntry(+ message_id=str(message_id),+ created_at=queued_at,+ status=EmailDeliveryStatus(status),+ status_at=status_at,+ reason=reason or None,+ recipient=recipient,+ workflow_id=workflow_id,+ template_id=str(template.id) if template else None,+ template_name=template.name if template else code_send_keys.get(workflow_id, ""),+ sending_domain=domain,+ opened=bool(opened),+ clicked=bool(clicked),+ )+ )+ return entries+++def list_transactional_emails(+ team_id: int,+ *,+ search: str | None = None,+ status: EmailDeliveryStatus | None = None,+ workflow_id: str | None = None,+ date_from: datetime | None = None,+ date_to: datetime | None = None,+ limit: int = 50,+ offset: int = 0,+ access: WorkflowViewAccess | None = None,+) -> tuple[list[TransactionalEmailLogEntry], bool]:+ """A page of the project's sends, newest first, and whether more follow. `access` limits the sends to the workflows+ the reader may view, and None reads them all."""+ if _sees_no_sends(access):+ return [], False+ period = _window(date_from, date_to)+ start, end = period.start, period.end+ period_filter = "team_id = %(team_id)s AND created_at >= %(start)s AND created_at < %(end)s"+ having = ["delivery_status != ''"]+ params: dict[str, Any] = {"start": start, "end": end, "limit": limit + 1, "offset": offset}+ # Only the queued row names the recipient and the workflow, so these filters pick messages from queued rows.+ queued_filters: list[str] = []+ settings: dict[str, int] = {}++ search = (search or "").strip()+ message_id = UUID(search) if search and _is_uuid(search) else None+ if message_id:+ sent_around = _queued_at(message_id)+ if sent_around is None:+ return [], False+ params["message_id"] = str(message_id)+ params["start"] = max(start, sent_around - _CLOCK_SKEW)+ params["end"] = min(end, sent_around + _CLOCK_SKEW)+ elif search:+ queued_filters.append("positionCaseInsensitive(recipient, %(search)s) > 0")+ params["search"] = search+ settings.update(_SEARCH)+ if status:+ having.append("delivery_status = %(status)s")+ params["status"] = status.value+ if workflow_id:+ queued_filters.append("function_id = %(workflow_id)s")+ having.append("message_function_id = %(workflow_id)s")+ params["workflow_id"] = workflow_id+ if access is not None:+ queued_filters.append(_access_condition("function_id", access, params))+ having.append(_access_condition("message_function_id", access, params))++ queued = " AND ".join([period_filter, "status = 'queued'", *queued_filters])+ candidates = f"SELECT created_at, message_id FROM {EMAIL_STATUS_EVENTS_TABLE} WHERE {queued}"+ if message_id:+ scope = "AND message_id = %(message_id)s"+ elif status:+ # A delivery status comes from all of a message's rows, so this reads every message in the period.+ settings.update(_GROUP_AS_READ)+ scope = f"AND (created_at, message_id) IN ({candidates})" if search or workflow_id else ""+ else:+ # The page comes from queued rows alone, so a long period doesn't group every message to show 50 of them.+ # Kafka can deliver a queued row twice, so this takes extra rows and the grouping below drops the repeats.+ params["candidates"] = (limit + 1 + offset) * 2+ scope = (+ f"AND (created_at, message_id) IN ({candidates} ORDER BY created_at DESC, message_id DESC"+ " LIMIT %(candidates)s)"+ )++ rows = _execute(+ team_id,+ f"""+ SELECT {_MESSAGE_COLUMNS}+ FROM {EMAIL_STATUS_EVENTS_TABLE}+ WHERE {period_filter} {scope}+ GROUP BY created_at, message_id+ HAVING {" AND ".join(having)}+ ORDER BY queued_at DESC, message_id DESC+ LIMIT %(limit)s OFFSET %(offset)s+ """,+ params,+ settings or None,+ )+ has_more = len(rows) > limit+ return _build_entries(team_id, rows[:limit]), has_more+++def get_transactional_email(+ team_id: int, message_id: UUID, *, access: WorkflowViewAccess | None = None+) -> TransactionalEmailLogDetail | None:+ """One send with every status it went through, or None when the project has no send with this id, or the reader+ may not view its workflow."""+ queued = _queued_at(message_id)+ if queued is None:+ return None+ params = {"message_id": str(message_id), "start": queued - _CLOCK_SKEW, "end": queued + _CLOCK_SKEW}+ where = "team_id = %(team_id)s AND message_id = %(message_id)s AND created_at >= %(start)s AND created_at < %(end)s"++ rows = _execute(+ team_id,+ f"SELECT {_MESSAGE_COLUMNS} FROM {EMAIL_STATUS_EVENTS_TABLE} WHERE {where} GROUP BY message_id",+ params,+ )+ entries = _build_entries(team_id, rows)+ if not entries or (access is not None and not access.allows(entries[0].workflow_id)):+ return None+ entry = entries[0]++ events = _execute(+ team_id,+ # Kafka can deliver a status twice, and this table keeps every row. A repeat has the same status and time.+ f"""+ SELECT status, status_at, reason FROM {EMAIL_STATUS_EVENTS_TABLE}+ WHERE {where}+ GROUP BY status, status_at, reason+ ORDER BY status_at, max(version)+ """,+ params,+ )+ timeline: list[TransactionalEmailLogEvent] = []+ for kind, at, reason in events:+ if kind not in EmailLogEventKind.values:+ continue+ # A failed email step also fails its run, and the run writes a second, vaguer failure. Show the first only.+ if kind == EmailLogEventKind.FAILED and timeline and timeline[-1].kind == EmailLogEventKind.FAILED:+ continue+ timeline.append(TransactionalEmailLogEvent(kind=EmailLogEventKind(kind), at=at, reason=reason or None))++ assets = fetch_message_assets_for_invocations(team_id, [entry.message_id], after=queued - _CLOCK_SKEW)+ asset = assets[0] if assets else None+ template = _templates_by_workflow(team_id, [entry.workflow_id]).get(entry.workflow_id)+ return TransactionalEmailLogDetail(+ entry=entry,+ timeline=timeline,+ subject=asset.subject if asset else "",+ distinct_id=asset.distinct_id if asset else "",+ # The stored copy opens through its workflow, so a deleted workflow's copy can't be shown.+ action_id=asset.action_id if asset and (access is None or entry.workflow_id in access.viewable_ids) else "",+ sensitive=bool(template and template.sensitive),+ )+++def transactional_email_stats(+ team_id: int,+ group_by: EmailStatsGroupBy,+ *,+ date_from: datetime | None = None,+ date_to: datetime | None = None,+ access: WorkflowViewAccess | None = None,+) -> list[TransactionalEmailStatsRow]:+ """How many sends reached each status, per template or per sending domain, busiest first."""+ if _sees_no_sends(access):+ return []+ period = _window(date_from, date_to)+ start, end = period.start, period.end+ params: dict[str, Any] = {"start": start, "end": end}+ access_filter = f"AND {_access_condition('message_function_id', access, params)}" if access is not None else ""+ group_column = "message_function_id" if group_by == EmailStatsGroupBy.TEMPLATE else "message_sending_domain"+ rows = _execute(+ team_id,+ f"""+ SELECT+ {group_column} AS group_key,+ countIf(delivery_status IN ('sent', 'delivered', 'bounced', 'complained')) AS sent,+ countIf(delivery_status IN ('delivered', 'complained')) AS delivered,+ countIf(delivery_status = 'bounced') AS bounced,+ countIf(delivery_status = 'complained') AS complained,+ countIf(was_opened) AS opened,+ countIf(was_clicked) AS clicked,+ countIf(delivery_status = 'failed') AS failed+ FROM (+ SELECT {_MESSAGE_COLUMNS}+ FROM {EMAIL_STATUS_EVENTS_TABLE}+ WHERE team_id = %(team_id)s AND created_at >= %(start)s AND created_at < %(end)s+ GROUP BY created_at, message_id+ )+ WHERE delivery_status != '' AND group_key != '' {access_filter}+ GROUP BY group_key+ ORDER BY sent + failed DESC, group_key+ LIMIT 200+ """,+ params,+ _GROUP_AS_READ,+ )+ templates = (+ _templates_by_workflow(team_id, [row[0] for row in rows]) if group_by == EmailStatsGroupBy.TEMPLATE else {}+ )+ code_send_keys = (+ _code_send_keys(team_id, [row[0] for row in rows]) if group_by == EmailStatsGroupBy.TEMPLATE else {}+ )+ stats = []+ for key, sent, delivered, bounced, complained, opened, clicked, failed in rows:+ template = templates.get(key)+ if group_by == EmailStatsGroupBy.TEMPLATE:+ label = template.name if template and not template.deleted else code_send_keys.get(key, "")+ key = str(template.id) if template else key+ else:+ label = key+ stats.append(+ TransactionalEmailStatsRow(+ key=key,+ label=label,+ sent=sent,+ delivered=delivered,+ bounced=bounced,+ complained=complained,+ opened=opened,+ clicked=clicked,+ failed=failed,+ )+ )+ return stats+++def transactional_email_results(+ team: Team,+ user: User | None,+ workflow_id: str,+ event: str,+ *,+ window_days: int = 7,+ revenue_property: str | None = None,+ date_from: datetime | None = None,+ date_to: datetime | None = None,+) -> TransactionalEmailResults:+ """Of the people a transactional email was sent to, how many did `event` within `window_days` of their first send,+ and the revenue those events carried."""+ tag_queries(product=Product.MESSAGING, feature=Feature.QUERY)+ period = _window(date_from, date_to)+ start, end = period.start, period.end+ window = timedelta(days=min(max(window_days, 1), MAX_CONVERSION_WINDOW_DAYS))+ sends = fetch_first_email_sends(team.id, workflow_id, start, end, limit=MAX_RESULTS_RECIPIENTS)+ if not sends:+ return TransactionalEmailResults(recipients=0, converted=0, revenue=0.0, median_hours_to_convert=None)++ # The same person can be reached under several distinct ids, so the send and the conversion meet on the person.+ person_by_distinct_id = _persons_for_distinct_ids(team, user, list(sends))+ first_send: dict[str, datetime] = {}+ for distinct_id, sent_at in sends.items():+ person = person_by_distinct_id.get(distinct_id, f"distinct:{distinct_id}")+ first_send[person] = min(first_send.get(person, sent_at), sent_at)++ conversions = _conversions(+ team, user, event, revenue_property, list(sends), first_send, window, start, end + window+ )+ converted_at = {person: conversion.first_at for person, conversion in conversions.items()}+ revenue = sum(conversion.revenue for conversion in conversions.values())++ hours = [(converted_at[person] - first_send[person]).total_seconds() / 3600 for person in converted_at]+ return TransactionalEmailResults(+ recipients=len(first_send),+ converted=len(converted_at),+ revenue=round(revenue, 2),+ median_hours_to_convert=round(median(hours), 2) if hours else None,+ )+++def _persons_for_distinct_ids(team: Team, user: User | None, distinct_ids: list[str]) -> dict[str, str]:+ response = execute_hogql_query(+ """+ SELECT distinct_id, toString(person_id) FROM person_distinct_ids+ WHERE distinct_id IN {distinct_ids}+ LIMIT {limit}+ """,+ team=team,+ user=user,+ placeholders={"distinct_ids": ast.Constant(value=distinct_ids), "limit": ast.Constant(value=len(distinct_ids))},+ query_type="transactional_email_results_persons",+ workload=Workload.ONLINE,+ )+ return dict(response.results or [])+++@frozen+class _Conversion:+ first_at: datetime+ revenue: float+++def _conversions(+ team: Team,+ user: User | None,+ event: str,+ revenue_property: str | None,+ distinct_ids: list[str],+ first_send: dict[str, datetime],+ window: timedelta,+ start: datetime,+ end: datetime,+) -> dict[str, _Conversion]:+ """Each recipient's first conversion within `window` of their first send, and the revenue of those conversions.++ ClickHouse does the windowing and the sums, so a recipient comes back as one row however many events they did. A+ recipient with no person profile is keyed by distinct ID, the same way `transactional_email_results` keys their send.+ """+ revenue: ast.Expr = (+ ast.Call(+ name="toFloatOrNull",+ args=[ast.Call(name="toString", args=[ast.Field(chain=["properties", revenue_property])])],+ )+ if revenue_property+ else ast.Constant(value=None)+ )+ recipients = list(first_send)+ response = execute_hogql_query(+ """+ SELECT conversions.recipient, min(conversions.timestamp), sum(conversions.value)+ FROM (+ SELECT+ if(person_id IN (SELECT person_id FROM person_distinct_ids WHERE distinct_id IN {distinct_ids}),+ toString(person_id), concat('distinct:', distinct_id)) AS recipient,+ timestamp,+ {revenue} AS value+ FROM events+ WHERE event = {event}+ AND timestamp >= {start} AND timestamp < {end}+ AND (distinct_id IN {distinct_ids}+ OR person_id IN (SELECT person_id FROM person_distinct_ids WHERE distinct_id IN {distinct_ids}))+ ) AS conversions+ INNER JOIN (+ SELECT tupleElement(send, 1) AS recipient, fromUnixTimestamp64Milli(tupleElement(send, 2)) AS sent_at+ FROM (SELECT arrayJoin(arrayZip({recipients}, {sent_at_ms})) AS send)+ ) AS sends ON conversions.recipient = sends.recipient+ WHERE conversions.timestamp >= sends.sent_at+ AND conversions.timestamp <= sends.sent_at + toIntervalSecond({window_seconds})+ GROUP BY conversions.recipient+ LIMIT {limit}+ """,+ team=team,+ user=user,+ placeholders={+ "revenue": revenue,+ "event": ast.Constant(value=event),+ "start": ast.Constant(value=start),+ "end": ast.Constant(value=end),+ "distinct_ids": ast.Constant(value=distinct_ids),+ "recipients": ast.Constant(value=recipients),+ "sent_at_ms": ast.Constant(+ value=[int(first_send[recipient].timestamp() * 1000) for recipient in recipients]+ ),+ "window_seconds": ast.Constant(value=int(window.total_seconds())),+ "limit": ast.Constant(value=len(recipients)),+ },+ query_type="transactional_email_results_conversions",+ workload=Workload.ONLINE,+ )+ return {+ recipient: _Conversion(first_at=first_at.astimezone(UTC), revenue=float(total or 0.0))+ for recipient, first_at, total in response.results or []+ }diff --git a/products/messaging/backend/tests/api/test_transactional_email_log.py b/products/messaging/backend/tests/api/test_transactional_email_log.pynew file mode 100644index 000000000000..c1e0ee65e323--- /dev/null+++ b/products/messaging/backend/tests/api/test_transactional_email_log.py@@ -0,0 +1,435 @@+from datetime import UTC, datetime, timedelta+from uuid import UUID++import time_machine+from posthog.test.base import APIBaseTest, ClickhouseTestMixin, _create_event, flush_persons_and_events+from unittest.mock import patch++from parameterized import parameterized+from rest_framework import status++from posthog.clickhouse.client.execute import sync_execute+from posthog.clickhouse.client.limit import ConcurrencyLimitExceeded+from posthog.constants import AvailableFeature+from posthog.models import OrganizationMembership, Team+from posthog.models.personal_api_key import PersonalAPIKey+from posthog.models.utils import generate_random_token_personal, hash_key_value+from posthog.test.persons import create_person+from posthog.uuidt import UUIDT++from products.access_control.backend.facade.testing import create_access_control+from products.messaging.backend.models.email_status_sql import EMAIL_STATUS_EVENTS_DATA_TABLE+from products.messaging.backend.models.message_template import MessageTemplate+from products.messaging.backend.models.transactional_email_key import TransactionalEmailKey+from products.workflows.backend.facade.testing import create_workflow_for_test+from products.workflows.backend.facade.writes import destroy_workflow++# `run_failed` is the failure the whole run writes, which ranks below the email step's own failure.+RANK = {+ "queued": 0,+ "run_failed": 1,+ "failed": 2,+ "sent": 3,+ "delivered": 5,+ "bounced": 6,+ "complained": 7,+ "opened": 8,+ "clicked": 9,+}+NOW = datetime(2026, 6, 15, 12, 0, 0, tzinfo=UTC)+++@time_machine.travel(NOW, tick=False)+@patch(+ "products.messaging.backend.presentation.views.message_templates.posthoganalytics.feature_enabled",+ return_value=True,+)+class TestTransactionalEmailLog(ClickhouseTestMixin, APIBaseTest):+ def setUp(self):+ super().setUp()+ self.workflow_id = create_workflow_for_test(team_id=self.team.id, name="Password reset").id+ self.template = MessageTemplate.objects.create(+ team=self.team, name="Password reset", transactional_hog_flow_id=self.workflow_id+ )++ def _send(+ self,+ minutes_ago: int,+ recipient: str,+ statuses: list[tuple[str, int, str]],+ *,+ team: Team | None = None,+ workflow_id: str | None = None,+ domain: str = "mail.example.com",+ ) -> str:+ queued_at = NOW - timedelta(minutes=minutes_ago)+ message_id = str(UUIDT(unix_time_ms=int(queued_at.timestamp() * 1000)))+ rows = [("queued", 0, ""), *statuses]+ sync_execute(+ f"""+ INSERT INTO {EMAIL_STATUS_EVENTS_DATA_TABLE}+ (team_id, message_id, status, version, created_at, status_at, reason, recipient, function_id,+ sending_domain, _timestamp, _offset, _partition)+ VALUES+ """,+ [+ {+ "team_id": (team or self.team).id,+ "message_id": message_id,+ "status": "failed" if row_status == "run_failed" else row_status,+ "version": RANK[row_status] * 2**48+ + int((queued_at + timedelta(seconds=seconds)).timestamp() * 1000),+ "created_at": queued_at,+ "status_at": queued_at + timedelta(seconds=seconds),+ "reason": reason,+ "recipient": recipient if row_status == "queued" else "",+ "function_id": (workflow_id or self.workflow_id) if row_status == "queued" else "",+ "sending_domain": domain if row_status == "sent" else "",+ "_timestamp": queued_at,+ "_offset": 0,+ "_partition": 0,+ }+ for row_status, seconds, reason in rows+ ],+ )+ return message_id++ def _url(self, suffix: str = "") -> str:+ return f"/api/projects/{self.team.id}/transactional_email_log/{suffix}"++ def test_lists_sends_newest_first_and_an_open_never_hides_a_bounce(self, _flag):+ oldest = self._send(30, "[email protected]", [("sent", 1, ""), ("delivered", 2, ""), ("opened", 60, "")])+ bounced = self._send(20, "[email protected]", [("sent", 1, ""), ("bounced", 2, "hard"), ("opened", 90, "")])+ newest = self._send(10, "[email protected]", [("sent", 1, ""), ("clicked", 30, "")])+ self._send(5, "[email protected]", [("sent", 1, "")], team=Team.objects.create(organization=self.organization))++ response = self.client.get(self._url())++ assert response.status_code == status.HTTP_200_OK, response.json()+ results = response.json()["results"]+ assert [(r["message_id"], r["status"], r["reason"], r["opened"], r["clicked"]) for r in results] == [+ (newest, "sent", None, False, True),+ (bounced, "bounced", "hard", True, False),+ (oldest, "delivered", None, True, False),+ ]+ assert results[0]["template_name"] == "Password reset"+ assert results[0]["sending_domain"] == "mail.example.com"++ @parameterized.expand(+ [+ ("part_of_the_recipient", {"search": "JANE"}, ["[email protected]"], False),+ ("status", {"status": "failed"}, ["[email protected]"], False),+ ("page_size", {"limit": 1}, ["[email protected]"], True),+ ("second_page", {"limit": 1, "offset": 1}, ["[email protected]"], False),+ ("search_and_status", {"search": "bob", "status": "failed"}, ["[email protected]"], False),+ ("search_with_no_match_for_the_status", {"search": "jane", "status": "failed"}, [], False),+ ("status_past_its_last_send", {"status": "sent", "offset": 1}, [], False),+ ]+ )+ def test_filters_the_list(self, _flag, _name, params, expected_recipients, expected_has_more):+ self._send(20, "[email protected]", [("sent", 1, "")])+ self._send(10, "[email protected]", [("failed", 1, "provider_error")])++ response = self.client.get(self._url(), params)++ assert [r["recipient"] for r in response.json()["results"]] == expected_recipients+ assert response.json()["has_more"] == expected_has_more++ def test_finds_a_send_by_message_id_only_inside_the_date_range(self, _flag):+ message_id = self._send(60, "[email protected]", [("sent", 1, "")])+ self._send(10, "[email protected]", [("sent", 1, "")])++ inside = self.client.get(self._url(), {"search": message_id}).json()+ outside = self.client.get(+ self._url(), {"search": message_id, "date_from": (NOW - timedelta(minutes=30)).isoformat()}+ ).json()++ assert [r["message_id"] for r in inside["results"]] == [message_id]+ assert outside["results"] == []++ @parameterized.expand(+ [+ ("list", ""),+ ("stats", "stats/?group_by=template"),+ ("results", "results/?event=purchase&workflow_id={workflow_id}"),+ ]+ )+ def test_a_full_query_slot_answers_429(self, _flag, _name, path):+ with patch(+ "products.messaging.backend.presentation.query_concurrency.app_org_concurrency_slot",+ side_effect=ConcurrencyLimitExceeded("Exceeded maximum concurrency limit"),+ ):+ response = self.client.get(self._url(path.format(workflow_id=self.workflow_id)))++ assert response.status_code == status.HTTP_429_TOO_MANY_REQUESTS, response.json()++ def test_shows_one_send_with_its_timeline(self, _flag):+ message_id = self._send(+ 10, "[email protected]", [("failed", 1, "provider_error"), ("run_failed", 2, "hog_error")]+ )++ response = self.client.get(self._url(f"{message_id}/"))++ assert response.status_code == status.HTTP_200_OK, response.json()+ body = response.json()+ assert (body["status"], body["reason"]) == ("failed", "provider_error")+ # A failed email step also fails its run, and that second failure says less.+ assert [(event["kind"], event["reason"]) for event in body["timeline"]] == [+ ("queued", None),+ ("failed", "provider_error"),+ ]++ def test_a_status_delivered_twice_shows_once(self, _flag):+ message_id = self._send(+ 10, "[email protected]", [("sent", 1, ""), ("clicked", 2, ""), ("clicked", 2, ""), ("clicked", 3, "")]+ )++ body = self.client.get(self._url(f"{message_id}/")).json()++ assert [event["kind"] for event in body["timeline"]] == ["queued", "sent", "clicked", "clicked"]++ def test_a_queued_row_delivered_twice_takes_one_place_on_a_page(self, _flag):+ self._send(20, "[email protected]", [("queued", 0, "")])+ self._send(10, "[email protected]", [("queued", 0, "")])++ first_page = self.client.get(self._url(), {"limit": 1}).json()+ second_page = self.client.get(self._url(), {"limit": 1, "offset": 1}).json()++ assert [r["recipient"] for r in first_page["results"]] == ["[email protected]"]+ assert first_page["has_more"] is True+ assert [r["recipient"] for r in second_page["results"]] == ["[email protected]"]+ assert second_page["has_more"] is False++ @parameterized.expand(+ [+ ("list", "", ["hog_flow:read"], "person:read"),+ ("retrieve", "{message_id}/", ["hog_flow:read"], "person:read"),+ (+ "results",+ "results/?event=purchase&workflow_id={workflow_id}",+ ["hog_flow:read", "person:read"],+ "query:read",+ ),+ ]+ )+ def test_a_token_needs_the_scope_for_the_data_it_reads(self, _flag, _name, path, scopes, missing_scope):+ message_id = self._send(10, "[email protected]", [("sent", 1, "")])+ key = generate_random_token_personal()+ PersonalAPIKey.objects.create(label="scoped", user=self.user, secure_value=hash_key_value(key), scopes=scopes)++ response = self.client.get(+ self._url(path.format(message_id=message_id, workflow_id=self.workflow_id)),+ headers={"authorization": f"Bearer {key}"},+ )++ assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()+ assert missing_scope in response.json()["detail"]++ @parameterized.expand([("another_projects_send", True), ("a_deleted_template", False)])+ def test_hides_what_the_project_cannot_see(self, _flag, _name, other_team):+ team = Team.objects.create(organization=self.organization) if other_team else None+ message_id = self._send(10, "[email protected]", [("sent", 1, "")], team=team)+ self.template.deleted = True+ self.template.save()++ response = self.client.get(self._url(f"{message_id}/"))++ if other_team:+ assert response.status_code == status.HTTP_404_NOT_FOUND+ else:+ assert (response.json()["template_id"], response.json()["template_name"]) == (None, "")++ def test_counts_sends_per_template_and_per_sending_domain(self, _flag):+ self._send(30, "[email protected]", [("sent", 1, ""), ("delivered", 2, ""), ("opened", 60, ""), ("opened", 90, "")])+ self._send(20, "[email protected]", [("sent", 1, ""), ("bounced", 2, "hard")], domain="other.example.com")+ self._send(10, "[email protected]", [("failed", 1, "provider_error")])++ by_template = self.client.get(self._url("stats/")).json()["results"]+ by_domain = self.client.get(self._url("stats/"), {"group_by": "sending_domain"}).json()["results"]++ assert [+ (r["key"], r["label"], r["sent"], r["delivered"], r["bounced"], r["opened"], r["failed"])+ for r in by_template+ ] == [(str(self.template.id), "Password reset", 2, 1, 1, 1, 1)]+ assert [(r["key"], r["sent"], r["bounced"]) for r in by_domain] == [+ ("mail.example.com", 1, 0),+ ("other.example.com", 1, 1),+ ]++ def test_counts_who_converted_within_the_window_after_their_first_send(self, _flag):+ for distinct_id, sent_minutes_ago in [+ ("converted", 600),+ ("too-late", 600 * 24),+ ("never", 60),+ ("personless", 600),+ ]:+ if distinct_id != "personless":+ create_person(team=self.team, distinct_ids=[distinct_id])+ sync_execute(+ """+ INSERT INTO message_assets_data+ (team_id, function_kind, function_id, parent_run_id, invocation_id, action_id, kind, distinct_id,+ person_id, recipient, subject, status, sent_at, version, is_deleted, html)+ VALUES+ """,+ [+ {+ "team_id": self.team.id,+ "function_kind": "hog_flow",+ "function_id": self.workflow_id,+ "parent_run_id": "",+ "invocation_id": str(UUIDT()),+ "action_id": "transactional_email",+ "kind": "email",+ "distinct_id": distinct_id,+ "person_id": "",+ "recipient": f"{distinct_id}@example.com",+ "subject": "Reset",+ "status": "sent",+ "sent_at": NOW - timedelta(minutes=sent_minutes_ago),+ "version": 1,+ "is_deleted": 0,+ "html": "",+ }+ ],+ )+ _create_event(+ team=self.team,+ event="purchase",+ distinct_id="converted",+ timestamp=NOW - timedelta(minutes=300),+ properties={"amount": 30},+ )+ for minutes_ago, amount in [(200, 5), (-900, 100)]:+ _create_event(+ team=self.team,+ event="purchase",+ distinct_id="converted",+ timestamp=NOW - timedelta(minutes=minutes_ago),+ properties={"amount": amount},+ )+ _create_event(+ team=self.team,+ event="purchase",+ distinct_id="personless",+ timestamp=NOW - timedelta(minutes=300),+ properties={"amount": 20, "$process_person_profile": False},+ )+ _create_event(+ team=self.team,+ event="purchase",+ distinct_id="too-late",+ timestamp=NOW - timedelta(minutes=300),+ properties={"amount": 50},+ )+ flush_persons_and_events()++ response = self.client.get(+ self._url("results/"),+ {+ "workflow_id": str(self.workflow_id),+ "event": "purchase",+ "window_days": "1",+ "revenue_property": "amount",+ "date_from": (NOW - timedelta(days=29)).isoformat(),+ },+ )++ assert response.status_code == status.HTTP_200_OK, response.json()+ assert response.json() == {"recipients": 4, "converted": 2, "revenue": 55.0, "median_hours_to_convert": 5.0}++ def test_hides_the_sends_of_a_workflow_the_user_cannot_view(self, _flag):+ restricted = create_workflow_for_test(team_id=self.team.id, name="Payroll").id+ visible_id = self._send(20, "[email protected]", [("sent", 1, "")])+ hidden_id = self._send(10, "[email protected]", [("sent", 1, "")], workflow_id=restricted)+ deleted_workflow = create_workflow_for_test(team_id=self.team.id, name="Old").id+ deleted_id = self._send(+ 5, "[email protected]", [("sent", 1, "")], workflow_id=deleted_workflow, domain="old.example.com"+ )+ destroy_workflow(team_id=self.team.id, hog_flow_id=UUID(deleted_workflow))+ self.organization.available_product_features = [+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL},+ {"key": AvailableFeature.ROLE_BASED_ACCESS, "name": AvailableFeature.ROLE_BASED_ACCESS},+ ]+ self.organization.save()+ self.organization_membership.level = OrganizationMembership.Level.MEMBER+ self.organization_membership.save()+ create_access_control(+ team_id=self.team.id,+ resource="hog_flow",+ resource_id=restricted,+ access_level="none",+ organization_member_id=self.organization_membership.id,+ )++ denied_then_deleted = create_workflow_for_test(team_id=self.team.id, name="Secret").id+ denied_then_deleted_id = self._send(+ 2, "[email protected]", [("sent", 1, "")], workflow_id=denied_then_deleted, domain="secret.example.com"+ )+ create_access_control(+ team_id=self.team.id,+ resource="hog_flow",+ resource_id=denied_then_deleted,+ access_level="none",+ organization_member_id=self.organization_membership.id,+ )+ destroy_workflow(team_id=self.team.id, hog_flow_id=UUID(denied_then_deleted))++ listed = self.client.get(self._url()).json()["results"]+ detail = self.client.get(self._url(f"{hidden_id}/"))+ results = self.client.get(self._url("results/"), {"workflow_id": restricted, "event": "purchase"})++ stats = self.client.get(self._url("stats/"), {"group_by": "sending_domain"}).json()["results"]++ assert [r["message_id"] for r in listed] == [deleted_id, visible_id]+ assert detail.status_code == status.HTTP_404_NOT_FOUND+ assert results.status_code == status.HTTP_404_NOT_FOUND+ assert {row["label"] for row in stats} == {"mail.example.com", "old.example.com"}+ assert self.client.get(self._url(f"{deleted_id}/")).json()["recipient"] == "[email protected]"+ assert self.client.get(self._url(f"{denied_then_deleted_id}/")).status_code == status.HTTP_404_NOT_FOUND++ def test_names_a_send_from_code_by_its_template_key(self, _flag):+ workflow_id = create_workflow_for_test(team_id=self.team.id, name="order-shipped").id+ TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).create(+ team_id=self.team.id, key="order-shipped", hog_flow_id=workflow_id+ )+ self._send(5, "[email protected]", [("sent", 1, "")], workflow_id=workflow_id)++ listed = self.client.get(self._url()).json()["results"]+ stats = self.client.get(self._url("stats/"), {"group_by": "template"}).json()["results"]++ assert [r["template_name"] for r in listed] == ["order-shipped"]+ assert [r["label"] for r in stats] == ["order-shipped"]++ def test_no_access_to_workflows_also_hides_the_sends_of_deleted_ones(self, _flag):+ deleted_workflow = create_workflow_for_test(team_id=self.team.id, name="Old").id+ deleted_id = self._send(5, "[email protected]", [("sent", 1, "")], workflow_id=deleted_workflow)+ destroy_workflow(team_id=self.team.id, hog_flow_id=UUID(deleted_workflow))+ self.organization.available_product_features = [+ {"key": AvailableFeature.ACCESS_CONTROL, "name": AvailableFeature.ACCESS_CONTROL},+ {"key": AvailableFeature.ROLE_BASED_ACCESS, "name": AvailableFeature.ROLE_BASED_ACCESS},+ ]+ self.organization.save()+ self.organization_membership.level = OrganizationMembership.Level.MEMBER+ self.organization_membership.save()+ create_access_control(+ team_id=self.team.id,+ resource="hog_flow",+ access_level="none",+ organization_member_id=self.organization_membership.id,+ )+ assert self.client.get(self._url()).status_code == status.HTTP_403_FORBIDDEN++ granted_id = self._send(10, "[email protected]", [("sent", 1, "")])+ create_access_control(+ team_id=self.team.id,+ resource="hog_flow",+ resource_id=str(self.workflow_id),+ access_level="viewer",+ organization_member_id=self.organization_membership.id,+ )++ listed = self.client.get(self._url())+ assert listed.status_code == status.HTTP_200_OK, listed.json()+ assert [r["message_id"] for r in listed.json()["results"]] == [granted_id]+ assert self.client.get(self._url(f"{deleted_id}/")).status_code == status.HTTP_404_NOT_FOUNDdiff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.tsindex 6777c1ade4c3..ccc727480ffe 100644--- a/products/messaging/frontend/generated/api.schemas.ts+++ b/products/messaging/frontend/generated/api.schemas.ts@@ -995,6 +995,187 @@ export interface SendTransactionalEmailApi {identifiers?: TransactionalEmailIdentifiersApi}+export interface TransactionalEmailLogEntryApi {+ /** The `message_id` that the send returned. */+ message_id: string+ /** When the send was queued. */+ created_at: string+ /** The email's delivery status. `queued` waits to go out, `sent` reached the email provider, `delivered` was accepted by the recipient's mail server, `bounced` and `complained` came back later, and `failed` was not sent.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained */+ status: EmailDeliveryStatusEnumApi+ /** When the email reached its delivery status. */+ status_at: string+ /**+ * Why a failed email was not sent, or the bounce type. Null otherwise.+ * @nullable+ */+ reason: string | null+ /** The address the email was sent to. */+ recipient: string+ /** The workflow behind the transactional email. */+ workflow_id: string+ /**+ * The transactional email template. Null when it no longer exists.+ * @nullable+ */+ template_id: string | null+ /** The template's name. Empty when it was deleted. */+ template_name: string+ /** The domain the email was sent from. Empty before it was sent. */+ sending_domain: string+ /** Whether the recipient opened the email. */+ opened: boolean+ /** Whether the recipient clicked a link in the email. */+ clicked: boolean+}++export interface TransactionalEmailLogListApi {+ /** Sends, newest first. */+ results: TransactionalEmailLogEntryApi[]+ /** Whether another page follows. */+ has_more: boolean+}++/**+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained+ * * `opened` - Opened+ * * `clicked` - Clicked+ */+export type EmailLogEventKindEnumApi = (typeof EmailLogEventKindEnumApi)[keyof typeof EmailLogEventKindEnumApi]++export const EmailLogEventKindEnumApi = {+ Queued: 'queued',+ Failed: 'failed',+ Sent: 'sent',+ Delivered: 'delivered',+ Bounced: 'bounced',+ Complained: 'complained',+ Opened: 'opened',+ Clicked: 'clicked',+} as const++export interface TransactionalEmailLogEventApi {+ /** What happened. The delivery statuses, plus `opened` and `clicked` for what the recipient did.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained+ * * `opened` - Opened+ * * `clicked` - Clicked */+ kind: EmailLogEventKindEnumApi+ /** When it happened. */+ at: string+ /**+ * Why a send failed, or the bounce type. Null otherwise.+ * @nullable+ */+ reason: string | null+}++export interface TransactionalEmailLogDetailApi {+ /** The `message_id` that the send returned. */+ message_id: string+ /** When the send was queued. */+ created_at: string+ /** The email's delivery status. `queued` waits to go out, `sent` reached the email provider, `delivered` was accepted by the recipient's mail server, `bounced` and `complained` came back later, and `failed` was not sent.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained */+ status: EmailDeliveryStatusEnumApi+ /** When the email reached its delivery status. */+ status_at: string+ /**+ * Why a failed email was not sent, or the bounce type. Null otherwise.+ * @nullable+ */+ reason: string | null+ /** The address the email was sent to. */+ recipient: string+ /** The workflow behind the transactional email. */+ workflow_id: string+ /**+ * The transactional email template. Null when it no longer exists.+ * @nullable+ */+ template_id: string | null+ /** The template's name. Empty when it was deleted. */+ template_name: string+ /** The domain the email was sent from. Empty before it was sent. */+ sending_domain: string+ /** Whether the recipient opened the email. */+ opened: boolean+ /** Whether the recipient clicked a link in the email. */+ clicked: boolean+ /** Everything that happened, oldest first. */+ timeline: TransactionalEmailLogEventApi[]+ /** The subject the email went out with. Empty when it was never sent. */+ subject: string+ /** The distinct ID the send named. Empty when it named none. */+ distinct_id: string+ /** The workflow step that sent the email, which the rendered email is stored under. Empty when no rendered email was stored. */+ action_id: string+ /** True when the template is marked sensitive, so no rendered body or subject values are kept. */+ sensitive: boolean+}++export interface TransactionalEmailResultsApi {+ /** People the email was sent to in the date range. */+ recipients: number+ /** Of those, people who did the event within the window. */+ converted: number+ /** The sum of the revenue property on those events. */+ revenue: number+ /**+ * Median hours from the first send to the first conversion. Null when none converted.+ * @nullable+ */+ median_hours_to_convert: number | null+}++export interface TransactionalEmailStatsRowApi {+ /** The template ID or the sending domain. */+ key: string+ /** The template name or the sending domain. Empty for a deleted template. */+ label: string+ /** Emails that reached the email provider. */+ sent: number+ /** Emails the recipient's mail server accepted. */+ delivered: number+ /** Emails that bounced. */+ bounced: number+ /** Emails the recipient marked as spam. */+ complained: number+ /** Emails the recipient opened. */+ opened: number+ /** Emails where the recipient clicked a link. */+ clicked: number+ /** Emails that were not sent. */+ failed: number+}++export interface TransactionalEmailStatsApi {+ /** One row per group, busiest first. */+ results: TransactionalEmailStatsRowApi[]+}+export type MessagingCategoriesListParams = {/*** Number of results to return per page.@@ -1047,3 +1228,114 @@ export type MessagingTemplatesListParams = {*/offset?: number}++export type TransactionalEmailLogListParams = {+ /**+ * Only sends queued at or after this time. Defaults to 7 days ago. The log keeps sends for 30 days.+ */+ date_from?: string+ /**+ * Only sends queued before this time. Defaults to now.+ */+ date_to?: string+ /**+ * Page size.+ * @minimum 1+ * @maximum 200+ */+ limit?: number+ /**+ * Sends to skip.+ * @minimum 0+ */+ offset?: number+ /**+ * A `message_id` for an exact match, or part of the recipient's email address.+ */+ search?: string+ /**+ * Only sends in this delivery status.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained+ * @minLength 1+ */+ status?: TransactionalEmailLogListStatus+ /**+ * Only sends of the transactional email backed by this workflow.+ */+ workflow_id?: string+}++export type TransactionalEmailLogListStatus =+ (typeof TransactionalEmailLogListStatus)[keyof typeof TransactionalEmailLogListStatus]++export const TransactionalEmailLogListStatus = {+ Queued: 'queued',+ Failed: 'failed',+ Sent: 'sent',+ Delivered: 'delivered',+ Bounced: 'bounced',+ Complained: 'complained',+} as const++export type TransactionalEmailLogResultsRetrieveParams = {+ /**+ * Only sends queued at or after this time. Defaults to 7 days ago. The log keeps sends for 30 days.+ */+ date_from?: string+ /**+ * Only sends queued before this time. Defaults to now.+ */+ date_to?: string+ /**+ * The event that counts as a conversion, such as `signed_up`.+ * @minLength 1+ */+ event: string+ /**+ * An event property holding a revenue amount to add up.+ */+ revenue_property?: string+ /**+ * How many days after the first send the event still counts.+ * @minimum 1+ * @maximum 30+ */+ window_days?: number+ /**+ * The workflow behind the transactional email.+ */+ workflow_id: string+}++export type TransactionalEmailLogStatsRetrieveParams = {+ /**+ * Only sends queued at or after this time. Defaults to 7 days ago. The log keeps sends for 30 days.+ */+ date_from?: string+ /**+ * Only sends queued before this time. Defaults to now.+ */+ date_to?: string+ /**+ * Count per template or per sending domain.+ *+ * * `template` - Template+ * * `sending_domain` - Sending domain+ * @minLength 1+ */+ group_by?: TransactionalEmailLogStatsRetrieveGroupBy+}++export type TransactionalEmailLogStatsRetrieveGroupBy =+ (typeof TransactionalEmailLogStatsRetrieveGroupBy)[keyof typeof TransactionalEmailLogStatsRetrieveGroupBy]++export const TransactionalEmailLogStatsRetrieveGroupBy = {+ Template: 'template',+ SendingDomain: 'sending_domain',+} as constdiff --git a/products/messaging/frontend/generated/api.ts b/products/messaging/frontend/generated/api.tsindex 0c0c5dff3d02..97303b15b61b 100644--- a/products/messaging/frontend/generated/api.ts+++ b/products/messaging/frontend/generated/api.ts@@ -44,6 +44,13 @@ import type {StartProviderImportApi,SupabaseAuthEmailSettingsApi,TopicPreferencesApi,+ TransactionalEmailLogDetailApi,+ TransactionalEmailLogListApi,+ TransactionalEmailLogListParams,+ TransactionalEmailLogResultsRetrieveParams,+ TransactionalEmailLogStatsRetrieveParams,+ TransactionalEmailResultsApi,+ TransactionalEmailStatsApi,WebhookUrlApi,} from './api.schemas'@@ -1000,3 +1007,121 @@ export const messagingTemplatesSendCreate = async (body: JSON.stringify(sendTransactionalEmailApi),})}++export const getTransactionalEmailLogListUrl = (projectId: string, params?: TransactionalEmailLogListParams) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/transactional_email_log/?${stringifiedParams}`+ : `/api/projects/${projectId}/transactional_email_log/`+}++/**+ * List the project's transactional email sends, newest first. The log keeps sends for 30 days.+ * @summary List transactional email sends+ */+export const transactionalEmailLogList = async (+ projectId: string,+ params?: TransactionalEmailLogListParams,+ options?: RequestInit+): Promise<TransactionalEmailLogListApi> => {+ return apiMutator<TransactionalEmailLogListApi>(getTransactionalEmailLogListUrl(projectId, params), {+ ...options,+ method: 'GET',+ })+}++export const getTransactionalEmailLogRetrieveUrl = (projectId: string, id: string) => {+ return `/api/projects/${projectId}/transactional_email_log/${id}/`+}++/**+ * Get one send with its timeline: when it was queued, sent, delivered, opened and clicked.+ * @summary Get a transactional email send+ */+export const transactionalEmailLogRetrieve = async (+ projectId: string,+ id: string,+ options?: RequestInit+): Promise<TransactionalEmailLogDetailApi> => {+ return apiMutator<TransactionalEmailLogDetailApi>(getTransactionalEmailLogRetrieveUrl(projectId, id), {+ ...options,+ method: 'GET',+ })+}++export const getTransactionalEmailLogResultsRetrieveUrl = (+ projectId: string,+ params: TransactionalEmailLogResultsRetrieveParams+) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/transactional_email_log/results/?${stringifiedParams}`+ : `/api/projects/${projectId}/transactional_email_log/results/`+}++/**+ * Of the people a transactional email was sent to, count those who did an event within a window after their first send, and add up the revenue on those events.+ * @summary Get what happened after a transactional email+ */+export const transactionalEmailLogResultsRetrieve = async (+ projectId: string,+ params: TransactionalEmailLogResultsRetrieveParams,+ options?: RequestInit+): Promise<TransactionalEmailResultsApi> => {+ return apiMutator<TransactionalEmailResultsApi>(getTransactionalEmailLogResultsRetrieveUrl(projectId, params), {+ ...options,+ method: 'GET',+ })+}++export const getTransactionalEmailLogStatsRetrieveUrl = (+ projectId: string,+ params?: TransactionalEmailLogStatsRetrieveParams+) => {+ const normalizedParams = new URLSearchParams()++ Object.entries(params || {}).forEach(([key, value]) => {+ if (value !== undefined) {+ normalizedParams.append(key, value === null ? 'null' : String(value))+ }+ })++ const stringifiedParams = normalizedParams.toString()++ return stringifiedParams.length > 0+ ? `/api/projects/${projectId}/transactional_email_log/stats/?${stringifiedParams}`+ : `/api/projects/${projectId}/transactional_email_log/stats/`+}++/**+ * Count sends by delivery status, opens and clicks, per template or per sending domain.+ * @summary Get transactional email delivery stats+ */+export const transactionalEmailLogStatsRetrieve = async (+ projectId: string,+ params?: TransactionalEmailLogStatsRetrieveParams,+ options?: RequestInit+): Promise<TransactionalEmailStatsApi> => {+ return apiMutator<TransactionalEmailStatsApi>(getTransactionalEmailLogStatsRetrieveUrl(projectId, params), {+ ...options,+ method: 'GET',+ })+}diff --git a/products/workflows/backend/facade/api.py b/products/workflows/backend/facade/api.pyindex 65750373a36d..ec79237a8f31 100644--- a/products/workflows/backend/facade/api.py+++ b/products/workflows/backend/facade/api.py@@ -25,6 +25,7 @@ from products.workflows.backend.facade.contracts import (WorkflowNotFound,WorkflowSummary,WorkflowTaskDailyLimits,+ WorkflowViewAccess,WorkflowVisionScanDailyLimits,)from products.workflows.backend.models import HogFlow, TeamWorkflowsConfig@@ -70,6 +71,8 @@ __all__ = ["filter_hog_flow_references_by_access_level","get_email_sending_state","get_email_sending_tier_limits",+ "get_viewable_workflow_ids",+ "get_workflow_view_access","get_hog_flows_referencing_template_input_keys","list_owned_workflow_health","max_email_sending_tier",@@ -222,6 +225,30 @@ def get_workflow_names(*, team_id: int, workflow_ids: Iterable[str]) -> dict[str}+def get_viewable_workflow_ids(*, team_id: int, user_access_control: UserAccessControl) -> set[str]:+ """The ids, as strings, of the team's workflows the reader may view."""+ return {+ str(pk)+ for pk in user_access_control.filter_queryset_by_access_level(+ HogFlow.objects.filter(team_id=team_id)+ ).values_list("id", flat=True)+ }+++def get_workflow_view_access(*, team_id: int, user_access_control: UserAccessControl) -> WorkflowViewAccess:+ """What the reader may view, for records that outlive their workflow. A denial outlives the workflow it names, so a+ deleted workflow stays hidden from a reader denied it, and otherwise follows their access to workflows as a whole."""+ viewable = get_viewable_workflow_ids(team_id=team_id, user_access_control=user_access_control)+ existing = {str(pk) for pk in HogFlow.objects.filter(team_id=team_id).values_list("id", flat=True)}+ return WorkflowViewAccess(+ viewable_ids=frozenset(viewable),+ blocked_ids=frozenset(+ (existing | user_access_control.blocked_resource_ids_by_scope.get("hog_flow", frozenset())) - viewable+ ),+ can_view_deleted=user_access_control.has_resource_access("hog_flow"),+ )++def get_workflow_summary(*, team_id: int, workflow_id: str) -> WorkflowSummary:row = HogFlow.objects.filter(team_id=team_id, id=workflow_id).values("id", "name", "status").first()if row is None:diff --git a/products/workflows/backend/facade/contracts.py b/products/workflows/backend/facade/contracts.pyindex 5aea64085d3a..a3b781cb9256 100644--- a/products/workflows/backend/facade/contracts.py+++ b/products/workflows/backend/facade/contracts.py@@ -33,6 +33,18 @@ if TYPE_CHECKING:from posthog.models.user import User+@frozen+class WorkflowViewAccess:+ viewable_ids: frozenset[str]+ blocked_ids: frozenset[str]+ can_view_deleted: bool++ def allows(self, workflow_id: str) -> bool:+ if workflow_id in self.viewable_ids:+ return True+ return self.can_view_deleted and bool(workflow_id) and workflow_id not in self.blocked_ids++@frozenclass WorkflowSummary:id: strdiff --git a/products/workflows/backend/facade/message_assets.py b/products/workflows/backend/facade/message_assets.pyindex 590b3f4f061a..b137dee460d3 100644--- a/products/workflows/backend/facade/message_assets.py+++ b/products/workflows/backend/facade/message_assets.py@@ -1,13 +1,17 @@"""Message assets: the emails and push notifications that workflow steps sent, read from ClickHouse."""from products.workflows.backend.services.message_assets import (+ fetch_first_email_sends,fetch_message_asset_html,fetch_message_assets,+ fetch_message_assets_for_invocations,fetch_message_assets_for_person,)__all__ = [+ "fetch_first_email_sends","fetch_message_asset_html","fetch_message_assets",+ "fetch_message_assets_for_invocations","fetch_message_assets_for_person",]diff --git a/products/workflows/backend/services/message_assets.py b/products/workflows/backend/services/message_assets.pyindex 944a5166b259..e8a7d8c14949 100644--- a/products/workflows/backend/services/message_assets.py+++ b/products/workflows/backend/services/message_assets.py@@ -2,6 +2,7 @@ from collections.abc import Sequencefrom datetime import UTC, datetimefrom typing import Any, Optional, cast+from posthog.clickhouse.client.connection import Workloadfrom posthog.clickhouse.client.execute import sync_executefrom products.workflows.backend.facade.contracts import MessageAsset@@ -193,6 +194,82 @@ def fetch_message_assets_for_person(return [_build_asset(row) for row in results]+def fetch_message_assets_for_invocations(+ team_id: int,+ invocation_ids: Sequence[str],+ after: datetime,+) -> list[MessageAsset]:+ """The emails the given runs sent, at most one per run and step. `after` bounds the scan to the runs' partitions."""+ if not invocation_ids:+ return []+ query = f"""+ SELECT {_OUTER_COLUMNS}+ FROM (+ SELECT {_COLLAPSED_AGGREGATES}+ FROM message_assets+ WHERE team_id = %(team_id)s+ AND function_kind = 'hog_flow'+ AND kind = 'email'+ AND invocation_id IN %(invocation_ids)s+ AND sent_at >= toDateTime64(%(after)s, 6)+ GROUP BY invocation_id, action_id+ )+ WHERE latest_is_deleted = 0+ """+ results = cast(+ list,+ sync_execute(+ query,+ {+ "team_id": team_id,+ "invocation_ids": list(invocation_ids),+ "after": after.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S"),+ },+ workload=Workload.ONLINE,+ team_id=team_id,+ ),+ )+ return [_build_asset(row) for row in results]+++def fetch_first_email_sends(+ team_id: int,+ function_id: str,+ after: datetime,+ before: datetime,+ limit: int,+) -> dict[str, datetime]:+ """When the workflow first emailed each distinct ID in the range, for the `limit` most recently emailed."""+ rows = cast(+ list,+ sync_execute(+ """+ SELECT distinct_id, min(sent_at) AS first_sent_at+ FROM message_assets+ WHERE team_id = %(team_id)s+ AND function_kind = 'hog_flow'+ AND function_id = %(function_id)s+ AND kind = 'email'+ AND sent_at >= toDateTime64(%(after)s, 6) AND sent_at < toDateTime64(%(before)s, 6)+ AND distinct_id != ''+ GROUP BY distinct_id+ ORDER BY first_sent_at DESC+ LIMIT %(limit)s+ """,+ {+ "team_id": team_id,+ "function_id": function_id,+ "after": after.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S"),+ "before": before.astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%S"),+ "limit": limit,+ },+ workload=Workload.ONLINE,+ team_id=team_id,+ ),+ )+ return {distinct_id: sent_at.replace(tzinfo=UTC) for distinct_id, sent_at in rows}++def fetch_message_asset_html(team_id: int,function_kind: str,diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex ba77338c9ef1..b54e9701fb1f 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -37183,6 +37183,30 @@ export namespace Schemas {source_id: string;}+ /**+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained+ * * `opened` - Opened+ * * `clicked` - Clicked+ */+ export type EmailLogEventKindEnum = typeof EmailLogEventKindEnum[keyof typeof EmailLogEventKindEnum];+++ export const EmailLogEventKindEnum = {+ Queued: 'queued',+ Failed: 'failed',+ Sent: 'sent',+ Delivered: 'delivered',+ Bounced: 'bounced',+ Complained: 'complained',+ Opened: 'opened',+ Clicked: 'clicked',+ } as const;+/*** How much workflow email this project may send, and how much of that it has used.*/@@ -113480,6 +113504,164 @@ export namespace Schemas {runs: TrainingRunHistoryEntry[];}+ export interface TransactionalEmailLogEvent {+ /** What happened. The delivery statuses, plus `opened` and `clicked` for what the recipient did.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained+ * * `opened` - Opened+ * * `clicked` - Clicked */+ kind: EmailLogEventKindEnum;+ /** When it happened. */+ at: string;+ /**+ * Why a send failed, or the bounce type. Null otherwise.+ * @nullable+ */+ reason: string | null;+ }++ export interface TransactionalEmailLogDetail {+ /** The `message_id` that the send returned. */+ message_id: string;+ /** When the send was queued. */+ created_at: string;+ /** The email's delivery status. `queued` waits to go out, `sent` reached the email provider, `delivered` was accepted by the recipient's mail server, `bounced` and `complained` came back later, and `failed` was not sent.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained */+ status: EmailDeliveryStatusEnum;+ /** When the email reached its delivery status. */+ status_at: string;+ /**+ * Why a failed email was not sent, or the bounce type. Null otherwise.+ * @nullable+ */+ reason: string | null;+ /** The address the email was sent to. */+ recipient: string;+ /** The workflow behind the transactional email. */+ workflow_id: string;+ /**+ * The transactional email template. Null when it no longer exists.+ * @nullable+ */+ template_id: string | null;+ /** The template's name. Empty when it was deleted. */+ template_name: string;+ /** The domain the email was sent from. Empty before it was sent. */+ sending_domain: string;+ /** Whether the recipient opened the email. */+ opened: boolean;+ /** Whether the recipient clicked a link in the email. */+ clicked: boolean;+ /** Everything that happened, oldest first. */+ timeline: TransactionalEmailLogEvent[];+ /** The subject the email went out with. Empty when it was never sent. */+ subject: string;+ /** The distinct ID the send named. Empty when it named none. */+ distinct_id: string;+ /** The workflow step that sent the email, which the rendered email is stored under. Empty when no rendered email was stored. */+ action_id: string;+ /** True when the template is marked sensitive, so no rendered body or subject values are kept. */+ sensitive: boolean;+ }++ export interface TransactionalEmailLogEntry {+ /** The `message_id` that the send returned. */+ message_id: string;+ /** When the send was queued. */+ created_at: string;+ /** The email's delivery status. `queued` waits to go out, `sent` reached the email provider, `delivered` was accepted by the recipient's mail server, `bounced` and `complained` came back later, and `failed` was not sent.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained */+ status: EmailDeliveryStatusEnum;+ /** When the email reached its delivery status. */+ status_at: string;+ /**+ * Why a failed email was not sent, or the bounce type. Null otherwise.+ * @nullable+ */+ reason: string | null;+ /** The address the email was sent to. */+ recipient: string;+ /** The workflow behind the transactional email. */+ workflow_id: string;+ /**+ * The transactional email template. Null when it no longer exists.+ * @nullable+ */+ template_id: string | null;+ /** The template's name. Empty when it was deleted. */+ template_name: string;+ /** The domain the email was sent from. Empty before it was sent. */+ sending_domain: string;+ /** Whether the recipient opened the email. */+ opened: boolean;+ /** Whether the recipient clicked a link in the email. */+ clicked: boolean;+ }++ export interface TransactionalEmailLogList {+ /** Sends, newest first. */+ results: TransactionalEmailLogEntry[];+ /** Whether another page follows. */+ has_more: boolean;+ }++ export interface TransactionalEmailResults {+ /** People the email was sent to in the date range. */+ recipients: number;+ /** Of those, people who did the event within the window. */+ converted: number;+ /** The sum of the revenue property on those events. */+ revenue: number;+ /**+ * Median hours from the first send to the first conversion. Null when none converted.+ * @nullable+ */+ median_hours_to_convert: number | null;+ }++ export interface TransactionalEmailStatsRow {+ /** The template ID or the sending domain. */+ key: string;+ /** The template name or the sending domain. Empty for a deleted template. */+ label: string;+ /** Emails that reached the email provider. */+ sent: number;+ /** Emails the recipient's mail server accepted. */+ delivered: number;+ /** Emails that bounced. */+ bounced: number;+ /** Emails the recipient marked as spam. */+ complained: number;+ /** Emails the recipient opened. */+ opened: number;+ /** Emails where the recipient clicked a link. */+ clicked: number;+ /** Emails that were not sent. */+ failed: number;+ }++ export interface TransactionalEmailStats {+ /** One row per group, busiest first. */+ results: TransactionalEmailStatsRow[];+ }+export interface TranslateRequest {/*** The text to translate@@ -134819,6 +135001,117 @@ export namespace Schemas {offset?: number;};+ export type TransactionalEmailLogListParams = {+ /**+ * Only sends queued at or after this time. Defaults to 7 days ago. The log keeps sends for 30 days.+ */+ date_from?: string;+ /**+ * Only sends queued before this time. Defaults to now.+ */+ date_to?: string;+ /**+ * Page size.+ * @minimum 1+ * @maximum 200+ */+ limit?: number;+ /**+ * Sends to skip.+ * @minimum 0+ */+ offset?: number;+ /**+ * A `message_id` for an exact match, or part of the recipient's email address.+ */+ search?: string;+ /**+ * Only sends in this delivery status.+ *+ * * `queued` - Queued+ * * `failed` - Failed+ * * `sent` - Sent+ * * `delivered` - Delivered+ * * `bounced` - Bounced+ * * `complained` - Complained+ * @minLength 1+ */+ status?: TransactionalEmailLogListStatus;+ /**+ * Only sends of the transactional email backed by this workflow.+ */+ workflow_id?: string;+ };++ export type TransactionalEmailLogListStatus = typeof TransactionalEmailLogListStatus[keyof typeof TransactionalEmailLogListStatus];+++ export const TransactionalEmailLogListStatus = {+ Queued: 'queued',+ Failed: 'failed',+ Sent: 'sent',+ Delivered: 'delivered',+ Bounced: 'bounced',+ Complained: 'complained',+ } as const;++ export type TransactionalEmailLogResultsRetrieveParams = {+ /**+ * Only sends queued at or after this time. Defaults to 7 days ago. The log keeps sends for 30 days.+ */+ date_from?: string;+ /**+ * Only sends queued before this time. Defaults to now.+ */+ date_to?: string;+ /**+ * The event that counts as a conversion, such as `signed_up`.+ * @minLength 1+ */+ event: string;+ /**+ * An event property holding a revenue amount to add up.+ */+ revenue_property?: string;+ /**+ * How many days after the first send the event still counts.+ * @minimum 1+ * @maximum 30+ */+ window_days?: number;+ /**+ * The workflow behind the transactional email.+ */+ workflow_id: string;+ };++ export type TransactionalEmailLogStatsRetrieveParams = {+ /**+ * Only sends queued at or after this time. Defaults to 7 days ago. The log keeps sends for 30 days.+ */+ date_from?: string;+ /**+ * Only sends queued before this time. Defaults to now.+ */+ date_to?: string;+ /**+ * Count per template or per sending domain.+ *+ * * `template` - Template+ * * `sending_domain` - Sending domain+ * @minLength 1+ */+ group_by?: TransactionalEmailLogStatsRetrieveGroupBy;+ };++ export type TransactionalEmailLogStatsRetrieveGroupBy = typeof TransactionalEmailLogStatsRetrieveGroupBy[keyof typeof TransactionalEmailLogStatsRetrieveGroupBy];+++ export const TransactionalEmailLogStatsRetrieveGroupBy = {+ Template: 'template',+ SendingDomain: 'sending_domain',+ } as const;+export type TurnSuggestionsStateRetrieveParams = {/*** ID of the PostHog AI conversation (task) to read suggestion outcomes for.