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 transactional email log api (#127746)

Daniel Marchukd141e959089f
diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 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 | None
diff --git a/products/messaging/backend/facade/transactional_email_log.py b/products/messaging/backend/facade/transactional_email_log.py
new file mode 100644
index 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.py
new file mode 100644
index 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 error
diff --git a/products/messaging/backend/presentation/views/transactional_email_log.py b/products/messaging/backend/presentation/views/transactional_email_log.py
new file mode 100644
index 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.py
index 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 TransactionalEmailLogViewSet
from products.messaging.backend.presentation.views.transactional_email_status import MessagingEmailsViewSet
webhook_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.py
new file mode 100644
index 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.py
new file mode 100644
index 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_FOUND
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index 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 const
diff --git a/products/messaging/frontend/generated/api.ts b/products/messaging/frontend/generated/api.ts
index 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.py
index 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.py
index 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
+
+
@frozen
class WorkflowSummary:
id: str
diff --git a/products/workflows/backend/facade/message_assets.py b/products/workflows/backend/facade/message_assets.py
index 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.py
index 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 Sequence
from datetime import UTC, datetime
from typing import Any, Optional, cast
+from posthog.clickhouse.client.connection import Workload
from posthog.clickhouse.client.execute import sync_execute
from 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.ts
index 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.