[Silthus]

Part of the code-first rebuild of the email send stack; new in the rebuild, with no closed PR to replace: a template send delivers the content Django graded (decision D3 on map #461).

Problem

• A template send on send/email/ right after an upload can deliver the previous content, while Django answered that the caller's template.hash is current.
• Django grades the hash, but the email goes out from the workflow copy cdp-api and the worker cached, which can lag after a lost reload.
• This is the Django half: it tells cdp-api which workflow version holds the graded content. The cdp-api and worker half is feat(cdp): send a template from the workflow version Django graded #584.

Impact

Pays into Grow Workflows through billed workflows_emails actions per paying org: a developer who uploads a template and sends it at once gets the new content. In scope: the send/email/ route.

Merge Danger

Note

🟢 Merge risk: low · two-way door: a revert stops sending the version, and delivery works as today

• Template sends on send/email/ only, behind workflows-email-from-code. Rendered-content sends and the legacy template send route don't change.
• No order against feat(cdp): send a template from the workflow version Django graded #584. A cdp-api without feat(cdp): send a template from the workflow version Django graded #584 strips the unknown field and sends as today. The cross-version runs in feat(cdp): send a template from the workflow version Django graded #584 show it.
• The node stack deploys first. Every send by template.key now goes to cdp-api's /transactional_email/send, which feat(cdp): deliver a code send's content on its own transactional email route #565 adds. Against cdp-api master, those sends answer 503 delivery_unavailable and send nothing (cross-version proof below). They stay behind workflows-email-from-code.
• feat(messaging): send the workflow version a template send by key was checked against #585 lands with feat(messaging): capture email first code send once per project #583. A keyed retry of a send by template.key that crosses a deploy of feat(messaging): capture email first code send once per project #583 without feat(messaging): send the workflow version a template send by key was checked against #585 answers 422, because the two pick different routes for one fingerprint. Key sends exist only inside this stack, so no stored fingerprint has that shape today.
• One more primary read of the workflow's version per template send.
• The version-behind 503 reaches a caller only when cdp-api answers it, which only feat(cdp): send a template from the workflow version Django graded #584 does.

Changes

Kind	Files	Lines
Production	5	+56 −8
Tests	2	+88 −7

• A template send posts the version of its workflow that holds the graded content, as send.hogFlowVersion. Django reads it after grading the hash, from the writer database, so it is never older than the graded content.
• A workflow deleted between the grade and the version read answers as the cdp-api 404 does today (Unavailable to the caller), without a stack trace in the log.
• A send that the email pipeline can't deliver yet gets a 503 that says so. When cdp-api still holds an older workflow version than the graded one, the caller gets master's 503 delivery_unavailable shape with its own detail:

{
  "type": "server_error",
  "code": "delivery_unavailable",
  "detail": "This template's newest version hasn't reached the email pipeline yet, so nothing was sent. Retry in a few seconds, with the same Idempotency-Key if you sent one.",
  "attr": null
}

• Nothing was sent in that case, so a retry is safe with or without a key. The internal reason, workflow_version_behind, never reaches the caller.
• Every other 503 keeps master's body, on both routes.
• Every send by template.key posts the version, with or without from, reply_to or capture_engagement, so it goes to the accepted-send route. Its default captureEngagement: true changes nothing: the project's setting still decides.
• A send by template.id keeps master's route, which grades no hash and posts no version. One that sets capture_engagement (feat(messaging): send a stored template by key on send/email #574), which takes workflows-email-from-code, goes to the accepted-send route and posts the version, like a send by template.key. Only a field the caller sent counts, so a form body that omits it keeps master's route.
• No serializer or OpenAPI change, so no regenerated types.

How did you test this code?

Test seams: the DRF client on send/email/, asserting the body posted to cdp-api (test_transactional_email.py).

Test rationale, each run red first:

• A send by template.key that posts no version, with or without the send options, or a version from before a save. A PATCH that saves new content is followed by a send that must post the new version.
• A version read from a lagging read replica.
• A workflow deleted before the version read that logs an exception.
• The three rendered-content rows compare the whole send dict, which pins that the field is absent there.
• A version-behind 503 from cdp-api that answers the generic 503, or that puts workflow_version_behind anywhere in the body.

Proofs (saved with fleet proof on ef44c9b):

• Live run: Django at this head, cdp-api and both CDP workers at the node stack (f9abed0841c), mail caught in maildev. Sends by id and by template.key, uploads, the superseded and outdated hashes, and the send options all answer and deliver as on feat(messaging): capture email first code send once per project #583.
• SDK live run on 5304e8d (cdp-api at feat(cdp): send a template from the workflow version Django graded #584's 5d66b71): posthog-node (feat(node): upload local email templates by hash on send posthog-js#7) and posthog-python (feat: send email content from code with posthog.emails.send posthog-python#2) send a local template under a new key: 409 template_outdated, upload 201, send 202, delivered. Onto a template edited in PostHog, the upload answers 409 template_edited_in_posthog (feat(messaging): lock code-managed templates and adopt templates into code #631), the SDK reports it, and nothing is sent.
• Shadow diff against feat(messaging): capture email first code send once per project #583's head, same cases: no difference in responses, mail or usage events.
• Cross-version, this head against cdp-api master: sends by template.key answer 503 delivery_unavailable and send nothing. Sends by id deliver.
• Prod shape: a gap until read-only production access exists on 2026-11-02.
• Lane gate on this head: ruff, the IDOR check, the migration checks, repo-wide mypy, and the messaging and workflows tests pass.

Earlier live run, 2026-10-31

Django at 3a30f51c529, cdp-api and both CDP workers at #584 (f9abed0841c), mail caught in maildev.

Send by template.key	Result
Current hash, right after an upload changed the content	202, the new content delivered
Superseded hash	202 with the template_superseded warning, the new content delivered
A hash PostHog doesn't hold	409 template_outdated, nothing sent
With from, reply_to and capture_engagement	202, sent from support@example.com
posthog-node local template (Silthus/posthog-js#7), new key	409, upload, then 202

CI: the fork has no Depot runners, so those jobs never start. Semgrep Checks Pass fails on every fork PR, because its path filter job runs only for the PostHog owner; semgrep with the repo's rules passes locally on the changed files. The lane check reports cross_lane=false.

Release status

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

Docs update

None.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

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

• Built as lane srv2 of map Map: send code-managed email templates with one PostHog call #461, for decision D3; restacked as lane dj3 onto feat(messaging): capture email first code send once per project #583 and master's refusal code, so the 503 drops its why and fix.
• Skills: modernize-pr, tdd, writing-tests, writing-user-facing-copy, qa-swarm, pr-description, writing-pr-descriptions.

Question	Answer	Who	Where
Does a template send deliver what Django graded?	Yes, through #584 and this PR	👤 Human	map #461, decision D3 of 2026-10-25
May the code carry comments?	No; names carry the reasons	👤 Human	map #461, 2026-10-25
What does a send get when the pipeline holds an older version?	The contract's 503 delivery_unavailable with the version lag in detail; replaces a new public workflow_version_behind code	👤 Human	approved (conductor, 2026-10-26)
Does a 503 carry why and fix?	No; this stack reuses master's refusal shape, so the lag goes in detail	👤 Human	map #461, 2026-10-28
Key the cache on the hash, or on a version floor?	A version floor, read after grading from the writer; replaces D3's "key the cache on the hash"	👍 Accepted default	approved (conductor, 2026-10-26)
Does a send by template.id with capture_engagement post the version?	Yes, it takes the accepted-send route like a key send; other id sends keep master's route	🤖 Agent	dj3 QA swarm, 2026-11-01
Must #585 deploy with #583?	Yes; apart, a keyed retry of a key send answers 422. Kept as a stated condition, not code	🤖 Agent	dj3 QA swarm, 2026-11-01
Must the retry reuse the key?	Only if the caller sent one: nothing was sent, so a retry without a key is safe too	👍 Accepted default	approved (conductor, 2026-10-26)

Open: a send by template.id posts no version, so one right after an upload can still use the cached copy. Recommendation: leave it; that send grades no hash.

Involvement: one decision from Michael and one from the map's conductor; review round 1 (GPT-6.1 Sol, Opus fresh eyes) fixed, then final reads by GPT-6.1 Sol; dj3 round 1 (GPT-6.1 Sol) fixed, its final read raised the cdp-api route order, answered in the merge risk; live run captured; cross-version proof in #584. dj3 QA swarm (GPT-6.1 Sol review, Opus fresh eyes): one merge fix, two rejections; live run, shadow diff and cross-version on this head.

🤖 Generated with Claude Code

[Silthus]

Moved to PostHog#127188.