: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(messaging): capture email first code send once per project (#127187)
Michael Reichenbacha60a02e4bb76
diff --git a/.semgrep/rules/security/idor-team-scoped-models.yaml b/.semgrep/rules/security/idor-team-scoped-models.yamlindex a4cecedfcd05..86b89cdd636f 100644--- a/.semgrep/rules/security/idor-team-scoped-models.yaml+++ b/.semgrep/rules/security/idor-team-scoped-models.yaml@@ -244,6 +244,7 @@ rules:|FileSystem|FileSystemFolderInstructions|FileSystemFolderContextGeneration+ |FirstCodeSend|GithubCommentMapping|GitHubSyncConfig|GitHubSyncPlan@@ -752,6 +753,7 @@ rules:|FileSystem|FileSystemFolderInstructions|FileSystemFolderContextGeneration+ |FirstCodeSend|GithubCommentMapping|GitHubSyncConfig|GitHubSyncPlandiff --git a/products/messaging/backend/facade/transactional_email.py b/products/messaging/backend/facade/transactional_email.pyindex e6c9db537824..bed97b4009c2 100644--- a/products/messaging/backend/facade/transactional_email.py+++ b/products/messaging/backend/facade/transactional_email.py@@ -17,6 +17,7 @@ from products.messaging.backend.services.transactional_email import (lock_transactional_workflow_id,make_transactional,observe_transactional_email_stage,+ report_first_code_send,require_code_email_access,send_code_email,send_transactional_email,@@ -42,6 +43,7 @@ __all__ = ["lock_transactional_workflow_id","make_transactional","observe_transactional_email_stage",+ "report_first_code_send","require_code_email_access","send_code_email","send_transactional_email",diff --git a/products/messaging/backend/migrations/0016_first_code_send.py b/products/messaging/backend/migrations/0016_first_code_send.pynew file mode 100644index 000000000000..71e11bfa139d--- /dev/null+++ b/products/messaging/backend/migrations/0016_first_code_send.py@@ -0,0 +1,43 @@+# Generated by Django 5.2.18 on 2026-10-25 23:23++import django.db.models.deletion+from django.db import migrations, models++import posthog.uuidt+++class Migration(migrations.Migration):+ dependencies = [+ ("messaging", "0015_transactional_email_key"),+ ("posthog", "1412_drop_retired_desktop_file_system_tables"),+ ]++ operations = [+ migrations.CreateModel(+ name="FirstCodeSend",+ fields=[+ (+ "id",+ models.UUIDField(+ default=posthog.uuidt.uuid7,+ editable=False,+ primary_key=True,+ serialize=False,+ ),+ ),+ ("created_at", models.DateTimeField(auto_now_add=True)),+ (+ "team",+ models.ForeignKey(+ db_constraint=False,+ on_delete=django.db.models.deletion.CASCADE,+ related_name="+",+ to="posthog.team",+ ),+ ),+ ],+ options={+ "constraints": [models.UniqueConstraint(fields=("team",), name="unique_first_code_send_per_team")],+ },+ ),+ ]diff --git a/products/messaging/backend/migrations/max_migration.txt b/products/messaging/backend/migrations/max_migration.txtindex 11b055dbd3c6..0ad546ac48ef 100644--- a/products/messaging/backend/migrations/max_migration.txt+++ b/products/messaging/backend/migrations/max_migration.txt@@ -1 +1 @@-0015_transactional_email_key+0016_first_code_senddiff --git a/products/messaging/backend/models/__init__.py b/products/messaging/backend/models/__init__.pyindex 4ba7c27de7fc..07e1aa960fed 100644--- a/products/messaging/backend/models/__init__.py+++ b/products/messaging/backend/models/__init__.py@@ -1,4 +1,5 @@from .email_hard_bounce import EmailHardBounce+from .first_code_send import FirstCodeSendfrom .message_category import MessageCategory, MessageCategoryTypefrom .message_preferences import ALL_MESSAGE_PREFERENCE_CATEGORY_ID, MessageRecipientPreference, PreferenceStatusfrom .message_suppression import MessageSuppression, SuppressionSource@@ -11,6 +12,7 @@ from .transactional_email_key import TransactionalEmailKey__all__ = ["ALL_MESSAGE_PREFERENCE_CATEGORY_ID","EmailHardBounce",+ "FirstCodeSend","MessageCategory","MessageCategoryType","MessageRecipientPreference",diff --git a/products/messaging/backend/models/first_code_send.py b/products/messaging/backend/models/first_code_send.pynew file mode 100644index 000000000000..bf0c4b2268ed--- /dev/null+++ b/products/messaging/backend/models/first_code_send.py@@ -0,0 +1,16 @@+from django.db import models++from posthog.models.scoping.root_mixin import TeamScopedRootMixin+from posthog.models.utils import UUIDModel++FIRST_CODE_SEND_CONSTRAINT = "unique_first_code_send_per_team"+++class FirstCodeSend(TeamScopedRootMixin, UUIDModel):+ team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")+ created_at = models.DateTimeField(auto_now_add=True)++ class Meta:+ constraints = [+ models.UniqueConstraint(fields=["team"], name=FIRST_CODE_SEND_CONSTRAINT),+ ]diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.pyindex 622d02e07851..a7204319d9cc 100644--- a/products/messaging/backend/presentation/views/message_templates.py+++ b/products/messaging/backend/presentation/views/message_templates.py@@ -32,10 +32,10 @@ from posthog.api.forbid_destroy_model import ForbidDestroyModelfrom posthog.api.mixins import ResponseDeclaration, validated_requestfrom posthog.api.routing import TeamAndOrgViewSetMixinfrom posthog.api.shared import UserBasicSerializer-from posthog.auth import ProjectSecretAPIKeyAuthentication+from posthog.auth import ProjectSecretAPIKeyAuthentication, ProjectSecretAPIKeyUserfrom posthog.event_usage import groups, report_user_actionfrom posthog.integrations import IntegrationManager, IntegrationNotFound-from posthog.models import User+from posthog.models import ProjectSecretAPIKey, Userfrom posthog.models.tag import tagifyfrom posthog.permissions import is_authenticated_via_project_secret_api_key, legacy_scope_object_usedfrom posthog.rate_limit import PersonalOrProjectSecretApiKeyRateThrottle, ProjectSecretApiKeyTeamRateThrottle@@ -73,6 +73,7 @@ from products.messaging.backend.facade.transactional_email import (lock_transactional_workflow_id,make_transactional,observe_transactional_email_stage,+ report_first_code_send,require_code_email_access,send_code_email,send_transactional_email,@@ -408,6 +409,7 @@ IDEMPOTENCY_KEY_PARAMETER = OpenApiParameter(TRANSACTIONAL_EMAIL_API_FLAG = "workflows-transactional-email-api"+FIRST_CODE_SEND_EVENT = "email first code send"DISTINCT_ID_HELP_TEXT = (@@ -820,6 +822,8 @@ class TransactionalEmailSendMixin:finally:with transactional_email_stage("usage_event"):self._report_transactional_email_send(request, {**addressed, **outcome})+ if not queued.replayed:+ self._report_first_code_send_after_commit(request, route, addressed.get("addressed_by", "template_id"))return Response(SendTransactionalEmailResponseSerializer(queued).data,status=status.HTTP_202_ACCEPTED,@@ -851,6 +855,37 @@ class TransactionalEmailSendMixin:if not self.user_access_control.check_access_level_for_resource("hog_flow", "editor"):raise exceptions.PermissionDenied("You need editor access to workflows to send under a new key.")+ def _report_first_code_send_after_commit(self, request: Any, route: str, addressed_by: str) -> None:+ if route != "send_email" or not isinstance(request.user, ProjectSecretAPIKeyUser):+ return+ key = request.user.project_secret_api_key+ if key.created_by_id is None:+ return+ # A code send passed this flag before it went out, so only a send by template id checks it here.+ if addressed_by != "template_key" and not _flag_enabled(self.team, EMAIL_FROM_CODE_FLAG):+ return+ transaction.on_commit(lambda: self._report_first_code_send(key, addressed_by))++ def _report_first_code_send(self, key: ProjectSecretAPIKey, addressed_by: str) -> None:+ try:+ report_first_code_send(self.team_id, lambda: self._capture_first_code_send(key, addressed_by))+ except Exception as e:+ logger.warning("Failed to capture the first code send", team_id=self.team_id, error=str(e))++ def _capture_first_code_send(self, key: ProjectSecretAPIKey, addressed_by: str) -> bool:+ key_creator = User.objects.filter(created_project_secret_api_keys__id=key.pk).first()+ if key_creator is None:+ return False+ # A key made in an environment sends for its project, and the project holds the claim.+ project = self.team.parent_team or self.team+ queued = posthoganalytics.capture(+ distinct_id=key_creator.distinct_id,+ event=FIRST_CODE_SEND_EVENT,+ properties={"team_id": project.id, "addressed_by": addressed_by},+ groups=groups(self.organization, project),+ )+ return queued is not None+def _report_transactional_email_send(self, request: Any, properties: dict[str, Any]) -> None:# report_user_action drops the synthetic user behind a project secret API key, so capture directly.try:diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.pyindex 410aa3117f54..a6028fdb4e6c 100644--- a/products/messaging/backend/services/transactional_email.py+++ b/products/messaging/backend/services/transactional_email.py@@ -48,7 +48,7 @@ from products.messaging.backend.facade.contracts import (TransactionalEmailError,TransactionalEmailPaused,)-from products.messaging.backend.models import MessageCategory, MessageTemplate, TransactionalEmailKey+from products.messaging.backend.models import FirstCodeSend, MessageCategory, MessageTemplate, TransactionalEmailKeyfrom products.messaging.backend.models.message_category import MessageCategoryTypefrom products.messaging.backend.services.html_text import text_from_htmlfrom products.workflows.backend.facade.api import WorkflowNotFound, get_workflow_summary@@ -448,6 +448,18 @@ def _lock_team_keys(team_id: int) -> None:)+def report_first_code_send(team_id: int, capture: Callable[[], bool]) -> None:+ _, claimed = FirstCodeSend.objects.for_team(team_id).get_or_create(defaults={"team_id": team_id})+ if not claimed:+ return+ captured = False+ try:+ captured = capture()+ finally:+ if not captured:+ FirstCodeSend.objects.for_team(team_id).delete()++def require_code_email_access(team_id: int,key: str,diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.pyindex 7c8b9233fdae..1e24824f425c 100644--- a/products/messaging/backend/tests/api/test_transactional_email.py+++ b/products/messaging/backend/tests/api/test_transactional_email.py@@ -1,4 +1,5 @@import json+from collections.abc import Callablefrom typing import Any, get_argsfrom uuid import UUID, uuid4@@ -6,6 +7,9 @@ import pytestfrom posthog.test.base import APIBaseTestfrom unittest.mock import MagicMock, patch+from django.db import connection+from django.test.utils import CaptureQueriesContext+import requestsfrom parameterized import parameterizedfrom prometheus_client import REGISTRY@@ -14,12 +18,15 @@ from rest_framework.test import APIClientfrom structlog.testing import capture_logsfrom posthog.constants import AvailableFeature+from posthog.dataclasses import frozenfrom posthog.models import OrganizationMembership, ProjectSecretAPIKey, Team, Userfrom posthog.models.integration import Integration-from posthog.models.personal_api_key import hash_key_value-from posthog.models.utils import generate_random_token_secret+from posthog.models.personal_api_key import PersonalAPIKey, hash_key_value+from posthog.models.utils import generate_random_token_personal, generate_random_token_secretfrom products.access_control.backend.facade.testing import create_access_control+from products.messaging.backend.facade.transactional_email import report_first_code_send+from products.messaging.backend.models.first_code_send import FirstCodeSendfrom products.messaging.backend.models.message_category import MessageCategory, MessageCategoryTypefrom products.messaging.backend.models.message_template import MessageTemplatefrom products.messaging.backend.models.transactional_email_key import TransactionalEmailKey@@ -51,6 +58,14 @@ ADDRESS_VERDICTS = []+@frozen+class CapturedFirstCodeSend:+ distinct_id: str | None+ properties: dict[str, Any]+ organization_id: str+ project: str++def _stage_counts() -> dict[str, float]:return {stage: REGISTRY.get_sample_value("messaging_transactional_email_stage_duration_seconds_count", {"stage": stage})@@ -115,14 +130,21 @@ class TestTransactionalEmail(APIBaseTest):flat["distinct_id"] = body["identifiers"]["distinct_id"]return {**flat, "template_id": str(self.template.id)}- def _psak_client(self, scopes: list[str], team: Team | None = None) -> APIClient:+ def _psak_client(+ self,+ scopes: list[str],+ created_by: User | None = None,+ label: str = "transactional email",+ team: Team | None = None,+ ) -> APIClient:raw_token = generate_random_token_secret()ProjectSecretAPIKey.objects.create(team=team or self.team,- label="transactional email",+ label=label,secure_value=hash_key_value(raw_token),scopes=scopes,mask_value=f"{raw_token[:4]}...{raw_token[-4:]}",+ created_by=created_by,)client = APIClient()client.credentials(HTTP_AUTHORIZATION=f"Bearer {raw_token}")@@ -561,7 +583,7 @@ class TestTransactionalEmail(APIBaseTest):set_default_email_sender_if_unset(env.id, env_sender.id)clients = {self.team.id: self._psak_client(["hog_flow:write"]),- env.id: self._psak_client(["hog_flow:write"], env),+ env.id: self._psak_client(["hog_flow:write"], team=env),}for team_id in (self.team.id, env.id, self.team.id, env.id):@@ -1076,6 +1098,198 @@ class TestTransactionalEmail(APIBaseTest):assert (after.message_category_id, after.content) == (None, before.content)assert self._workflow(self.hog_flow_id)["version"] == 1+ def _sender_client(self, sender: str) -> APIClient:+ if sender == "personal_api_key":+ token = generate_random_token_personal()+ PersonalAPIKey.objects.create(+ label="email", user=self.user, secure_value=hash_key_value(token), scopes=["transactional_email:write"]+ )+ client = APIClient()+ client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}")+ return client+ return self._psak_client(+ ["transactional_email:write"], created_by=self.user if sender == "key_creator" else None+ )++ @staticmethod+ def _first_code_sends(capture: MagicMock) -> list[CapturedFirstCodeSend]:+ return [+ CapturedFirstCodeSend(+ distinct_id=call.kwargs["distinct_id"],+ properties=call.kwargs["properties"],+ organization_id=call.kwargs["groups"]["organization"],+ project=call.kwargs["groups"]["project"],+ )+ for call in capture.call_args_list+ if call.kwargs["event"] == "email first code send"+ ]++ @parameterized.expand([("the_project", False), ("an_environment", True)])+ def test_the_first_code_send_of_a_project_is_reported_once_for_whoever_made_its_key_in(+ self, mock_post, _flag, capture, _name, in_environment+ ):+ self._cdp_accepts(mock_post)+ key_team = self.team+ if in_environment:+ key_team = Team.objects.create(organization=self.organization, parent_team=self.team, name="env")+ sender = Integration.objects.create(+ team=key_team, kind="email", integration_id="[email protected]", config={"verified": True}+ )+ set_default_email_sender_if_unset(key_team.id, sender.id)+ psak = self._psak_client(["hog_flow:write"], created_by=self.user, team=key_team)+ url = f"/api/projects/{key_team.id}/messaging/send/email/"++ with self.captureOnCommitCallbacks(execute=True):+ first = psak.post(url, self._code_send(), format="json")+ with self.captureOnCommitCallbacks(execute=True):+ second = psak.post(url, self._code_send(), format="json")++ assert (first.status_code, second.status_code) == (status.HTTP_202_ACCEPTED, status.HTTP_202_ACCEPTED), (+ first.json()+ )+ assert self._first_code_sends(capture) == [+ CapturedFirstCodeSend(+ distinct_id=self.user.distinct_id,+ properties={"team_id": self.team.id, "addressed_by": "template_key"},+ organization_id=str(self.organization.id),+ project=str(self.team.uuid),+ )+ ]++ def test_a_template_send_by_id_counts_as_the_first_code_send(self, mock_post, _flag, capture):+ self._cdp_accepts(mock_post)++ with self.captureOnCommitCallbacks(execute=True):+ response = self._send(self._sender_client("key_creator"), "send_email", self.body)++ assert response.status_code == status.HTTP_202_ACCEPTED, response.json()+ assert [sent.properties["addressed_by"] for sent in self._first_code_sends(capture)] == ["template_id"]++ @parameterized.expand(+ [+ (+ "a_replay",+ "key_creator",+ MagicMock(status_code=202, json=lambda: {"invocation_id": "a", "replayed": True}),+ True,+ 202,+ ),+ ("a_key_nobody_made", "key_without_creator", None, True, 202),+ ("a_personal_api_key", "personal_api_key", None, True, 202),+ ("a_send_the_pipeline_refuses", "key_creator", MagicMock(status_code=429), True, 503),+ ("the_flag_off", "key_creator", None, False, 404),+ ]+ )+ def test_reports_no_first_code_send_for(+ self, mock_post, flag, capture, _name, sender, pipeline_answer, flag_on, expected_status+ ):+ self._cdp_accepts(mock_post)+ if pipeline_answer is not None:+ mock_post.return_value = pipeline_answer+ flag.return_value = flag_on++ with self.captureOnCommitCallbacks(execute=True):+ response = self._sender_client(sender).post(self.send_email_url, self._code_send(), format="json")++ assert response.status_code == expected_status, response.json()+ assert self._first_code_sends(capture) == []++ @parameterized.expand(+ [+ ("raises", {"side_effect": RuntimeError("capture is down")}),+ ("drops_the_event", {"return_value": None}),+ ]+ )+ def test_a_first_code_send_that_fails_to_capture_leaves_it_to_a_later_send(+ self, mock_post, _flag, capture, _name, failure+ ):+ self._cdp_accepts(mock_post)+ psak = self._sender_client("key_creator")+ capture.configure_mock(**failure)++ with self.captureOnCommitCallbacks(execute=True):+ failed = psak.post(self.send_email_url, self._code_send(), format="json")+ capture.reset_mock(side_effect=True, return_value=True)+ with self.captureOnCommitCallbacks(execute=True):+ later = psak.post(self.send_email_url, self._code_send(), format="json")++ assert (failed.status_code, later.status_code) == (status.HTTP_202_ACCEPTED, status.HTTP_202_ACCEPTED)+ assert [sent.properties["addressed_by"] for sent in self._first_code_sends(capture)] == ["template_key"]++ @parameterized.expand(+ [+ ("the_template_route", "send", {EMAIL_FROM_CODE_FLAG, TRANSACTIONAL_EMAIL_API_FLAG}),+ ("send_email_without_the_code_flag", "send_email", {TRANSACTIONAL_EMAIL_API_FLAG}),+ ]+ )+ def test_a_template_send_by_id_reports_no_first_code_send_on(self, mock_post, flag, capture, _name, route, flags):+ self._cdp_accepts(mock_post)+ flag.side_effect = lambda name, *args, **kwargs: name in flags++ with self.captureOnCommitCallbacks(execute=True):+ response = self._send(self._sender_client("key_creator"), route, self.body)++ assert response.status_code == status.HTTP_202_ACCEPTED, response.json()+ assert self._first_code_sends(capture) == []+ assert not FirstCodeSend.objects.for_team(self.team.id).exists()++ def test_a_creator_deleted_before_the_callback_leaves_the_first_code_send_to_a_later_send(+ self, mock_post, _flag, capture+ ):+ self._cdp_accepts(mock_post)+ departed = User.objects.create_and_join(self.organization, "[email protected]", None)+ departed_psak = self._psak_client(["hog_flow:write"], created_by=departed, label="departed")++ with self.captureOnCommitCallbacks(execute=False) as callbacks:+ departed_psak.post(self.send_email_url, self._code_send(), format="json")+ departed.delete()+ for callback in callbacks:+ callback()+ with self.captureOnCommitCallbacks(execute=True):+ self._sender_client("key_creator").post(self.send_email_url, self._code_send(), format="json")++ assert self._first_code_sends(capture) == [+ CapturedFirstCodeSend(+ distinct_id=self.user.distinct_id,+ properties={"team_id": self.team.id, "addressed_by": "template_key"},+ organization_id=str(self.organization.id),+ project=str(self.team.uuid),+ )+ ]++ def test_a_later_code_send_makes_no_first_code_send_insert(self, mock_post, _flag, _capture):+ self._cdp_accepts(mock_post)+ psak = self._sender_client("key_creator")+ with self.captureOnCommitCallbacks(execute=True):+ psak.post(self.send_email_url, self._code_send(), format="json")++ with CaptureQueriesContext(connection) as queries, self.captureOnCommitCallbacks(execute=True):+ response = psak.post(self.send_email_url, self._code_send(), format="json")++ assert response.status_code == status.HTTP_202_ACCEPTED, response.json()+ assert [+ query["sql"]+ for query in queries.captured_queries+ if 'INSERT INTO "messaging_firstcodesend"' in query["sql"]+ ] == []++ def test_reports_a_projects_first_code_send_once(self, _mock_post, _flag, _capture):+ environment = Team.objects.create(organization=self.organization, parent_team=self.team, name="env")+ other_team = Team.objects.create(organization=self.organization)+ captured: list[int] = []++ def capture_for(team_id: int) -> Callable[[], bool]:+ def capture() -> bool:+ captured.append(team_id)+ return True++ return capture++ for team_id in (self.team.id, self.team.id, environment.id, other_team.id):+ report_first_code_send(team_id, capture_for(team_id))++ assert captured == [self.team.id, other_team.id]+@pytest.mark.ee@patch(