[Silthus]

Part of the code-first rebuild of the email send stack; replaces parts of PostHog#121867 (one send per idempotency key on send/email/).

Problem

• A developer who retries a keyed code send on send/email/ can get 422 idempotency_key_reused instead of a replay, after the project's default sender changed in between.
• The same happens to a send that names an address no sender owns exactly, because Django resolves it through the default sender. The first send already went out, so the retry should replay it.
• feat(messaging): mark a code send that leaves the sender to the project #578 is the Django half, which forwards the key and sets isDefault. This is the cdp-api half.

Impact

Pays into Grow Workflows through billed workflows_emails actions per paying org: callers can retry without double sends. In scope: CDP email sends.

Merge Danger

Warning

🔴 Merge risk: high · two-way door: a revert puts the resolved sender back in the key

• Deduplication on the CDP email delivery path changes, where a wrong replay drops an email in silence, so the grade is high even behind the flag.
• Only keyed code sends on transactional_email/send change, and only send/email/ makes them, behind workflows-email-from-code. The template route is unchanged.
• Rollout window: a keyed send queued by the older cdp-api keeps the sender's integration in its key. A retry within 24 hours after the deploy answers 422 instead of a replay, and a revert does the reverse.
• Contract: send.from.isDefault is new and optional. An older Django omits it, and the key then binds the integration as before.

Changes

Kind	Files	Lines
Production	2	+20 −1
Tests	1	+42 −0

• A keyed retry replays after the default sender changed. cdp-api leaves from out of the key when Django marks it as the project's default sender (isDefault).
• A keyed retry replays after a named address resolved to another sender. A named address keys on the address and name the caller sent, not on the integration id Django picked.
• A sender without an address keys on its integration and name only. An explicit isDefault: false and a missing flag give the same key, so a retry that leaves the flag out still replays.
• Rebased onto feat(cdp): deliver a code send's content on its own transactional email route #565 at master 43333f8. The earlier version also moved the active check after the key lookup and gave the inactive refusal its own why and fix. feat(cdp): deliver a code send's content on its own transactional email route #565 now does the first, and Django on master maps cdp-api's not_sendable itself (feat(messaging): refuse transactional sends the email worker would skip PostHog/posthog#123019), so both left this PR.

How did you test this code?

Test seams: cdp-api's accepted-send route over HTTP (cdp-api.serial.test.ts).

Test rationale: returns the first send for a retry of %s and queues nothing new, one table for every replay, run red first: a retry after the default sender or the integration behind a named address changed that answers 422, and a retry that leaves out isDefault: false. The two new rejects the key for a request with %s rows pin that another named sender, or a named sender instead of the default, still answers 422.

Proofs at 64d8940:

• Lane gate: typescript:check, eslint, oxlint and prettier pass, and cdp-api.serial.test.ts passes (168 tests).
• Shadow diff: cdp-api.serial.test.ts at HEAD, run against feat(cdp): deliver a code send's content on its own transactional email route #565's head 920e7c9, moves two outcomes: the two sender-change retries replay instead of answering 422. The changed-content, other-route and other-sender rows still answer 422. Evidence is saved with fleet proof.
• Live run and cross-version: owed at this head; lane dj3 of map Map: send code-managed email templates with one PostHog call #461 runs the live stack. Not run here.
• Prod shape: a gap until read-only production access exists on 2026-11-02.

Proofs at the pre-rebase head 1a43bdd, with Django at #578 79e619b

Case	Both new	Django before #578
Keyed send	202, delivered	202, delivered
Same request, same key	202 replayed: true, one email in total	202 replayed: false, two emails
Same key, another recipient	422 idempotency_key_reused, nothing sent	202, delivered: no key reaches cdp-api
Keyed send without from, then its retry	202 replayed: true, one email in total	two emails
That retry after the default sender changed	202 replayed: true, one email in total	three emails in total
Named from, retry after the default sender changed	202 replayed: true, one email in total	two emails in total
Template by id (control)	202, delivered	202, delivered

The paused-key rows of that table moved with the active check to #565.

CI: the fork has no Depot runners, so those jobs never start, and no secret for the project-board app, so flags-project-board fails. The lane check passes: against master the PR changes only nodejs/ (cross_lane=false).

Release status

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

Docs update

None in this PR. The send API docs follow when the flag opens.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: Claude Code, Claude Opus 5.5 (claude-opus-5-5)

Skills: tdd, writing-tests, stacking-prs, modernize-pr, pr-description, writing-pr-descriptions

Question	Answer	Who	Where
Does a reused key with a changed template.hash replay?	Yes, and the key's help text says what it binds	👤 Human	map #461, lane brief of 2026-10-25
May the code carry comments?	No; names carry the reasons	👤 Human	map #461, 2026-10-25
Shrink onto the upstream refusal code?	Yes; code that duplicates master goes	👤 Human	map #461, 2026-10-28
Keep the inactive refusal's own why and fix?	No; Django on master maps not_sendable to its own answer	🤖 Agent	map #461 lane node3, restack of 2026-10-31
Should a named address marked isDefault key on the address?	No; Django sets isDefault only when the caller named no address, so the address there is the default's and must stay out of the key	🤖 Agent	qa-swarm round 3, 2026-11-01
Do the cdp-api and Django halves land as one PR?	No: two PRs in either order, each safe against the other side's older version	🤖 Agent	pending approval

Involvement: rounds 1 and 2 and two final reads before the restack; after it, one GPT-6.1 Sol review, a full two-family panel on 2026-11-01 (8 lanes: 2 fixed, 1 rejected, shadow diff owed and run) and a narrow round (2 lanes: description fixes, 2 rejected); pre-rebase live and cross-version proof kept above.

More context for AI agents

• Session: lane node3 of map Map: send code-managed email templates with one PostHog call #461, Claude Code.
• Decisions: the base moved from feat(cdp): refuse an accepted send the send checks would skip #577 to feat(cdp): deliver a code send's content on its own transactional email route #565, because refactor(cdp): move the email send checks into one send policy #576 and feat(cdp): refuse an accepted send the send checks would skip #577 are superseded by master (fix(workflows): drop suppressed cc/bcc instead of skipping the email PostHog/posthog#118456, feat(messaging): refuse transactional sends the email worker would skip PostHog/posthog#123019, fix(messaging): refuse a transactional email to a recipient that can't receive email PostHog/posthog#123878, fix(messaging): stop suppression refusals dropping transactional email PostHog/posthog#123492).
• Read closely: senderTheCallerChose in nodejs/src/cdp/cdp-api.ts.
• Base merge: feat(cdp): deliver a code send's content on its own transactional email route #565's shared primary read and its replay test rewrite arrive through the merge of email-v2/01-cdp-code-send; they are feat(cdp): deliver a code send's content on its own transactional email route #565's diff, not this PR's.

🤖 Generated with Claude Code

[Silthus]

Moved to PostHog#127129.