[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. An older cdp-api 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.
• One more primary read of the workflow's version per template send.
• The explained 503 reaches a caller only when cdp-api answers the version-behind 503, which only feat(cdp): send a template from the workflow version Django graded #584 sends.

Changes

Kind	Files	Lines
Production	4	+79 −3
Tests	1	+87 −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 an explained 503. When cdp-api still holds an older workflow version than the graded one, the caller gets the contract's 503 delivery_unavailable, with why and fix:

{
  "type": "server_error",
  "code": "delivery_unavailable",
  "detail": "This template's newest version hasn't reached the email pipeline yet.",
  "attr": null,
  "why": "The email pipeline still holds an older version than the one PostHog checked the send against, so nothing was sent.",
  "fix": "Retry in a few seconds. If you sent an Idempotency-Key, use the same key.",
  "docs_url": ".../transactional-email-api#delivery_unavailable"
}

• Nothing was sent in that case, so a retry is safe with or without a key. Django logs the internal reason, workflow_version_behind, which never reaches the caller.
• Every other 503 keeps its current body, on both routes. Unavailable gains optional detail, why and fix, and only this case sets them.
• 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 template send that posts no version, 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. The existing 503 rows pin that their bodies have no why or fix key at all, not even a null one.

Proofs: live and cross-version runs are in #584, with this head as the Django side. Prod shape: a gap until read-only production access exists on 2026-11-02.

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 other GitHub-hosted checks pass. The lane check passes: against master the PR changes only the Python and frontend side.

Release status

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

Docs update

None in this PR. The explained 503 links to the #delivery_unavailable anchor of the transactional email API docs, which the docs for this stack need to carry.

🤖 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.
• Skills: tdd, writing-tests, writing-user-facing-copy, 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 and why; replaces a new public workflow_version_behind code	👤 Human	approved (conductor, 2026-10-26)
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)
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)

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; live and cross-version proof captured in #584.

🤖 Generated with Claude Code