[mayteio]

Problem

• A transactional email API caller who sends to an invalid address, or to a domain with no mail servers, gets 202 queued, but the email never goes out.
• The email worker skips that send because it would hard bounce, so the caller believes an email went out that never will.
• The cross-SDK contract in Transactional email SDK contract for posthog-python and posthog-node #120921 says every check that would skip a send runs before the 202. The recipient check did not.

Refs #120921

Changes

• A send to an unreachable recipient now gets 422 with the new error code recipient_unreachable and a message that asks the caller to check the address for a typo.
• refuseTransactionalEmail in the Node CDP API runs the same recipient check as the worker, through the new EmailValidationService.getRecipientSkipReason(teamId, email).
• getRecipientSkipReason is split out of getSkipReason, so the worker and the API share one check.
• The check runs last among the refusals, because a cache miss costs a DNS lookup.
• DNS failures fail open, so a DNS outage never blocks email.
• The worker keeps its own check, because state can change while the job waits in the queue.
• Django maps the new pipeline code: RecipientUnreachable contract, a PIPELINE_REFUSALS entry, and a 422 in TransactionalEmailRejected.STATUS_BY_CODE.
• Mechanical: createCdpCoreServices exposes emailValidationService, and the 422 OpenAPI description mentions the new case.

How did you test this code?

Test rationale: The new case in cdp-api.serial.test.ts ("refuses a send the email worker would skip because the recipient's domain has no mail servers") catches the API answering 202 for a send the worker would skip. It extends the existing parameterized refusal test. With the new refuseTransactionalEmail lines removed, it fails (202 instead of 422). The new row in test_reports_a_send_the_pipeline_refuses catches Django returning a server error for the new pipeline code. A beforeEach stub makes getRecipientSkipReason return null for the other cases, because the fixtures send to example.com, which publishes a null MX.

Run locally:

• cdp-api.serial.test.ts with -t "transactional email", and email-validation.service.test.ts.
• products/messaging/backend/tests/api/test_transactional_email.py.
• Repo-wide mypy, ruff, eslint and prettier on the changed files.

Not run: a real send against a live DNS resolver, or manual testing in a running stack.

Release status

• This change is behind a feature flag and is not available to users

Docs update

None in this repo. The transactional email docs page (PostHog/posthog.com#21564) should list the new recipient_unreachable error code.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: PostHog Desktop (Claude Code), Claude Opus 5.5

• Skills invoked: /writing-pr-descriptions.
• Duplicate search: gh pr list --state open --search "recipient unreachable transactional" found no open PR.
• Public artifact: all test data is invented and uses example.com. Nothing in this PR comes from customer material.

🤖 Generated with Claude Code

---

Created with PostHog Desktop

[trunk-io]

😎 Merged successfully - details.

[github-actions]

🤖 CI report

⚠️ Trunk lane — backend Python lane, mixes lanes

This PR is assigned to the backend Python lane. It runs backend Python tests and may merge in parallel with PRs in other lanes.

This PR changes Python or frontend code (products/messaging/backend/facade/contracts.py, products/messaging/backend/presentation/views/message_templates.py, products/messaging/backend/services/transactional_email.py and 1 more) and Node or Rust code (nodejs/src/cdp/cdp-api.serial.test.ts, nodejs/src/cdp/cdp-api.ts, nodejs/src/cdp/cdp-services.ts and 2 more) together. In the merge queue, every Node or Rust PR behind it in the same lane then runs the Django and frontend suites too, so the cross-lane check fails. Split it, or add the cross-lane-change label if the halves must land together.

✅ Duplication (Python) — clean

New Python code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

✅ Duplication (TypeScript) — clean

New TypeScript code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

[trunk-io]

   

Failed Test	Failure Summary	Logs
EmailService native email sending with maildev should include tracking code in the email with distinct_id	The test expected one matching item but received an empty array.	Logs ↗︎

View Full Report ↗︎ ⋅ Docs

[mayteio]

@PostHog review --deep

[mayteio]

@PostHog review

[posthog]

PostHog Review · Standard · reviewed 5289444: no findings.

This Standard review started from the posthog-review label. Comment @posthog review --deep for a Deep review, or @posthog help to see all commands.

[parameterai]

Risk: No findings

Since the last review this PR only merged master and updated a test to match master's new behavior (quota-limited transactional sends queue instead of refusing), plus added two echo fields to the preferences-token validation response. The two new response fields are claims from a server-signed, fail-closed-verified JWT, so they disclose nothing the token holder could not already decode from the token itself, and the recipient-unreachable refusal chain is intact after the merge.

_{Sentinel reviewed 95ea844 · Review settings}

[stamphog]

Approved.

The disclosed API and send-path changes have independent assurance from a current-head review and owning-team authorship. No unresolved substantive review concerns or other policy refusal grounds were found.

• Author wrote 50% of the modified lines and has 39 merged PRs in these paths (familiarity MODERATE).
• PostHog Review (Standard) reviewed the current head: no findings.
• posthog[bot] reviewed the current head.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	41L, 7F substantive, 52L/9F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1c-medium (52L, 9F, two-areas, fix)
stamphog 2.6.1		.stamphog/policy.yml @ 5289444 · reviewed head 5289444

[mayteio]

/trunk merge

[trunk-io]

An error occurred while submitting your PR to the queue: This PR is already merged

[deployment-status-posthog]

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-10-27 17:36 UTC	Run
prod-us	✅ Deployed	2026-10-27 18:00 UTC	Run
prod-eu	✅ Deployed	2026-10-27 17:55 UTC	Run