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(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.yaml
index 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
|GitHubSyncPlan
diff --git a/products/messaging/backend/facade/transactional_email.py b/products/messaging/backend/facade/transactional_email.py
index 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.py
new file mode 100644
index 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.txt
index 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_send
diff --git a/products/messaging/backend/models/__init__.py b/products/messaging/backend/models/__init__.py
index 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 FirstCodeSend
from .message_category import MessageCategory, MessageCategoryType
from .message_preferences import ALL_MESSAGE_PREFERENCE_CATEGORY_ID, MessageRecipientPreference, PreferenceStatus
from .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.py
new file mode 100644
index 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.py
index 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 ForbidDestroyModel
from posthog.api.mixins import ResponseDeclaration, validated_request
from posthog.api.routing import TeamAndOrgViewSetMixin
from posthog.api.shared import UserBasicSerializer
-from posthog.auth import ProjectSecretAPIKeyAuthentication
+from posthog.auth import ProjectSecretAPIKeyAuthentication, ProjectSecretAPIKeyUser
from posthog.event_usage import groups, report_user_action
from posthog.integrations import IntegrationManager, IntegrationNotFound
-from posthog.models import User
+from posthog.models import ProjectSecretAPIKey, User
from posthog.models.tag import tagify
from posthog.permissions import is_authenticated_via_project_secret_api_key, legacy_scope_object_used
from 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.py
index 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, TransactionalEmailKey
from products.messaging.backend.models.message_category import MessageCategoryType
from products.messaging.backend.services.html_text import text_from_html
from 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.py
index 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 Callable
from typing import Any, get_args
from uuid import UUID, uuid4
@@ -6,6 +7,9 @@ import pytest
from posthog.test.base import APIBaseTest
from unittest.mock import MagicMock, patch
+from django.db import connection
+from django.test.utils import CaptureQueriesContext
+
import requests
from parameterized import parameterized
from prometheus_client import REGISTRY
@@ -14,12 +18,15 @@ from rest_framework.test import APIClient
from structlog.testing import capture_logs
from posthog.constants import AvailableFeature
+from posthog.dataclasses import frozen
from posthog.models import OrganizationMembership, ProjectSecretAPIKey, Team, User
from 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_secret
from 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 FirstCodeSend
from products.messaging.backend.models.message_category import MessageCategory, MessageCategoryType
from products.messaging.backend.models.message_template import MessageTemplate
from 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(