: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(signals): improve and attribute the first report email (#121309)
Georgiy Tarasov807006d52b18
diff --git a/products/signals/ARCHITECTURE.md b/products/signals/ARCHITECTURE.mdindex 31dc1ea5dda9..098f171a7904 100644--- a/products/signals/ARCHITECTURE.md+++ b/products/signals/ARCHITECTURE.md@@ -240,12 +240,16 @@ On re-promotion:Guided and quick onboarding create a `SignalFirstReportNotification` in the activation transaction, preserving the activating user for that environment. The first report that becomes `ready`, immediately actionable, and not already addressed after activation triggers a transactional email to that user's email address, tracked against their distinct ID. Control onboarding does not identify an activator and does not enroll a recipient.-Sending requires the organization-scoped `signals-first-report-email` feature flag and is cloud-only. A disabled, missing, or unavailable flag leaves notifications pending without claiming or cancelling them, including in DEBUG. Sending also remains disabled until the dedicated `POSTHOG_TRANSACTIONAL_EMAIL_API_KEY` is configured. `SIGNALS_FIRST_REPORT_EMAIL_TEMPLATE_ID` in `backend/constants.py` selects the first-report transactional email template. The shared `POSTHOG_PROJECT_ID` and `POSTHOG_HOST` settings default to `2` and `https://us.posthog.com`, independently of the recipient's region. Both support optional environment overrides to select another sending project or host. The API key must be a project secret API key with `hog_flow:write` for that sending project, and the template must be an active transactional email template with a verified sender. Sending uses the shared transactional email client synchronously inside the notification task so the notification row can record the API's acceptance. Template creation and deployment configuration are separate from this code. The template can use `{{ variables.project_id }}`, `{{ variables.report_id }}`, `{{ variables.report_title }}`, `{{ variables.report_url }}`, and `{{ variables.activation_id }}`. All template data is supplied explicitly; the recipient need not have a person profile in the sending project.+Sending requires the organization-scoped `signals-first-report-email` feature flag and is cloud-only. A disabled, missing, or unavailable flag leaves notifications pending without claiming or cancelling them, including in DEBUG. Sending also remains disabled until the dedicated `POSTHOG_TRANSACTIONAL_EMAIL_API_KEY` is configured. `SIGNALS_FIRST_REPORT_EMAIL_TEMPLATE_ID` in `backend/constants.py` selects the first-report transactional email template. The shared `POSTHOG_PROJECT_ID` and `POSTHOG_HOST` settings default to `2` and `https://us.posthog.com`, independently of the recipient's region. Both support optional environment overrides to select another sending project or host. The API key must be a project secret API key with `hog_flow:write` for that sending project, and the template must be an active transactional email template with a verified sender. Sending uses the shared transactional email client synchronously inside the notification task so the notification row can record the API's acceptance. Template creation and deployment configuration are separate from this code.++The template can use `{{ variables.project_id }}`, `{{ variables.report_id }}`, `{{ variables.report_title }}`, `{{ variables.report_summary }}`, `{{ variables.report_priority }}`, `{{ variables.report_url }}`, and `{{ variables.activation_id }}`. `report_summary` is the summary's first line, capped at 320 characters, matching the report's Inbox preview. `report_priority` is the latest Inbox priority judgment (`P0`–`P4`), or an empty string when unavailable. Both values are captured with the title and URL when the report is first claimed and remain unchanged on retry. Templates must omit the description and priority badge when those variables are missing, including for payloads captured before they were introduced. All template data is supplied explicitly; the recipient need not have a person profile in the sending project.Report and actionability writes enqueue delivery on the Celery `email` queue after commit. A sweep on the default Celery queue runs every five minutes to recover missed enqueues and retry confirmed rejections. The sweep skips database queries and task fan-out when cloud delivery or the shared sender configuration is disabled. A `Retry-After` response sets `next_attempt_at`; both delivery claims and the sweep respect that deadline, and the Celery retry uses the same delay. Delivery rechecks report visibility, organization membership, project access, and report access, and never substitutes another recipient. The selected report and template data persist across retries. A selected report undergoing research stays pending until it becomes visible again. `queued_at` and `message_id` record acceptance by the transactional pipeline, not delivery to the recipient's mailbox. Sending does not wait for implementation or Slack notification delivery.The transactional send API has no idempotency key. `send_started_at` is committed before the send, so concurrent workers, uncertain responses, and worker loss cannot automatically queue a duplicate. Confirmed pre-send failures, quota rejections, and connection timeouts clear that marker and can retry. A row with `send_started_at` set and `queued_at` unset requires reconciliation against the sending project's workflow history before retrying: record the accepted message if found, or clear the marker only after confirming nothing was queued. A crash before the request can also leave such a row. Uncertain outcomes are held rather than retried automatically.+Report links carry `link_source=first_report_email`, which the existing `Inbox report opened` event records. Workflows already captures email sends, delivery, opens, and link clicks. Join report engagement to the existing `Inbox report action completed` event (`action_type=create_pr`, `outcome=success`) by `report_id` to measure successful implementation kickoff, and use `pr_created.signal_report_id` for tracked PR outcomes. `Inbox report action` with `action_type=copy_implementation_prompt` records handoff intent; `agent=clipboard` distinguishes copying from agent deep links. Successful kickoff means the API accepted the implementation request, and handoff intent does not prove an external agent started work.+### `SignalReportReingestionWorkflow` (`signal-report-reingestion`)Deletes a report and re-ingests its signals through the current Signals ingestion pipeline. Useful when grouping decisions need to be re-evaluated after prompt or matching changes.diff --git a/products/signals/backend/first_report_notification.py b/products/signals/backend/first_report_notification.pyindex 68658451c448..267909ad281b 100644--- a/products/signals/backend/first_report_notification.py+++ b/products/signals/backend/first_report_notification.py@@ -7,6 +7,7 @@ from django.core.exceptions import ImproperlyConfiguredfrom django.db import transactionfrom django.db.models import Qfrom django.utils import timezone+from django.utils.text import Truncatorimport structlog@@ -18,7 +19,6 @@ from posthog.transactional_email import (is_transactional_email_configured,send_transactional_email,)-from posthog.utils import absolute_urifrom products.access_control.backend.facade.user_access_control import UserAccessControlfrom products.signals.backend.artefact_schemas import ActionabilityChoice@@ -26,6 +26,8 @@ from products.signals.backend.constants import SIGNALS_FIRST_REPORT_EMAIL_TEMPLAfrom products.signals.backend.models import SignalFirstReportNotification, SignalReportfrom products.signals.backend.report_access import may_read_reportsfrom products.signals.backend.report_content_gates import team_first_report_email_enabled+from products.signals.backend.report_priority import latest_report_priorities+from products.signals.backend.report_urls import ReportLinkSource, build_report_urlif TYPE_CHECKING:from django.db.models import QuerySet@@ -109,7 +111,9 @@ def _claim(team_id: int) -> SignalFirstReportNotification | None:"project_id": team_id,"report_id": str(report.id),"report_title": report.title,- "report_url": absolute_uri(f"/project/{team_id}/inbox/reports/{report.id}"),+ "report_summary": Truncator((report.summary or "").strip().split("\n", 1)[0]).chars(320),+ "report_priority": latest_report_priorities(team_id, [str(report.id)]).get(str(report.id), ""),+ "report_url": build_report_url(team_id, report.id, ReportLinkSource.FIRST_REPORT_EMAIL),"activation_id": str(notification.id),}# The transactional API has no idempotency key. A crash or uncertain response must leavediff --git a/products/signals/backend/report_urls.py b/products/signals/backend/report_urls.pyindex cd3f8985bb1c..1e7435dbaf84 100644--- a/products/signals/backend/report_urls.py+++ b/products/signals/backend/report_urls.py@@ -12,6 +12,7 @@ from posthog.utils import absolute_uriclass ReportLinkSource(StrEnum):+ FIRST_REPORT_EMAIL = "first_report_email"MCP = "mcp"SLACK = "slack"SLACK_SCOUT = "slack_scout"diff --git a/products/signals/backend/test/test_first_report_notification.py b/products/signals/backend/test/test_first_report_notification.pyindex eb92d710ea2d..ca479379e1cd 100644--- a/products/signals/backend/test/test_first_report_notification.py+++ b/products/signals/backend/test/test_first_report_notification.py@@ -1,3 +1,4 @@+import jsonfrom datetime import UTC, datetime, timedeltafrom uuid import uuid4@@ -80,9 +81,29 @@ class TestFirstReportNotification(BaseTest):def notification(self) -> SignalFirstReportNotification:return SignalFirstReportNotification.objects.for_team(self.team.id).get()+ @parameterized.expand(+ [+ (+ "summary_lead",+ "Users cannot accept expired invitations.\n\n## Evidence\nMore details.",+ "Users cannot accept expired invitations.",+ "P1",+ ),+ ("long_summary_without_priority", "x" * 400, "x" * 319 + "…", ""),+ ]+ )@time_machine.travel("2026-01-15T12:01:00Z", tick=False)- def test_first_report_targets_activator_once_per_project(self) -> None:- first = self.report(first_visible_at=timezone.now() - timedelta(seconds=1))+ def test_first_report_targets_activator_once_per_project(+ self, _name: str, summary: str, expected_summary: str, priority: str+ ) -> None:+ first = self.report(first_visible_at=timezone.now() - timedelta(seconds=1), summary=summary)+ if priority:+ SignalReportArtefact.objects.create(+ team=self.team,+ report=first,+ type=SignalReportArtefact.ArtefactType.PRIORITY_JUDGMENT,+ content=json.dumps({"priority": priority, "explanation": "The invitation flow is blocked."}),+ )self.report()other_user = User.objects.create_and_join(self.organization, "[email protected]", None)register_first_report_notification(team=self.team, user=other_user)@@ -98,7 +119,9 @@ class TestFirstReportNotification(BaseTest):"project_id": self.team.id,"report_id": str(first.id),"report_title": first.title,- "report_url": f"https://app.example.com/project/{self.team.id}/inbox/reports/{first.id}",+ "report_summary": expected_summary,+ "report_priority": priority,+ "report_url": f"https://app.example.com/project/{self.team.id}/inbox/reports/{first.id}?link_source=first_report_email","activation_id": str(self.notification().id),},)@@ -169,6 +192,14 @@ class TestFirstReportNotification(BaseTest):initial_send = self.send.call_argsassert self.notification().send_started_at is Noneassert self.notification().last_error+ first.summary = "Updated after the first send attempt."+ first.save(update_fields=["summary"])+ SignalReportArtefact.objects.create(+ team=self.team,+ report=first,+ type=SignalReportArtefact.ArtefactType.PRIORITY_JUDGMENT,+ content=json.dumps({"priority": "P0", "explanation": "Impact increased after the first send attempt."}),+ )self.report(first_visible_at=timezone.now() - timedelta(seconds=1))self.send.side_effect = Nonediff --git a/products/signals/frontend/inbox/inboxAnalytics.ts b/products/signals/frontend/inbox/inboxAnalytics.tsindex 567e9dff599a..a06c757c101b 100644--- a/products/signals/frontend/inbox/inboxAnalytics.ts+++ b/products/signals/frontend/inbox/inboxAnalytics.ts@@ -122,6 +122,7 @@ export type InboxReportOpenMethod = 'click' | 'deeplink' | 'triage' | 'unknown'* `ReportLinkSource` in `products/signals/backend/report_urls.py`.*/export const INBOX_REPORT_LINK_SOURCES = [+ 'first_report_email','mcp','slack','slack_scout',diff --git a/products/signals/frontend/inbox/inboxSceneLogic.test.ts b/products/signals/frontend/inbox/inboxSceneLogic.test.tsindex 128fd8dfd793..39c089248485 100644--- a/products/signals/frontend/inbox/inboxSceneLogic.test.ts+++ b/products/signals/frontend/inbox/inboxSceneLogic.test.ts@@ -322,6 +322,13 @@ describe('inboxSceneLogic routing', () => {it.each([{ name: 'no param', source: undefined, visitedList: false, method: 'deeplink', linkSource: null },{ name: 'a known source', source: 'slack', visitedList: false, method: 'deeplink', linkSource: 'slack' },+ {+ name: 'the first report email',+ source: 'first_report_email',+ visitedList: false,+ method: 'deeplink',+ linkSource: 'first_report_email',+ },{name: 'an unknown source',source: 'carrier-pigeon',