From a7cd02cdc1530563d63eafa6c01cdd4cd7fc22d6 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 11:05:12 +0000
Subject: [PATCH 01/42] feat(messaging): add code-managed fields to message
 templates

A template uploaded from a repository needs to record who owns its
content, which file it came from, and a hash of what it publishes. This
adds those columns (all nullable) and the content hash function. No
route reads or writes them yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/facade/contracts.py     |  5 ++
 ...015_messagetemplate_code_managed_fields.py | 72 +++++++++++++++++++
 .../backend/migrations/max_migration.txt      |  2 +-
 .../backend/models/message_template.py        | 30 ++++++++
 .../backend/services/content_hash.py          | 19 +++++
 .../backend/tests/test_content_hash.py        | 33 +++++++++
 6 files changed, 160 insertions(+), 1 deletion(-)
 create mode 100644 products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py
 create mode 100644 products/messaging/backend/services/content_hash.py
 create mode 100644 products/messaging/backend/tests/test_content_hash.py

diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index ca909adcb536..244993502a90 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -193,3 +193,8 @@ class EmailStatus:
     status_at: datetime
     # Why a send failed, or the bounce type of a bounced email.
     reason: str | None = None
+
+
+class TemplateManagedBy(LabeledStrEnum):
+    GUI = "gui", "GUI"
+    CODE = "code", "Code"
diff --git a/products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py b/products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py
new file mode 100644
index 000000000000..f671e9c6eb5d
--- /dev/null
+++ b/products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py
@@ -0,0 +1,72 @@
+import django.contrib.postgres.fields
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("messaging", "0014_transactional_email_key"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="messagetemplate",
+            name="content_hash",
+            field=models.CharField(
+                blank=True,
+                help_text="Hash of the published subject, preheader, HTML and text, as `v1:` and 64 hex characters.",
+                max_length=80,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="messagetemplate",
+            name="managed_by",
+            field=models.CharField(
+                blank=True,
+                choices=[("gui", "GUI"), ("code", "Code")],
+                help_text="Who owns the template content: `gui` for the PostHog app, `code` for uploads from a repository. Empty means `gui`.",
+                max_length=400,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="messagetemplate",
+            name="source_path",
+            field=models.CharField(
+                blank=True,
+                help_text="Path of the template file in the source repository.",
+                max_length=400,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="messagetemplate",
+            name="source_ref",
+            field=models.CharField(
+                blank=True,
+                help_text="Commit or branch of the last upload.",
+                max_length=400,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="messagetemplate",
+            name="source_repository",
+            field=models.CharField(
+                blank=True,
+                help_text="Repository the template was last uploaded from, such as `github.com/example/app`.",
+                max_length=400,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="messagetemplate",
+            name="superseded_content_hashes",
+            field=django.contrib.postgres.fields.ArrayField(
+                base_field=models.CharField(max_length=80),
+                blank=True,
+                null=True,
+                size=None,
+            ),
+        ),
+    ]
diff --git a/products/messaging/backend/migrations/max_migration.txt b/products/messaging/backend/migrations/max_migration.txt
index 9550c176e213..87dded8864f4 100644
--- a/products/messaging/backend/migrations/max_migration.txt
+++ b/products/messaging/backend/migrations/max_migration.txt
@@ -1 +1 @@
-0014_transactional_email_key
+0015_messagetemplate_code_managed_fields
diff --git a/products/messaging/backend/models/message_template.py b/products/messaging/backend/models/message_template.py
index 0670af8610d2..91119380e3d7 100644
--- a/products/messaging/backend/models/message_template.py
+++ b/products/messaging/backend/models/message_template.py
@@ -1,8 +1,11 @@
+from django.contrib.postgres.fields import ArrayField
 from django.db import models
 
 from posthog.models.tagged_items_relation import Taggable
 from posthog.models.utils import UUIDTModel
 
+from products.messaging.backend.facade.contracts import TemplateManagedBy
+
 KEY_CONSTRAINT = "unique_message_template_key_per_team"
 
 
@@ -37,6 +40,33 @@ class MessageTemplate(Taggable, UUIDTModel):
         help_text="Client-chosen identifier, unique within this environment among templates that are not deleted. "
         "Letters, numbers, hyphens (-) and underscores (_) only.",
     )
+    managed_by = models.CharField(
+        max_length=400,
+        choices=TemplateManagedBy.choices,
+        null=True,
+        blank=True,
+        help_text="Who owns the template content: `gui` for the PostHog app, `code` for uploads from a repository. "
+        "Empty means `gui`.",
+    )
+    source_repository = models.CharField(
+        max_length=400,
+        null=True,
+        blank=True,
+        help_text="Repository the template was last uploaded from, such as `github.com/example/app`.",
+    )
+    source_path = models.CharField(
+        max_length=400, null=True, blank=True, help_text="Path of the template file in the source repository."
+    )
+    source_ref = models.CharField(
+        max_length=400, null=True, blank=True, help_text="Commit or branch of the last upload."
+    )
+    content_hash = models.CharField(
+        max_length=80,
+        null=True,
+        blank=True,
+        help_text="Hash of the published subject, preheader, HTML and text, as `v1:` and 64 hex characters.",
+    )
+    superseded_content_hashes = ArrayField(models.CharField(max_length=80), null=True, blank=True)
 
     class Meta:
         db_table = "posthog_messagetemplate"
diff --git a/products/messaging/backend/services/content_hash.py b/products/messaging/backend/services/content_hash.py
new file mode 100644
index 000000000000..6958ad9c0bb1
--- /dev/null
+++ b/products/messaging/backend/services/content_hash.py
@@ -0,0 +1,19 @@
+import hashlib
+from typing import Any
+
+HASH_PREFIX = "v1:"
+HASHED_FIELDS = ("subject", "preheader", "html", "text")
+
+_ENCODING_HEADER = b"posthog-email-template-v1\n"
+
+
+def email_content_hash(email: dict[str, Any]) -> str:
+    encoded = bytearray(_ENCODING_HEADER)
+    for field in HASHED_FIELDS:
+        value = _normalized_line_endings(email.get(field) or "").encode()
+        encoded += f"{len(value)}:".encode() + value + b"\n"
+    return HASH_PREFIX + hashlib.sha256(encoded).hexdigest()
+
+
+def _normalized_line_endings(value: str) -> str:
+    return value.replace("\r\n", "\n").replace("\r", "\n")
diff --git a/products/messaging/backend/tests/test_content_hash.py b/products/messaging/backend/tests/test_content_hash.py
new file mode 100644
index 000000000000..6b0c90ed2368
--- /dev/null
+++ b/products/messaging/backend/tests/test_content_hash.py
@@ -0,0 +1,33 @@
+from django.test import SimpleTestCase
+
+from parameterized import parameterized
+
+from products.messaging.backend.services.content_hash import email_content_hash
+
+
+class TestEmailContentHash(SimpleTestCase):
+    @parameterized.expand(
+        [
+            (
+                "fields_absent",
+                {"subject": "Welcome, {{ variables.first_name }}", "html": "<p>Hi {{ variables.first_name }}</p>"},
+                "v1:f74cd913f3aa2e5667a588f2865634e56693df77793ca594d18e9b5f89e3d2e6",
+            ),
+            (
+                "non_ascii",
+                {"subject": "Grüße", "preheader": "Vorschau", "html": "<p>ä</p>", "text": "ä"},
+                "v1:75cf6fc3189ca26f60da672d29a1d4c89c7db3dd458df3a550a34a4d2a92c149",
+            ),
+            (
+                "windows_line_endings",
+                {
+                    "subject": "Welcome, {{ variables.first_name }}",
+                    "html": "<p>Hi {{ variables.first_name }}</p>",
+                    "text": "\r\n\r",
+                },
+                "v1:8112876ee1b2dd7327f571b04b546ed057bfff5a904d9f0ae507b6a449ab6453",
+            ),
+        ]
+    )
+    def test_matches_the_spec_test_vectors(self, _name: str, email: dict, expected: str) -> None:
+        assert email_content_hash(email) == expected

From 5ce7197dbb45f5e8049c9a7bf5ff8594c38283bb Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 11:09:09 +0000
Subject: [PATCH 02/42] feat(messaging): upload email templates from code by
 key

`PUT /api/projects/:id/messaging_templates/by_key/:key/` creates or
updates the template with that key from HTML kept in a repository. The
first upload makes it transactional with the project's default verified
sender; later uploads publish changed content at once, answer
`unchanged` for the same content and, with `if_not_superseded`,
`superseded` for content a newer upload replaced. Code sends under a
key move to the template's workflow once an upload claims the key.

The upload sits behind `workflows-email-from-code`, keeps the PSAK
bypass and workflow access checks of the send route, gets its own rate
limits, and reports a usage event. The MCP tool
`workflows-upload-email-template` calls it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/facade/contracts.py     |  38 ++
 .../messaging/backend/facade/templates.py     | 108 ++++-
 .../backend/facade/transactional_email.py     |   4 -
 .../presentation/views/message_templates.py   | 424 ++++++++++++++----
 .../presentation/views/template_refusals.py   |  83 ++++
 .../backend/services/content_hash.py          |  19 +
 .../backend/services/message_templates.py     |  55 ++-
 .../backend/services/template_saves.py        |  71 +++
 .../backend/services/template_uploads.py      | 187 ++++++++
 .../backend/services/transactional_email.py   |  45 +-
 .../backend/tests/api/test_template_upload.py | 376 ++++++++++++++++
 .../tests/api/test_transactional_email.py     |  52 ++-
 .../frontend/generated/api.schemas.ts         | 177 +++++++-
 products/messaging/frontend/generated/api.ts  |  24 +
 .../messaging/frontend/generated/api.zod.ts   |  62 ++-
 products/workflows/mcp/email_templates.yaml   |  24 +
 .../schema/generated-tool-definitions.json    |  16 +
 services/mcp/schema/tool-definitions-all.json |  16 +
 services/mcp/src/api/generated.ts             | 179 +++++++-
 .../mcp/src/generated/email_templates/api.ts  |  77 +++-
 .../src/tools/generated/email_templates.ts    |  48 ++
 .../tool-schemas/workflows-send-email.json    |   2 +-
 .../workflows-upload-email-template.json      |  79 ++++
 23 files changed, 2003 insertions(+), 163 deletions(-)
 create mode 100644 products/messaging/backend/presentation/views/template_refusals.py
 create mode 100644 products/messaging/backend/services/template_saves.py
 create mode 100644 products/messaging/backend/services/template_uploads.py
 create mode 100644 products/messaging/backend/tests/api/test_template_upload.py
 create mode 100644 services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json

diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 244993502a90..7744ebe3b122 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -195,6 +195,44 @@ class EmailStatus:
     reason: str | None = None
 
 
+TEMPLATE_KEY_PATTERN = r"^[a-zA-Z0-9_-]+$"
+TEMPLATE_KEY_MAX_LENGTH = 400
+
+
 class TemplateManagedBy(LabeledStrEnum):
     GUI = "gui", "GUI"
     CODE = "code", "Code"
+
+
+class TemplateUploadResult(LabeledStrEnum):
+    CREATED = "created", "Created"
+    UPDATED = "updated", "Updated"
+    UNCHANGED = "unchanged", "Unchanged"
+    SUPERSEDED = "superseded", "Superseded"
+
+
+class ContentHashState(LabeledStrEnum):
+    NONE = "none", "None"
+    CURRENT = "current", "Current"
+    SUPERSEDED = "superseded", "Superseded"
+    OUTDATED = "outdated", "Outdated"
+
+
+@frozen
+class TemplateSource:
+    repository: str | None
+    path: str | None
+    ref: str | None
+
+
+@frozen
+class TemplateUpload:
+    key: str
+    name: str
+    subject: str
+    html: str
+    text: str
+    preheader: str
+    design: dict[str, Any]
+    source: TemplateSource | None
+    if_not_superseded: bool
diff --git a/products/messaging/backend/facade/templates.py b/products/messaging/backend/facade/templates.py
index 24033eb2ec79..01773546093c 100644
--- a/products/messaging/backend/facade/templates.py
+++ b/products/messaging/backend/facade/templates.py
@@ -10,8 +10,13 @@
 from posthog.api.tagged_item import current_tag_names
 from posthog.dataclasses import frozen
 
+from products.messaging.backend.facade.contracts import TemplateManagedBy, TemplateUpload, TemplateUploadResult
 from products.messaging.backend.models.message_template import MessageTemplate
-from products.messaging.backend.services import message_templates as templates_service
+from products.messaging.backend.services import (
+    message_templates as templates_service,
+    template_saves,
+    template_uploads,
+)
 from products.messaging.backend.services.lazy_list import LazyList
 
 
@@ -38,10 +43,22 @@ class MessageTemplateRow:
     transactional_hog_flow_id: UUID | None
     draft_content: dict[str, Any] | None
     sensitive: bool
+    key: str | None
+    managed_by: TemplateManagedBy | None
+    source_repository: str | None
+    source_path: str | None
+    source_ref: str | None
+    content_hash: str | None
     # Tag names, sorted. Keeps its default last, so every field without one stays above it.
     tags: tuple[str, ...] = ()
 
 
+@frozen
+class UploadedTemplate:
+    result: TemplateUploadResult
+    template: MessageTemplateRow
+
+
 def _to_contract(row: MessageTemplate) -> MessageTemplateRow:
     return MessageTemplateRow(
         id=row.id,
@@ -57,6 +74,12 @@ def _to_contract(row: MessageTemplate) -> MessageTemplateRow:
         transactional_hog_flow_id=row.transactional_hog_flow_id,
         draft_content=row.draft_content,
         sensitive=row.sensitive,
+        key=row.key,
+        managed_by=TemplateManagedBy(row.managed_by) if row.managed_by else None,
+        source_repository=row.source_repository,
+        source_path=row.source_path,
+        source_ref=row.source_ref,
+        content_hash=row.content_hash,
         tags=tuple(sorted(current_tag_names(row))),
     )
 
@@ -90,21 +113,80 @@ def create_template(team_id: int, created_by_id: int | None, fields: dict[str, A
     return _to_contract(templates_service.create_template(team_id, created_by_id, fields))
 
 
-def update_template(team_id: int, template_id: UUID, fields: dict[str, Any]) -> MessageTemplateRow:
-    """Set the given fields and save the whole row. `message_category` holds a category id or None."""
-    return _to_contract(templates_service.update_template(team_id, template_id, fields))
+def save_template_tags(team_id: int, template_id: UUID, tags: list[str]) -> MessageTemplateRow:
+    return _to_contract(templates_service.save_template_tags(team_id, template_id, tags))
 
 
-def save_template_draft(team_id: int, template_id: UUID, draft: dict[str, Any] | None) -> MessageTemplateRow:
-    """Replace only the template's unpublished draft. `None` discards it."""
-    return _to_contract(templates_service.save_draft(team_id, template_id, draft))
+def save_template_draft(
+    team_id: int,
+    template_id: UUID,
+    draft: dict[str, Any] | None,
+    *,
+    require_workflow_editor: Callable[[UUID], None],
+) -> MessageTemplateRow:
+    return _to_contract(
+        template_saves.save_locked_draft(team_id, template_id, draft, require_workflow_editor=require_workflow_editor)
+    )
 
 
-def edit_template_content(
-    team_id: int, template_id: UUID, edit: Callable[[dict[str, Any]], dict[str, Any]]
+def save_template_fields(
+    team_id: int,
+    template_id: UUID,
+    fields: dict[str, Any],
+    *,
+    user_id: int | None,
+    require_workflow_editor: Callable[[UUID], None],
 ) -> MessageTemplateRow:
-    """Lock the template, replace its content with `edit(content)` and save, in one transaction.
+    fields = dict(fields)
+    tags = fields.pop("tags", None)
+
+    def write(template: MessageTemplate) -> None:
+        templates_service.apply_fields(template, fields)
+        templates_service.save_tags(template, tags)
+
+    return _to_contract(
+        template_saves.save_template(
+            team_id,
+            template_id,
+            write,
+            user_id=user_id,
+            require_workflow_editor=require_workflow_editor,
+        )
+    )
 
-    `edit` gets a copy of the stored content. An exception from it rolls the change back.
-    """
-    return _to_contract(templates_service.edit_content_locked(team_id, template_id, edit))
+
+def save_template_content(
+    team_id: int,
+    template_id: UUID,
+    edit: Callable[[dict[str, Any]], dict[str, Any]],
+    *,
+    user_id: int | None,
+    require_workflow_editor: Callable[[UUID], None],
+) -> MessageTemplateRow:
+    return _to_contract(
+        template_saves.save_template(
+            team_id,
+            template_id,
+            lambda template: templates_service.edit_content(template, edit),
+            user_id=user_id,
+            require_workflow_editor=require_workflow_editor,
+        )
+    )
+
+
+def upload_template(
+    team_id: int,
+    upload: TemplateUpload,
+    *,
+    user_id: int | None,
+    require_workflow_editor: Callable[[UUID], None],
+    require_workflow_create: Callable[[], None],
+) -> UploadedTemplate:
+    uploaded = template_uploads.upload_template(
+        team_id,
+        upload,
+        user_id=user_id,
+        require_workflow_editor=require_workflow_editor,
+        require_workflow_create=require_workflow_create,
+    )
+    return UploadedTemplate(result=uploaded.result, template=_to_contract(uploaded.template))
diff --git a/products/messaging/backend/facade/transactional_email.py b/products/messaging/backend/facade/transactional_email.py
index 2d3c0181cbae..4aca0e3faa71 100644
--- a/products/messaging/backend/facade/transactional_email.py
+++ b/products/messaging/backend/facade/transactional_email.py
@@ -12,8 +12,6 @@
     SENDER_ADDRESS_MAX_LENGTH,
     SENDER_ADDRESS_PATTERN,
     TransactionalEmailStage,
-    check_transactional_update,
-    lock_transactional_workflow_id,
     make_transactional,
     observe_transactional_email_stage,
     require_code_email_access,
@@ -35,9 +33,7 @@
     "QueuedEmail",
     "TransactionalEmailError",
     "TransactionalEmailStage",
-    "check_transactional_update",
     "get_email_status",
-    "lock_transactional_workflow_id",
     "make_transactional",
     "observe_transactional_email_stage",
     "require_code_email_access",
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 4a3c2687f404..a18afb2ec84d 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -8,7 +8,6 @@
 
 from django.core.exceptions import ValidationError as DjangoValidationError
 from django.core.validators import validate_email
-from django.db import transaction
 
 import structlog
 import posthoganalytics
@@ -48,17 +47,26 @@
     render_design_html,
     validate_design,
 )
+from products.messaging.backend.facade.contracts import (
+    TemplateManagedBy,
+    TemplateSource,
+    TemplateUpload,
+    TemplateUploadResult,
+)
 from products.messaging.backend.facade.templates import (
     MessageCategoryNotInTeam,
     MessageTemplateMissing,
     MessageTemplateRow,
+    UploadedTemplate,
     create_template,
-    edit_template_content,
     get_template,
     list_templates,
+    save_template_content,
     save_template_draft,
+    save_template_fields,
+    save_template_tags,
     team_category_id,
-    update_template,
+    upload_template,
 )
 from products.messaging.backend.facade.transactional_email import (
     SENDER_ADDRESS_MAX_LENGTH,
@@ -68,18 +76,20 @@
     QueuedEmail,
     TransactionalEmailError,
     TransactionalEmailStage,
-    check_transactional_update,
-    lock_transactional_workflow_id,
     make_transactional,
     observe_transactional_email_stage,
     require_code_email_access,
     send_code_email,
     send_transactional_email,
     sender_address_error,
-    sync_transactional_workflow,
     transactional_email_stage,
 )
 from products.messaging.backend.presentation.views.serializers import DesignOperationSerializer
+from products.messaging.backend.presentation.views.template_refusals import (
+    TemplateErrorSerializer,
+    invalid_request,
+    invalid_template_key,
+)
 from products.notifications.backend.facade.api import publish_resource_edited
 from products.workflows.backend.facade.api import WorkflowAccessDenied, WorkflowNotFound
 from products.workflows.backend.facade.workflows import get_workflow
@@ -326,6 +336,36 @@ class MessageTemplateSerializer(serializers.Serializer):
         help_text="Unpublished edits to a transactional template's content. Sends keep using `content`. Saving "
         "`content` publishes it and clears the draft. Set null to discard the draft.",
     )
+    key = serializers.CharField(
+        read_only=True,
+        allow_null=True,
+        help_text="Stable identifier code uses to upload and send this template, unique within the project. Null "
+        "for templates that have no key. Set once, by the first upload.",
+    )
+    managed_by = serializers.ChoiceField(
+        choices=TemplateManagedBy.choices,
+        read_only=True,
+        allow_null=True,
+        help_text="Who owns the content. `code` when it was uploaded from a repository, and the template changes "
+        "through its next upload. `gui` or null when it is edited in PostHog.",
+    )
+    source_repository = serializers.CharField(
+        read_only=True,
+        allow_null=True,
+        help_text="Repository the template was last uploaded from, such as `github.com/example/app`.",
+    )
+    source_path = serializers.CharField(
+        read_only=True, allow_null=True, help_text="Path of the template file in the source repository."
+    )
+    source_ref = serializers.CharField(
+        read_only=True, allow_null=True, help_text="Commit or branch the template was last uploaded from."
+    )
+    content_hash = serializers.CharField(
+        read_only=True,
+        allow_null=True,
+        help_text="Hash of the published subject, preheader, HTML and text, as `v1:` and 64 hex characters. Changes "
+        "with every save that changes them.",
+    )
 
     def validate_tags(self, tags: list[str]) -> list[str]:
         # The stored name is the tagified one, and lowercasing can lengthen a string: "\u0130" becomes two
@@ -453,7 +493,9 @@ class SendEmailSerializer(SendTransactionalEmailSerializer):
         required=False,
         help_text="Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs "
         "and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` "
-        "and `html` or `text`. PostHog sends the content as is and never stores it as a template.",
+        "and `html` or `text`. PostHog sends the content as is and never stores it as a template. Once you upload a "
+        "template under this key, these sends run through that template's workflow, so their metrics and logs group "
+        "with the template from then on.",
     )
     distinct_id = serializers.CharField(
         required=False,
@@ -628,6 +670,31 @@ def _require_flag(team: Any, flag: str) -> None:
         raise NotFound()
 
 
+class TemplateUploadBurstThrottle(TransactionalEmailBurstThrottle):
+    scope = "transactional_email_upload_burst"
+
+
+class TemplateUploadSustainedThrottle(TransactionalEmailSustainedThrottle):
+    scope = "transactional_email_upload_sustained"
+
+
+class TemplateUploadTeamBurstThrottle(TransactionalEmailTeamBurstThrottle):
+    scope = "transactional_email_upload_psak_team_burst"
+
+
+class TemplateUploadTeamSustainedThrottle(TransactionalEmailTeamSustainedThrottle):
+    scope = "transactional_email_upload_psak_team_sustained"
+
+
+def template_upload_throttles() -> list[BaseThrottle]:
+    return [
+        TemplateUploadBurstThrottle(),
+        TemplateUploadSustainedThrottle(),
+        TemplateUploadTeamBurstThrottle(),
+        TemplateUploadTeamSustainedThrottle(),
+    ]
+
+
 def transactional_email_throttles() -> list[BaseThrottle]:
     # Both send routes share these scopes, so a caller can't double its rate by using both.
     return [
@@ -786,11 +853,14 @@ def _require_workflow_create(self) -> None:
             raise exceptions.PermissionDenied("You need editor access to workflows to send under a new key.")
 
     def _report_transactional_email_send(self, request: Any, properties: dict[str, Any]) -> None:
+        self._capture_api_usage(request, "transactional email api send", properties)
+
+    def _capture_api_usage(self, request: Any, event: str, properties: dict[str, Any]) -> None:
         # report_user_action drops the synthetic user behind a project secret API key, so capture directly.
         try:
             posthoganalytics.capture(
                 distinct_id=request.user.distinct_id,
-                event="transactional email api send",
+                event=event,
                 properties={
                     "team_id": self.team_id,
                     "auth_method": "project_secret_api_key"
@@ -801,7 +871,116 @@ def _report_transactional_email_send(self, request: Any, properties: dict[str, A
                 groups=groups(self.organization, self.team),
             )
         except Exception as e:
-            logger.warning("Failed to capture transactional email usage event", error=str(e))
+            logger.warning("Failed to capture transactional email usage event", event_name=event, error=str(e))
+
+
+class TemplateSourceSerializer(serializers.Serializer):
+    repository = serializers.CharField(
+        max_length=400,
+        required=False,
+        allow_null=True,
+        help_text="Host and path of the repository the file is in, such as `github.com/example/app`.",
+    )
+    path = serializers.CharField(
+        max_length=400,
+        required=False,
+        allow_null=True,
+        help_text="Path of the template file in the repository, such as `emails/welcome.html`.",
+    )
+    ref = serializers.CharField(
+        max_length=400,
+        required=False,
+        allow_null=True,
+        help_text="Commit or branch the file was uploaded from.",
+    )
+
+
+def with_field_named_source_that_drf_reserves(
+    fields: dict[str, serializers.Field], source: TemplateSourceSerializer
+) -> dict[str, serializers.Field]:
+    return {**fields, "source": source}
+
+
+class UploadTemplateSerializer(serializers.Serializer):
+    name = serializers.CharField(max_length=400, help_text="Template name shown in the template library.")
+    subject = serializers.CharField(
+        trim_whitespace=False, help_text="Email subject line. Supports Liquid, such as `{{ variables.first_name }}`."
+    )
+    html = serializers.CharField(
+        trim_whitespace=False,
+        help_text="Email body as HTML, stored as sent. Supports Liquid, such as `{{ variables.first_name }}`.",
+    )
+    text = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        trim_whitespace=False,
+        help_text="Plain-text body for email clients that can't show HTML. Leaving it out removes the stored one.",
+    )
+    preheader = serializers.CharField(
+        required=False,
+        allow_blank=True,
+        trim_whitespace=False,
+        help_text="Inbox preview text shown after the subject. Leaving it out removes the stored one.",
+    )
+    if_not_superseded = serializers.BooleanField(
+        required=False,
+        default=False,
+        help_text="Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the "
+        "file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. "
+        "The check covers the last 100 different contents the template replaced. Content outside those 100 "
+        "publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.",
+    )
+
+    def get_fields(self) -> dict[str, serializers.Field]:
+        return with_field_named_source_that_drf_reserves(
+            super().get_fields(),
+            TemplateSourceSerializer(
+                required=False,
+                help_text="Where the template file lives, so people in PostHog can find it. Leaving it out, or a "
+                "part of it, keeps what is stored.",
+            ),
+        )
+
+
+class UploadTemplateResponseSerializer(serializers.Serializer):
+    id = serializers.UUIDField(help_text="ID of the template.")
+    key = serializers.CharField(help_text="Key of the template.")
+    result = serializers.ChoiceField(
+        choices=TemplateUploadResult.choices,
+        help_text="`created`: the upload made a new template. `updated`: it published the uploaded content. "
+        "`unchanged`: the template already had this content, so nothing was published. `superseded`: the upload "
+        "set `if_not_superseded` and newer content already replaced this content, so nothing was published.",
+    )
+    content_hash = serializers.CharField(
+        help_text="Hash of the published content, as `v1:` and 64 hex characters. After `superseded` it is the hash "
+        "of the newer content."
+    )
+    managed_by = serializers.ChoiceField(
+        choices=TemplateManagedBy.choices,
+        allow_null=True,
+        help_text="`code` after every upload except `superseded`, which changes nothing. After `superseded` it is "
+        "what the template had, which is null for a template made in PostHog that no upload claimed yet.",
+    )
+    transactional_hog_flow_id = serializers.UUIDField(
+        allow_null=True,
+        help_text="The workflow that sends this template. Each upload that changes the content writes a new version "
+        "of it. Null only after `superseded`, on a template that is not transactional yet.",
+    )
+
+    def get_fields(self) -> dict[str, serializers.Field]:
+        return with_field_named_source_that_drf_reserves(
+            super().get_fields(),
+            TemplateSourceSerializer(help_text="Where the template file lives, as stored after the upload."),
+        )
+
+
+TEMPLATE_KEY_PARAMETER = OpenApiParameter(
+    name="key",
+    type=OpenApiTypes.STR,
+    location=OpenApiParameter.PATH,
+    description="Key of the template, chosen by you. Letters, digits, hyphens (-) and underscores (_), at most 400 "
+    "characters. The same key names the template in every project.",
+)
 
 
 @extend_schema_view(
@@ -829,10 +1008,10 @@ class MessageTemplatesViewSet(
         "design",
         "send",
         "make_transactional",
+        "upload",
     ]
     authentication_classes = [ProjectSecretAPIKeyAuthentication]
-    # A project secret API key can only send. Template CRUD stays session/personal API key/OAuth only.
-    psak_allowed_actions = ["send"]
+    psak_allowed_actions = ["send", "upload"]
     transactional_email_send_actions = ("send",)
 
     serializer_class = MessageTemplateSerializer
@@ -840,6 +1019,8 @@ class MessageTemplatesViewSet(
     def get_throttles(self):
         if self.action == "send":
             return transactional_email_throttles()
+        if self.action == "upload":
+            return template_upload_throttles()
         return super().get_throttles()
 
     def dangerously_get_object(self) -> MessageTemplateRow:
@@ -881,25 +1062,10 @@ def create(self, request: Request, *args: Any, **kwargs: Any) -> Response:
         serializer = self.get_serializer(data=request.data)
         serializer.is_valid(raise_exception=True)
         template = create_template(self.team_id, request.user.id, serializer.validated_data)
-        # report_user_action injects source and MCP-client properties from the request, so a create from the
-        # visual editor and one from the agent count in the same metric. Capture must never break the request.
-        try:
-            report_user_action(
-                self.request.user,
-                "message_template_created",
-                {
-                    "template_id": str(template.id),
-                    "team_id": str(self.team_id),
-                    "organization_id": str(self.organization_id),
-                },
-                team=self.team,
-                # Without this the event groups by the person's current organization, which can differ
-                # from the route's when they belong to more than one.
-                organization=self.organization,
-                request=self.request,
-            )
-        except Exception as e:
-            logger.warning("Failed to capture message template usage event", error=str(e))
+        self._report_user_action(
+            "message_template_created",
+            {"template_id": str(template.id), "organization_id": str(self.organization_id)},
+        )
         data = self._serialize(template)
         return Response(data, status=status.HTTP_201_CREATED, headers=self.get_success_headers(data))
 
@@ -910,45 +1076,47 @@ def update(self, request: Request, *args: Any, **kwargs: Any) -> Response:
         serializer.is_valid(raise_exception=True)
         fields = serializer.validated_data
         if fields.keys() == {"draft_content"}:
-            # Sends never read the draft, so it skips the sendability check and the workflow sync. It is still an edit
-            # of the transactional email, so it needs the same workflow access as a publish.
-            if template.transactional_hog_flow_id:
-                self._require_workflow_editor(template.transactional_hog_flow_id)
-            updated = save_template_draft(self.team_id, template.id, fields["draft_content"])
+            updated = save_template_draft(
+                self.team_id,
+                template.id,
+                fields["draft_content"],
+                require_workflow_editor=self._require_workflow_editor,
+            )
             self._emit_resource_edited(updated)
             return Response(self._serialize(updated))
         if fields.keys() == {"tags"}:
             # Tags are library metadata. Sends never read them, so a tag edit skips the sendability check
             # and must not write a new version of the template's transactional workflow.
-            updated = update_template(self.team_id, template.id, fields)
+            updated = save_template_tags(self.team_id, template.id, fields["tags"])
             self._emit_resource_edited(updated)
             return Response(self._serialize(updated))
         if "content" in fields:
             fields["draft_content"] = None
-        # Sends use the workflow's copy, so the template and its new workflow version are saved together,
-        # under a row lock that keeps a concurrent make_transactional from slipping in between.
-        with transaction.atomic():
-            hog_flow_id = lock_transactional_workflow_id(self.team_id, template.id)
-            if hog_flow_id:
-                self._require_workflow_editor(hog_flow_id)
-                try:
-                    check_transactional_update(template.id, self.team_id, fields)
-                except TransactionalEmailError as e:
-                    raise TransactionalEmailRejected(e) from None
-            updated = update_template(self.team_id, template.id, fields)
-            if hog_flow_id and not updated.deleted:
-                self._sync_transactional_workflow(template.id)
-                # The sync unlinks the template when its workflow was deleted.
-                updated = get_template(self.team_id, template.id)
+        try:
+            updated = save_template_fields(
+                self.team_id,
+                template.id,
+                fields,
+                user_id=self._actor_id(),
+                require_workflow_editor=self._require_workflow_editor,
+            )
+        except TransactionalEmailError as e:
+            raise TransactionalEmailRejected(e) from None
         self._emit_resource_edited(updated)
         return Response(self._serialize(updated))
 
-    def _sync_transactional_workflow(self, template_id: Any) -> None:
-        # Raising rolls back the template save, so the template and its workflow never disagree.
+    def _report_user_action(self, event: str, properties: dict[str, Any]) -> None:
         try:
-            sync_transactional_workflow(self.team_id, template_id, user_id=self._actor_id())
-        except TransactionalEmailError as e:
-            raise TransactionalEmailRejected(e) from None
+            report_user_action(
+                self.request.user,
+                event,
+                {"team_id": str(self.team_id), **properties},
+                team=self.team,
+                organization=self.organization,
+                request=self.request,
+            )
+        except Exception as e:
+            logger.warning("Failed to capture message template usage event", error=str(e))
 
     def _actor_id(self) -> int | None:
         return self.request.user.id if self.request.user.is_authenticated else None
@@ -979,13 +1147,14 @@ def design(self, request: Request, *args: Any, **kwargs: Any) -> Response:
         # of re-transmitting the whole design JSON. Reads, applies, validates, re-renders, and saves
         # atomically so a rejected batch leaves the template untouched (and concurrent visual-editor saves
         # can't interleave).
-        op_serializer = DesignPatchSerializer(data=request.data)
-        op_serializer.is_valid(raise_exception=True)
-        operations = op_serializer.validated_data["operations"]
 
         # Authorize + team-scope via the normal lookup, then re-read FOR UPDATE inside the transaction.
         template = self.get_object()
 
+        op_serializer = DesignPatchSerializer(data=request.data)
+        op_serializer.is_valid(raise_exception=True)
+        operations = op_serializer.validated_data["operations"]
+
         def apply_operations(content: dict[str, Any]) -> dict[str, Any]:
             email = content.get("email") or {}
             design = email.get("design")
@@ -1012,19 +1181,19 @@ def apply_operations(content: dict[str, Any]) -> dict[str, Any]:
             serializer.is_valid(raise_exception=True)
             return serializer.validated_data["content"]
 
-        with transaction.atomic():
-            # Checked under the row lock, so a template made transactional meanwhile is checked too.
-            hog_flow_id = lock_transactional_workflow_id(self.team_id, template.id)
-            if hog_flow_id:
-                self._require_workflow_editor(hog_flow_id)
-            locked = edit_template_content(self.team_id, template.id, apply_operations)
-            if hog_flow_id:
-                self._sync_transactional_workflow(template.id)
-                # The sync unlinks the template when its workflow was deleted.
-                locked = get_template(self.team_id, template.id)
+        try:
+            saved = save_template_content(
+                self.team_id,
+                template.id,
+                apply_operations,
+                user_id=self._actor_id(),
+                require_workflow_editor=self._require_workflow_editor,
+            )
+        except TransactionalEmailError as e:
+            raise TransactionalEmailRejected(e) from None
 
-        self._emit_resource_edited(locked)
-        return Response(self._serialize(locked))
+        self._emit_resource_edited(saved)
+        return Response(self._serialize(saved))
 
     @validated_request(
         SendTransactionalEmailSerializer,
@@ -1047,6 +1216,107 @@ def send(self, request: Any, *args: Any, **kwargs: Any) -> Response:
             template = self.get_object()
         return self._queue_transactional_email(request, template, route="template")
 
+    @extend_schema(
+        request=UploadTemplateSerializer,
+        responses={
+            200: OpenApiResponse(
+                response=UploadTemplateResponseSerializer,
+                description="The template was updated, is unchanged, or newer content superseded the upload",
+            ),
+            201: OpenApiResponse(response=UploadTemplateResponseSerializer, description="The template was created"),
+            400: OpenApiResponse(
+                response=TemplateErrorSerializer,
+                description="The key or a field is invalid, the template can't be sent, or there is no verified "
+                "default sender",
+            ),
+            404: OpenApiResponse(description="Sending email from code is not enabled for this project"),
+            429: OpenApiResponse(description="Rate limited"),
+        },
+        summary="Upload a template by key",
+        description=(
+            "Create or update the email template with this key from HTML, for templates kept as files in a "
+            "repository. The first upload creates the template and makes it transactional with the project's "
+            "default verified sender. A later upload publishes changed content at once, and answers `unchanged` "
+            "when the content is the same. With `if_not_superseded`, an upload of content that is one of the last "
+            "100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps "
+            "the template's sender and never turns a paused template back on."
+        ),
+        parameters=[TEMPLATE_KEY_PARAMETER],
+    )
+    @action(detail=False, methods=["PUT"], url_path=r"by_key/(?P<key>[^/]+)", pagination_class=None)
+    def upload(self, request: Request, key: str, *args: Any, **kwargs: Any) -> Response:
+        require_email_from_code(self.team)
+        refused = invalid_template_key(key)
+        body = UploadTemplateSerializer(data=request.data)
+        if refused is None and not body.is_valid():
+            refused = invalid_request(
+                body.errors, why="An upload needs a name, a subject and HTML, each as a string.", retry="upload again"
+            )
+        if refused is not None:
+            self._report_template_upload(request, {"result": "rejected", "error_code": refused.code})
+            return Response(TemplateErrorSerializer(refused).data, status=status.HTTP_400_BAD_REQUEST)
+
+        try:
+            uploaded = upload_template(
+                self.team_id,
+                self._template_upload(key, body.validated_data),
+                user_id=self._actor_id(),
+                require_workflow_editor=self._require_workflow_editor,
+                require_workflow_create=self._require_workflow_create,
+            )
+        except TransactionalEmailError as e:
+            self._report_template_upload(request, {"result": "rejected", "error_code": e.code})
+            raise TransactionalEmailRejected(e) from None
+        except exceptions.PermissionDenied:
+            self._report_template_upload(request, {"result": "rejected", "error_code": "permission_denied"})
+            raise
+
+        self._report_template_upload(request, {"result": uploaded.result, "template_id": str(uploaded.template.id)})
+        if uploaded.result != TemplateUploadResult.SUPERSEDED:
+            self._emit_resource_edited(uploaded.template)
+        created = uploaded.result == TemplateUploadResult.CREATED
+        return Response(
+            UploadTemplateResponseSerializer(self._upload_response(uploaded)).data,
+            status=status.HTTP_201_CREATED if created else status.HTTP_200_OK,
+        )
+
+    @staticmethod
+    def _template_upload(key: str, data: dict[str, Any]) -> TemplateUpload:
+        source = data.get("source")
+        return TemplateUpload(
+            key=key,
+            name=data["name"],
+            subject=data["subject"],
+            html=data["html"],
+            text=data.get("text", ""),
+            preheader=data.get("preheader", ""),
+            design=build_html_wrap_design(data["html"]),
+            source=TemplateSource(repository=source.get("repository"), path=source.get("path"), ref=source.get("ref"))
+            if source
+            else None,
+            if_not_superseded=data["if_not_superseded"],
+        )
+
+    @staticmethod
+    def _upload_response(uploaded: UploadedTemplate) -> dict[str, Any]:
+        template = uploaded.template
+        return {
+            "id": template.id,
+            "key": template.key,
+            "result": uploaded.result,
+            "content_hash": template.content_hash,
+            "managed_by": template.managed_by,
+            "source": {
+                "repository": template.source_repository,
+                "path": template.source_path,
+                "ref": template.source_ref,
+            },
+            "transactional_hog_flow_id": template.transactional_hog_flow_id,
+        }
+
+    def _report_template_upload(self, request: Any, outcome: dict[str, Any]) -> None:
+        self._capture_api_usage(request, "transactional email template uploaded", outcome)
+
     @validated_request(
         MakeTransactionalSerializer,
         responses={
@@ -1084,17 +1354,7 @@ def make_transactional(self, request: Any, *args: Any, **kwargs: Any) -> Respons
         updated = self.get_object()
         if not was_transactional:
             self._emit_resource_edited(updated)
-            try:
-                report_user_action(
-                    self.request.user,
-                    "message template made transactional",
-                    {"template_id": str(template.id), "team_id": str(self.team_id)},
-                    team=self.team,
-                    organization=self.organization,
-                    request=self.request,
-                )
-            except Exception as e:
-                logger.warning("Failed to capture message template usage event", error=str(e))
+            self._report_user_action("message template made transactional", {"template_id": str(template.id)})
         return Response(self._serialize(updated))
 
 
diff --git a/products/messaging/backend/presentation/views/template_refusals.py b/products/messaging/backend/presentation/views/template_refusals.py
new file mode 100644
index 000000000000..037a4d24905b
--- /dev/null
+++ b/products/messaging/backend/presentation/views/template_refusals.py
@@ -0,0 +1,83 @@
+import re
+from typing import Any
+
+from rest_framework import serializers
+from rest_framework.settings import api_settings
+
+from posthog.dataclasses import frozen
+
+from products.messaging.backend.facade.contracts import TEMPLATE_KEY_MAX_LENGTH, TEMPLATE_KEY_PATTERN
+
+
+class TemplateErrorSerializer(serializers.Serializer):
+    type = serializers.CharField(help_text="Error class, such as `invalid_request`.")
+    code = serializers.CharField(help_text="Stable error code to branch on, such as `invalid_template_key`.")
+    detail = serializers.CharField(help_text="What went wrong.")
+    attr = serializers.CharField(allow_null=True, help_text="The request field the error is about, if any.")
+    why = serializers.CharField(required=False, help_text="Why PostHog refuses the request.")
+    fix = serializers.CharField(required=False, help_text="What to change before you retry.")
+    docs_url = serializers.URLField(required=False, help_text="Documentation for this error code.")
+
+
+TRANSACTIONAL_EMAIL_DOCS_URL = "https://posthog.com/docs/workflows/transactional-email-api"
+
+
+@frozen
+class TemplateRefusal:
+    code: str
+    detail: str
+    attr: str | None
+    why: str
+    fix: str
+    type: str = "invalid_request"
+
+    @property
+    def docs_url(self) -> str:
+        return f"{TRANSACTIONAL_EMAIL_DOCS_URL}#{self.code}"
+
+
+@frozen
+class FieldError:
+    attr: str | None
+    message: str
+
+
+def invalid_template_key(key: object, attr: str = "key") -> TemplateRefusal | None:
+    if isinstance(key, str) and len(key) <= TEMPLATE_KEY_MAX_LENGTH and re.fullmatch(TEMPLATE_KEY_PATTERN, key):
+        return None
+    return TemplateRefusal(
+        code="invalid_template_key",
+        detail=f"The key can have at most {TEMPLATE_KEY_MAX_LENGTH} letters, digits, hyphens (-) and underscores (_).",
+        attr=attr,
+        why="Code names the template by its key in every project, so the key must stay the same.",
+        fix="Use a key like `password-reset`.",
+    )
+
+
+def invalid_request(errors: Any, *, why: str, retry: str) -> TemplateRefusal:
+    error = first_field_error(errors)
+    if error.attr is None:
+        return TemplateRefusal(
+            code="invalid_request",
+            detail=error.message,
+            attr=None,
+            why=why,
+            fix=f"Send the body as a JSON object and {retry}.",
+        )
+    return TemplateRefusal(
+        code="invalid_request",
+        detail=f"{error.attr}: {error.message}",
+        attr=error.attr,
+        why=why,
+        fix=f"Fix `{error.attr}` and {retry}.",
+    )
+
+
+def first_field_error(errors: Any, path: tuple[str, ...] = ()) -> FieldError:
+    if isinstance(errors, dict):
+        field, nested = next(iter(errors.items()))
+        field_path = path if field == api_settings.NON_FIELD_ERRORS_KEY else (*path, str(field))
+        return first_field_error(nested, field_path)
+    if isinstance(errors, list) and errors and not isinstance(errors[0], str):
+        return first_field_error(errors[0], path)
+    return FieldError(attr="__".join(path) or None, message=str(errors[0] if isinstance(errors, list) else errors))
diff --git a/products/messaging/backend/services/content_hash.py b/products/messaging/backend/services/content_hash.py
index 6958ad9c0bb1..4c4617bcc917 100644
--- a/products/messaging/backend/services/content_hash.py
+++ b/products/messaging/backend/services/content_hash.py
@@ -1,8 +1,11 @@
 import hashlib
 from typing import Any
 
+from products.messaging.backend.facade.contracts import ContentHashState
+
 HASH_PREFIX = "v1:"
 HASHED_FIELDS = ("subject", "preheader", "html", "text")
+SUPERSEDED_HASHES_KEPT = 100
 
 _ENCODING_HEADER = b"posthog-email-template-v1\n"
 
@@ -17,3 +20,19 @@ def email_content_hash(email: dict[str, Any]) -> str:
 
 def _normalized_line_endings(value: str) -> str:
     return value.replace("\r\n", "\n").replace("\r", "\n")
+
+
+def superseded_after_publish(previous_hash: str | None, published_hash: str, superseded: list[str]) -> list[str]:
+    replaced = [previous_hash] if previous_hash and previous_hash != published_hash else []
+    kept = [h for h in superseded if h not in (previous_hash, published_hash)]
+    return (replaced + kept)[:SUPERSEDED_HASHES_KEPT]
+
+
+def sent_hash_state(sent_hash: str | None, content_hash: str | None, superseded: list[str]) -> ContentHashState:
+    if sent_hash is None:
+        return ContentHashState.NONE
+    if sent_hash == content_hash:
+        return ContentHashState.CURRENT
+    if sent_hash in superseded:
+        return ContentHashState.SUPERSEDED
+    return ContentHashState.OUTDATED
diff --git a/products/messaging/backend/services/message_templates.py b/products/messaging/backend/services/message_templates.py
index 0480da5d329e..61ec620c9dfb 100644
--- a/products/messaging/backend/services/message_templates.py
+++ b/products/messaging/backend/services/message_templates.py
@@ -6,7 +6,6 @@
 from django.db import models, transaction
 from django.db.models.fields.json import KT
 from django.db.models.functions import Cast
-from django.utils import timezone
 
 from posthog.api.tagged_item import current_tag_names, replace_tags_on_object, set_tags_on_object
 from posthog.models import TaggedItem
@@ -14,6 +13,7 @@
 
 from products.messaging.backend.facade.contracts import EmailTemplateSummary
 from products.messaging.backend.models import MessageCategory, MessageTemplate
+from products.messaging.backend.services.content_hash import email_content_hash, superseded_after_publish
 
 
 def get_email_content(team_id: int, template_id: UUID) -> dict | None:
@@ -90,12 +90,16 @@ def team_template(team_id: int, template_id: UUID | str) -> MessageTemplate:
     return MessageTemplate.objects.get(team_id=team_id, deleted=False, pk=template_id)
 
 
+def team_template_with_key(team_id: int, key: str) -> MessageTemplate:
+    return MessageTemplate.objects.get(team_id=team_id, deleted=False, key=key)
+
+
 def category_id_for_team(team_id: int, category_id: Any) -> UUID:
     # Not filtered on deleted, as the related field this serves never was.
     return MessageCategory.objects.get(team_id=team_id, pk=category_id).pk
 
 
-def _apply_fields(template: MessageTemplate, fields: dict[str, Any]) -> None:
+def apply_fields(template: MessageTemplate, fields: dict[str, Any]) -> None:
     for attr, value in fields.items():
         setattr(template, "message_category_id" if attr == "message_category" else attr, value)
 
@@ -105,44 +109,39 @@ def create_template(team_id: int, created_by_id: int | None, fields: dict[str, A
     tags = fields.pop("tags", None)
     with transaction.atomic():
         template = MessageTemplate(team_id=team_id, created_by_id=created_by_id)
-        _apply_fields(template, fields)
+        apply_fields(template, fields)
+        record_content_hash(template)
         template.save(force_insert=True)
         if tags:
             set_tags_on_object(tags, template)
     return template
 
 
-def update_template(team_id: int, template_id: UUID | str, fields: dict[str, Any]) -> MessageTemplate:
-    fields = dict(fields)
-    tags = fields.pop("tags", None)
+def save_template_tags(team_id: int, template_id: UUID | str, tags: list[str]) -> MessageTemplate:
     with transaction.atomic():
         template = team_template(team_id, template_id)
-        # The editor sends the tags with every save, so only write them when they change.
-        tags_changed = tags is not None and {tagify(tag) for tag in tags} != current_tag_names(template)
         # Tags live on their own rows. Saving the template too would write back every column this
         # read saw, so a tag edit would overwrite content a concurrent publish had just committed.
-        if fields:
-            _apply_fields(template, fields)
-            template.save()
-        if tags_changed:
-            replace_tags_on_object(tags, template)
+        save_tags(template, tags)
     return template
 
 
-def save_draft(team_id: int, template_id: UUID | str, draft: dict[str, Any] | None) -> MessageTemplate:
-    # Writes only the draft, so a draft save that races a publish, a delete or a conversion can't undo it.
-    MessageTemplate.objects.filter(team_id=team_id, deleted=False, pk=template_id).update(
-        draft_content=draft, updated_at=timezone.now()
-    )
-    return team_template(team_id, template_id)
+def save_tags(template: MessageTemplate, tags: list[str] | None) -> None:
+    if tags is None:
+        return
+    tags_changed = {tagify(tag) for tag in tags} != current_tag_names(template)
+    if tags_changed:
+        replace_tags_on_object(tags, template)
 
 
-def edit_content_locked(
-    team_id: int, template_id: UUID | str, edit: Callable[[dict[str, Any]], dict[str, Any]]
-) -> MessageTemplate:
-    with transaction.atomic():
-        # nosemgrep: idor-lookup-without-team (re-fetch of an already team-scoped template, locked for update)
-        locked = MessageTemplate.objects.select_for_update().get(pk=team_template(team_id, template_id).pk)
-        locked.content = edit(deepcopy(locked.content or {}))
-        locked.save()
-    return locked
+def edit_content(template: MessageTemplate, edit: Callable[[dict[str, Any]], dict[str, Any]]) -> None:
+    template.content = edit(deepcopy(template.content or {}))
+
+
+def record_content_hash(template: MessageTemplate) -> None:
+    email = (template.content or {}).get("email")
+    published_hash = email_content_hash(email if isinstance(email, dict) else {})
+    template.superseded_content_hashes = superseded_after_publish(
+        template.content_hash, published_hash, template.superseded_content_hashes or []
+    )
+    template.content_hash = published_hash
diff --git a/products/messaging/backend/services/template_saves.py b/products/messaging/backend/services/template_saves.py
new file mode 100644
index 000000000000..a9d7516fa8cf
--- /dev/null
+++ b/products/messaging/backend/services/template_saves.py
@@ -0,0 +1,71 @@
+from collections.abc import Callable
+from typing import Any
+from uuid import UUID
+
+from django.db import transaction
+
+from products.messaging.backend.models import MessageTemplate
+from products.messaging.backend.services.message_templates import record_content_hash
+from products.messaging.backend.services.transactional_email import check_still_sendable, sync_transactional_workflow
+
+TemplateWrite = Callable[[MessageTemplate], None]
+WorkflowEditorCheck = Callable[[UUID], None]
+
+
+def save_template(
+    team_id: int,
+    template_id: UUID,
+    write: TemplateWrite,
+    *,
+    user_id: int | None,
+    require_workflow_editor: WorkflowEditorCheck,
+) -> MessageTemplate:
+    with transaction.atomic():
+        template = lock_template(team_id, template_id)
+        save_locked_template(template, write, user_id=user_id, require_workflow_editor=require_workflow_editor)
+    return template
+
+
+def save_locked_draft(
+    team_id: int,
+    template_id: UUID,
+    draft: dict[str, Any] | None,
+    *,
+    require_workflow_editor: WorkflowEditorCheck,
+) -> MessageTemplate:
+    with transaction.atomic():
+        template = lock_template(team_id, template_id)
+        if template.transactional_hog_flow_id:
+            require_workflow_editor(template.transactional_hog_flow_id)
+        template.draft_content = draft
+        template.save(update_fields=["draft_content", "updated_at"])
+    return template
+
+
+def lock_template(team_id: int, template_id: UUID) -> MessageTemplate:
+    return MessageTemplate.objects.select_for_update().get(team_id=team_id, id=template_id, deleted=False)
+
+
+def save_locked_template(
+    template: MessageTemplate,
+    write: TemplateWrite,
+    *,
+    user_id: int | None,
+    require_workflow_editor: WorkflowEditorCheck,
+) -> None:
+    hog_flow_id = template.transactional_hog_flow_id
+    if hog_flow_id:
+        require_workflow_editor(hog_flow_id)
+    write(template)
+    syncs_workflow = hog_flow_id is not None and not template.deleted
+    if syncs_workflow:
+        check_still_sendable(template)
+    record_content_hash(template)
+    template.save()
+    if syncs_workflow:
+        _sync_workflow_and_reread_its_link(template, user_id=user_id)
+
+
+def _sync_workflow_and_reread_its_link(template: MessageTemplate, *, user_id: int | None) -> None:
+    sync_transactional_workflow(template.team_id, template.id, user_id=user_id)
+    template.refresh_from_db()
diff --git a/products/messaging/backend/services/template_uploads.py b/products/messaging/backend/services/template_uploads.py
new file mode 100644
index 000000000000..936e430f9fcd
--- /dev/null
+++ b/products/messaging/backend/services/template_uploads.py
@@ -0,0 +1,187 @@
+from collections.abc import Callable
+from typing import Any
+
+from django.db import IntegrityError, transaction
+
+from posthog.dataclasses import frozen
+
+from products.messaging.backend.facade.contracts import (
+    ContentHashState,
+    SenderUnavailable,
+    TemplateManagedBy,
+    TemplateSource,
+    TemplateUpload,
+    TemplateUploadResult,
+)
+from products.messaging.backend.models import MessageTemplate
+from products.messaging.backend.models.message_template import KEY_CONSTRAINT
+from products.messaging.backend.services.content_hash import email_content_hash, sent_hash_state
+from products.messaging.backend.services.message_templates import record_content_hash
+from products.messaging.backend.services.template_saves import WorkflowEditorCheck, save_locked_template
+from products.messaging.backend.services.transactional_email import is_transactional, make_transactional
+
+SOURCE_PARTS = ("repository", "path", "ref")
+
+WorkflowCreateCheck = Callable[[], None]
+
+
+@frozen
+class Uploaded:
+    result: TemplateUploadResult
+    template: MessageTemplate
+
+
+def upload_template(
+    team_id: int,
+    upload: TemplateUpload,
+    *,
+    user_id: int | None,
+    require_workflow_editor: WorkflowEditorCheck,
+    require_workflow_create: WorkflowCreateCheck,
+) -> Uploaded:
+    def attempt() -> Uploaded:
+        with transaction.atomic():
+            return _upload(
+                team_id,
+                upload,
+                user_id=user_id,
+                require_workflow_editor=require_workflow_editor,
+                require_workflow_create=require_workflow_create,
+            )
+
+    try:
+        return attempt()
+    except IntegrityError as error:
+        if not _another_upload_created_the_key_first(error):
+            raise
+    return attempt()
+
+
+def _another_upload_created_the_key_first(error: IntegrityError) -> bool:
+    return KEY_CONSTRAINT in str(error)
+
+
+def _upload(
+    team_id: int,
+    upload: TemplateUpload,
+    *,
+    user_id: int | None,
+    require_workflow_editor: WorkflowEditorCheck,
+    require_workflow_create: WorkflowCreateCheck,
+) -> Uploaded:
+    template = locked_template_with_key(team_id, upload.key)
+    if template is None:
+        require_workflow_create()
+        return Uploaded(result=TemplateUploadResult.CREATED, template=_create(team_id, upload, user_id=user_id))
+    if template.transactional_hog_flow_id:
+        require_workflow_editor(template.transactional_hog_flow_id)
+    if upload.if_not_superseded and _is_superseded(template, upload):
+        return Uploaded(result=TemplateUploadResult.SUPERSEDED, template=template)
+    if _is_unchanged(template, upload):
+        _save_source(template, upload.source)
+        return Uploaded(result=TemplateUploadResult.UNCHANGED, template=template)
+    save_locked_template(
+        template,
+        lambda locked: _write_upload(locked, upload),
+        user_id=user_id,
+        require_workflow_editor=require_workflow_editor,
+    )
+    adopted_or_lost_its_workflow = not template.transactional_hog_flow_id
+    if adopted_or_lost_its_workflow:
+        require_workflow_create()
+        _make_transactional(template, user_id=user_id)
+    return Uploaded(result=TemplateUploadResult.UPDATED, template=template)
+
+
+def locked_template_with_key(team_id: int, key: str) -> MessageTemplate | None:
+    return MessageTemplate.objects.select_for_update().filter(team_id=team_id, key=key, deleted=False).first()
+
+
+def _create(team_id: int, upload: TemplateUpload, *, user_id: int | None) -> MessageTemplate:
+    template = MessageTemplate(team_id=team_id, created_by_id=user_id, key=upload.key)
+    _write_upload(template, upload)
+    record_content_hash(template)
+    template.save(force_insert=True)
+    _make_transactional(template, user_id=user_id)
+    return template
+
+
+def _make_transactional(template: MessageTemplate, *, user_id: int | None) -> None:
+    try:
+        make_transactional(template.team_id, template.id, user_id=user_id, from_integration_id=None)
+    except SenderUnavailable as error:
+        raise SenderUnavailable(_sender_unavailable_message(template)) from error
+    template.refresh_from_db()
+
+
+def _sender_unavailable_message(template: MessageTemplate) -> str:
+    sender = ((template.content or {}).get("email") or {}).get("from")
+    if isinstance(sender, dict) and sender.get("integrationId"):
+        return (
+            "The template's email sender isn't verified. Verify its sending domain, or pick a verified sender for "
+            "the template in PostHog, and upload again."
+        )
+    return (
+        "The project has no verified default email sender. Verify a sending domain, set it as the default "
+        "sender, and upload again."
+    )
+
+
+def _write_upload(template: MessageTemplate, upload: TemplateUpload) -> None:
+    template.name = upload.name
+    template.type = "email"
+    template.managed_by = TemplateManagedBy.CODE
+    content = template.content or {}
+    stored_email = content.get("email") or {}
+    template.content = {**content, "templating": "liquid", "email": {**stored_email, **_email(upload)}}
+    _discard_draft_the_upload_makes_stale(template)
+    _write_source(template, upload.source)
+
+
+def _discard_draft_the_upload_makes_stale(template: MessageTemplate) -> None:
+    template.draft_content = None
+
+
+def _email(upload: TemplateUpload) -> dict[str, Any]:
+    return {
+        "subject": upload.subject,
+        "preheader": upload.preheader,
+        "html": upload.html,
+        "text": upload.text,
+        "design": upload.design,
+    }
+
+
+def _is_unchanged(template: MessageTemplate, upload: TemplateUpload) -> bool:
+    stored_email = (template.content or {}).get("email") or {}
+    uploaded_hash = email_content_hash(_email(upload))
+    return (
+        template.name == upload.name
+        and email_content_hash(stored_email) == uploaded_hash
+        and template.content_hash == uploaded_hash
+        and template.managed_by == TemplateManagedBy.CODE
+        and is_transactional(template)
+    )
+
+
+def _is_superseded(template: MessageTemplate, upload: TemplateUpload) -> bool:
+    uploaded_hash = email_content_hash(_email(upload))
+    state = sent_hash_state(uploaded_hash, template.content_hash, template.superseded_content_hashes or [])
+    return state == ContentHashState.SUPERSEDED
+
+
+def _write_source(template: MessageTemplate, source: TemplateSource | None) -> list[str]:
+    changed: list[str] = []
+    for part in SOURCE_PARTS:
+        value = getattr(source, part) if source else None
+        field = f"source_{part}"
+        if value is not None and getattr(template, field) != value:
+            setattr(template, field, value)
+            changed.append(field)
+    return changed
+
+
+def _save_source(template: MessageTemplate, source: TemplateSource | None) -> None:
+    changed = _write_source(template, source)
+    if changed:
+        template.save(update_fields=[*changed, "updated_at"])
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index 4599b018a768..29d22169a525 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -288,31 +288,20 @@ def _workflow_exists(team_id: int, hog_flow_id: UUID) -> bool:
     return True
 
 
-def lock_transactional_workflow_id(team_id: int, template_id: UUID) -> UUID | None:
-    """Lock the template row for the rest of the transaction and return its workflow id. Holding the lock
-    keeps make_transactional from linking a workflow between this read and the update that follows."""
-    return (
-        MessageTemplate.objects.select_for_update()
-        .filter(team_id=team_id, id=template_id)
-        .values_list("transactional_hog_flow_id", flat=True)
-        .get()
+def is_transactional(template: MessageTemplate) -> bool:
+    return template.transactional_hog_flow_id is not None and _workflow_exists(
+        template.team_id, template.transactional_hog_flow_id
     )
 
 
-def check_transactional_update(template_id: UUID, team_id: int, fields: dict[str, Any]) -> None:
-    """Raise when an update would leave a transactional template unable to send. `fields` are validated
-    serializer fields, where `message_category` holds a category id."""
-    template = MessageTemplate.objects.get(team_id=team_id, id=template_id)
-    if not template.transactional_hog_flow_id or fields.get("deleted"):
-        return
-    # A link to a deleted workflow no longer restricts the template. The sync after the update clears it.
-    if not _workflow_exists(team_id, template.transactional_hog_flow_id):
+def check_still_sendable(template: MessageTemplate) -> None:
+    if template.deleted or not is_transactional(template):
         return
     check_sendable(
-        team_id,
-        template_type=fields.get("type", template.type),
-        content=fields.get("content", template.content),
-        message_category_id=fields.get("message_category", template.message_category_id),
+        template.team_id,
+        template_type=template.type,
+        content=template.content,
+        message_category_id=template.message_category_id,
     )
 
 
@@ -378,19 +367,19 @@ def _require_active(team_id: int, hog_flow_id: UUID) -> None:
         raise TransactionalEmailPaused("The template's transactional email isn't active.")
 
 
+def _template_an_upload_claimed(team_id: int, key: str) -> MessageTemplate | None:
+    return MessageTemplate.objects.filter(team_id=team_id, key=key, deleted=False, managed_by__isnull=False).first()
+
+
 def _code_email_workflow_id(team_id: int, key: str) -> UUID:
-    template_id = _template_id_for_key(team_id, key)
-    if template_id is not None:
-        return _transactional_workflow_id(team_id, template_id)
+    template = _template_an_upload_claimed(team_id, key)
+    if template is not None:
+        return _transactional_workflow_id(team_id, template.id)
     hog_flow_id = _key_workflow_id(team_id, key)
     _require_active(team_id, hog_flow_id)
     return hog_flow_id
 
 
-def _template_id_for_key(team_id: int, key: str) -> UUID | None:
-    return MessageTemplate.objects.filter(team_id=team_id, key=key, deleted=False).values_list("id", flat=True).first()
-
-
 def known_key(team_id: int, key: str) -> TransactionalEmailKey | None:
     return TransactionalEmailKey.objects.for_team(team_id).filter(key=key).first()
 
@@ -420,7 +409,7 @@ def require_code_email_access(
     require_workflow_editor: Callable[[UUID], None],
     require_workflow_create: Callable[[], None],
 ) -> None:
-    template = MessageTemplate.objects.filter(team_id=team_id, key=key, deleted=False).first()
+    template = _template_an_upload_claimed(team_id, key)
     if template is not None:
         if template.transactional_hog_flow_id is not None:
             require_workflow_editor(template.transactional_hog_flow_id)
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
new file mode 100644
index 000000000000..f46956de14ba
--- /dev/null
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -0,0 +1,376 @@
+from typing import Any
+
+from posthog.test.base import APIBaseTest
+from unittest.mock import MagicMock, patch
+
+from parameterized import parameterized
+from rest_framework import status
+from rest_framework.test import APIClient
+
+from posthog.models import ProjectSecretAPIKey, Team
+from posthog.models.integration import Integration
+from posthog.models.personal_api_key import hash_key_value
+from posthog.models.utils import generate_random_token_secret
+
+from products.messaging.backend.models.message_template import MessageTemplate
+from products.messaging.backend.presentation.views.message_templates import (
+    EMAIL_FROM_CODE_FLAG,
+    TRANSACTIONAL_EMAIL_API_FLAG,
+    TransactionalEmailBurstThrottle,
+)
+from products.messaging.backend.services import template_uploads
+from products.workflows.backend.facade.api import set_default_email_sender_if_unset
+
+WELCOME: dict[str, Any] = {
+    "name": "Welcome",
+    "subject": "Welcome, {{ variables.first_name }}",
+    "html": "<p>Hi {{ variables.first_name }}</p>",
+    "source": {"repository": "github.com/example/app", "path": "emails/welcome.html", "ref": "3f2c1ab"},
+}
+WELCOME_HASH = "v1:f74cd913f3aa2e5667a588f2865634e56693df77793ca594d18e9b5f89e3d2e6"
+GREETING = {"name": "Welcome", "subject": "Grüße", "preheader": "Vorschau", "html": "<p>ä</p>\n", "text": "ä"}
+GREETING_HASH = "v1:ff5293725c21e0f9b71918af66cf7b6e17b2021f250fe915f8426946b378c88d"
+
+
+@patch("products.messaging.backend.presentation.views.message_templates.posthoganalytics.capture")
+@patch(
+    "products.messaging.backend.presentation.views.message_templates.posthoganalytics.feature_enabled",
+    return_value=True,
+)
+@patch("posthog.plugins.plugin_server_api.internal_requests.post")
+class TestTemplateUpload(APIBaseTest):
+    def setUp(self):
+        super().setUp()
+        self.sender = self._verified_sender("hello@example.com")
+        set_default_email_sender_if_unset(self.team.id, self.sender.id)
+        self.url = f"/api/projects/{self.team.id}/messaging_templates/by_key/welcome/"
+        self.psak = self._psak_client(["hog_flow:write"])
+
+    def _verified_sender(self, address: str) -> Integration:
+        return Integration.objects.create(
+            team=self.team, kind="email", integration_id=address, config={"verified": True}
+        )
+
+    def _psak_client(self, scopes: list[str], team: Team | None = None) -> APIClient:
+        raw_token = generate_random_token_secret()
+        ProjectSecretAPIKey.objects.create(
+            team=team or self.team,
+            label=f"template upload {raw_token[:8]}",
+            secure_value=hash_key_value(raw_token),
+            scopes=scopes,
+            mask_value=f"{raw_token[:4]}...{raw_token[-4:]}",
+        )
+        client = APIClient()
+        client.credentials(HTTP_AUTHORIZATION=f"Bearer {raw_token}")
+        return client
+
+    def _upload(self, body: dict[str, Any]) -> dict[str, Any]:
+        response = self.psak.put(self.url, body, format="json")
+        assert response.status_code in (status.HTTP_200_OK, status.HTTP_201_CREATED), response.json()
+        return response.json()
+
+    def _template(self, template_id: str) -> dict[str, Any]:
+        response = self.client.get(f"/api/projects/{self.team.id}/messaging_templates/{template_id}/")
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        return response.json()
+
+    def _workflow(self, hog_flow_id: str) -> dict[str, Any]:
+        response = self.client.get(f"/api/projects/{self.team.id}/hog_flows/{hog_flow_id}")
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        return response.json()
+
+    def _sent_email(self, hog_flow_id: str) -> dict[str, Any]:
+        return self._workflow(hog_flow_id)["actions"][1]["config"]["inputs"]["email"]["value"]
+
+    def _superseded_hashes(self, template_id: str) -> list[str]:
+        return MessageTemplate.objects.get(id=template_id).superseded_content_hashes or []
+
+    def test_a_first_upload_creates_a_code_managed_transactional_template(self, _post: MagicMock, flag, _capture):
+        flag.side_effect = lambda key, *_args, **_kwargs: key == EMAIL_FROM_CODE_FLAG
+        response = self.psak.put(self.url, WELCOME, format="json")
+
+        assert response.status_code == status.HTTP_201_CREATED, response.json()
+        uploaded = response.json()
+        assert uploaded["result"] == "created"
+        assert uploaded["key"] == "welcome"
+        assert uploaded["managed_by"] == "code"
+        assert uploaded["content_hash"] == WELCOME_HASH
+        assert uploaded["source"] == WELCOME["source"]
+        template = self._template(uploaded["id"])
+        assert template["key"] == "welcome"
+        assert template["managed_by"] == "code"
+        assert template["content_hash"] == WELCOME_HASH
+        assert (template["source_repository"], template["source_path"], template["source_ref"]) == (
+            "github.com/example/app",
+            "emails/welcome.html",
+            "3f2c1ab",
+        )
+        assert template["transactional_hog_flow_id"] == uploaded["transactional_hog_flow_id"]
+        assert self._workflow(uploaded["transactional_hog_flow_id"])["status"] == "active"
+        email = self._sent_email(uploaded["transactional_hog_flow_id"])
+        assert (email["subject"], email["html"], email["from"]["integrationId"]) == (
+            WELCOME["subject"],
+            WELCOME["html"],
+            self.sender.id,
+        )
+
+    @parameterized.expand(
+        [
+            ("same_text", WELCOME, WELCOME, WELCOME_HASH),
+            ("other_line_endings", {**GREETING, "html": "<p>ä</p>\r\n"}, GREETING, GREETING_HASH),
+        ]
+    )
+    def test_an_identical_upload_is_unchanged_and_writes_no_workflow_version(
+        self, _post, _flag, _capture, _name, first_body, second_body, expected_hash
+    ):
+        first = self._upload(first_body)
+        before = self._template(first["id"])
+
+        with patch("products.messaging.backend.presentation.views.message_templates.publish_resource_edited") as edited:
+            response = self.psak.put(self.url, {**second_body, "source": {"ref": "9e8d7c6"}}, format="json")
+
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        assert response.json()["result"] == "unchanged"
+        assert response.json()["content_hash"] == expected_hash
+        kept_source = {**(first_body.get("source") or {"repository": None, "path": None}), "ref": "9e8d7c6"}
+        assert response.json()["source"] == kept_source
+        assert self._workflow(first["transactional_hog_flow_id"])["version"] == 1
+        after = self._template(first["id"])
+        assert {part: after[f"source_{part}"] for part in ("repository", "path", "ref")} == kept_source
+        assert after["updated_at"] > before["updated_at"]
+        assert (
+            edited.call_args.kwargs["updated_at"] == MessageTemplate.objects.get(id=first["id"]).updated_at.isoformat()
+        )
+
+    def test_an_upload_repairs_a_stored_hash_that_does_not_describe_the_content(self, _post, _flag, _capture):
+        first = self._upload(WELCOME)
+        MessageTemplate.objects.filter(id=first["id"]).update(content_hash=GREETING_HASH)
+
+        repaired = self._upload(WELCOME)
+
+        assert (repaired["result"], repaired["content_hash"]) == ("updated", WELCOME_HASH)
+        assert self._template(first["id"])["content_hash"] == WELCOME_HASH
+
+    @patch("products.messaging.backend.services.transactional_email.reload_hog_flows_on_workers")
+    def test_a_changed_upload_is_what_the_next_send_delivers(self, _reload, post: MagicMock, _flag, _capture):
+        first = self._upload(WELCOME)
+        post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
+
+        response = self.psak.put(self.url, GREETING, format="json")
+        sent = self.psak.post(
+            f"/api/projects/{self.team.id}/messaging_templates/{first['id']}/send/",
+            {"to": "user@example.com", "message_data": {"first_name": "Jane"}},
+            format="json",
+        )
+
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        assert response.json()["result"] == "updated"
+        assert response.json()["content_hash"] == GREETING_HASH
+        assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
+        hog_flow_id = response.json()["transactional_hog_flow_id"]
+        assert hog_flow_id == first["transactional_hog_flow_id"]
+        assert post.call_args.args[0].endswith(f"/hog_flows/{hog_flow_id}/transactional_email")
+        assert post.call_args.kwargs["json"]["variables"] == {"first_name": "Jane"}
+        email = self._sent_email(hog_flow_id)
+        assert (email["subject"], email["preheader"], email["html"], email["text"]) == (
+            "Grüße",
+            "Vorschau",
+            "<p>ä</p>\n",
+            "ä",
+        )
+        assert self._workflow(hog_flow_id)["version"] == 2
+
+    def _adopted_template_sending_from(self, sender: Integration) -> MessageTemplate:
+        return MessageTemplate.objects.create(
+            team=self.team,
+            name="Welcome",
+            key="welcome",
+            content={
+                "email": {
+                    "subject": "Hello",
+                    "html": "<p>Hello</p>",
+                    "from": {"integrationId": sender.id, "email": "team@example.com", "name": "Example team"},
+                }
+            },
+            type="email",
+        )
+
+    def test_an_upload_makes_an_adopted_template_without_a_workflow_send_from_its_own_sender(
+        self, _post, _flag, _capture
+    ):
+        own_sender = self._verified_sender("team@example.com")
+        adopted = self._adopted_template_sending_from(own_sender)
+
+        body = self._upload(WELCOME)
+
+        assert (body["result"], body["id"]) == ("updated", str(adopted.id))
+        assert self._sent_email(body["transactional_hog_flow_id"])["from"] == {
+            "integrationId": own_sender.id,
+            "email": "team@example.com",
+            "name": "Example team",
+        }
+
+    @parameterized.expand(
+        [
+            ("new_template_without_a_verified_default", False, "The project has no verified default email sender."),
+            ("adopted_template_with_an_unverified_sender", True, "The template's email sender isn't verified."),
+        ]
+    )
+    def test_without_a_verified_sender_an_upload_names_the_sender_and_writes_nothing(
+        self, _post, _flag, _capture, _name, adopted, expected_detail_start
+    ):
+        if adopted:
+            unverified = Integration.objects.create(
+                team=self.team, kind="email", integration_id="team@example.com", config={"verified": False}
+            )
+            self._adopted_template_sending_from(unverified)
+        else:
+            self.sender.config = {"verified": False}
+            self.sender.save()
+
+        response = self.psak.put(self.url, WELCOME, format="json")
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        assert response.json()["code"] == "sender_unavailable"
+        assert response.json()["detail"].startswith(expected_detail_start)
+        stored = MessageTemplate.objects.filter(team=self.team)
+        assert [(t.managed_by, t.transactional_hog_flow_id) for t in stored] == ([(None, None)] if adopted else [])
+
+    @parameterized.expand(
+        [
+            ("invalid_key", "wel!come", WELCOME, "invalid_template_key", "key", "Use a key like `password-reset`."),
+            (
+                "missing_subject",
+                "welcome",
+                {"name": "Welcome", "html": "<p>Hi</p>"},
+                "invalid_request",
+                "subject",
+                "Fix `subject` and upload again.",
+            ),
+            (
+                "long_source_path",
+                "welcome",
+                WELCOME | {"source": {"path": "a" * 401}},
+                "invalid_request",
+                "source__path",
+                "Fix `source__path` and upload again.",
+            ),
+            (
+                "list_body",
+                "welcome",
+                [WELCOME],
+                "invalid_request",
+                None,
+                "Send the body as a JSON object and upload again.",
+            ),
+        ]
+    )
+    def test_refuses_an_invalid_upload_with_the_field_to_fix(
+        self, _post, _flag, _capture, _name, key, body, expected_code, expected_attr, expected_fix
+    ):
+        response = self.psak.put(f"/api/projects/{self.team.id}/messaging_templates/by_key/{key}/", body, format="json")
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        assert response.json()["code"] == expected_code
+        assert (response.json()["attr"], response.json()["fix"]) == (expected_attr, expected_fix)
+        assert response.json()["docs_url"].endswith(f"#{expected_code}")
+        assert not MessageTemplate.objects.filter(team=self.team).exists()
+
+    @parameterized.expand(
+        [
+            ("read_scope", ["hog_flow:read"], False, {EMAIL_FROM_CODE_FLAG}, status.HTTP_403_FORBIDDEN),
+            ("another_projects_key", ["hog_flow:write"], True, {EMAIL_FROM_CODE_FLAG}, status.HTTP_403_FORBIDDEN),
+            (
+                "only_the_transactional_email_api_flag",
+                ["hog_flow:write"],
+                False,
+                {TRANSACTIONAL_EMAIL_API_FLAG},
+                status.HTTP_404_NOT_FOUND,
+            ),
+        ]
+    )
+    def test_refuses_an_upload_it_does_not_allow(
+        self, _post, flag, _capture, _name, scopes, other_project, enabled_flags, expected_status
+    ):
+        flag.side_effect = lambda key, *_args, **_kwargs: key in enabled_flags
+        team = Team.objects.create(organization=self.organization, name="Other project") if other_project else None
+
+        response = self._psak_client(scopes, team).put(self.url, WELCOME, format="json")
+
+        assert response.status_code == expected_status, response.json()
+        assert not MessageTemplate.objects.exists()
+
+    @patch("posthog.rate_limit.is_rate_limit_enabled", return_value=True)
+    def test_uploads_leave_the_send_rate_limit_to_sends(self, _rate_limit, post: MagicMock, _flag, _capture):
+        post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
+
+        with patch.object(TransactionalEmailBurstThrottle, "rate", "1/minute"):
+            uploaded = self.psak.put(self.url, WELCOME, format="json")
+            sent = self.psak.post(
+                f"/api/projects/{self.team.id}/messaging_templates/{uploaded.json()['id']}/send/",
+                {"to": "user@example.com"},
+                format="json",
+            )
+
+        assert uploaded.status_code == status.HTTP_201_CREATED, uploaded.json()
+        assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
+
+    def test_two_racing_first_uploads_end_with_one_template(self, _post, _flag, _capture):
+        winner = self._upload(WELCOME)
+        lookup = template_uploads.locked_template_with_key
+        lookups: list[str] = []
+
+        def misses_the_winner_once(team_id: int, key: str) -> MessageTemplate | None:
+            lookups.append(key)
+            return None if len(lookups) == 1 else lookup(team_id, key)
+
+        with patch.object(template_uploads, "locked_template_with_key", side_effect=misses_the_winner_once):
+            response = self.psak.put(self.url, GREETING, format="json")
+
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        assert (response.json()["result"], response.json()["id"]) == ("updated", winner["id"])
+        assert MessageTemplate.objects.filter(team=self.team, key="welcome").count() == 1
+
+    def test_a_publish_moves_the_replaced_hash_to_the_superseded_list(self, _post, _flag, _capture):
+        first = self._upload(WELCOME)
+
+        edited = self.client.patch(
+            f"/api/projects/{self.team.id}/messaging_templates/{first['id']}/",
+            {"content": {"email": {"subject": "Edited in PostHog", "html": "<p>Edited</p>"}}},
+            format="json",
+        )
+        edited_hash = edited.json()["content_hash"]
+        superseded_after_edit = self._superseded_hashes(first["id"])
+        rolled_back = self._upload(WELCOME)
+
+        assert edited.status_code == status.HTTP_200_OK, edited.json()
+        assert edited_hash not in (None, WELCOME_HASH)
+        assert superseded_after_edit == [WELCOME_HASH]
+        assert (rolled_back["result"], rolled_back["content_hash"]) == ("updated", WELCOME_HASH)
+        assert self._superseded_hashes(first["id"]) == [edited_hash]
+
+    @parameterized.expand(
+        [
+            ("superseded_content", WELCOME, "superseded", "Welcome aboard, {{ variables.first_name }}", "9e8d7c6", 2),
+            ("new_content", GREETING, "updated", GREETING["subject"], "3f2c1ab", 3),
+        ]
+    )
+    def test_an_upload_if_not_superseded_never_puts_replaced_content_back(
+        self, _post, _flag, _capture, _name, body, expected_result, expected_subject, expected_ref, expected_version
+    ):
+        self._upload(WELCOME)
+        newer = self._upload(
+            {**WELCOME, "subject": "Welcome aboard, {{ variables.first_name }}", "source": {"ref": "9e8d7c6"}}
+        )
+
+        response = self.psak.put(
+            self.url, {**body, "source": {"ref": "3f2c1ab"}, "if_not_superseded": True}, format="json"
+        )
+
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        uploaded = response.json()
+        assert (uploaded["result"], uploaded["id"]) == (expected_result, newer["id"])
+        template = self._template(newer["id"])
+        assert uploaded["content_hash"] == template["content_hash"]
+        assert (template["content"]["email"]["subject"], template["source_ref"]) == (expected_subject, expected_ref)
+        assert self._workflow(newer["transactional_hog_flow_id"])["version"] == expected_version
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 9d72794200f0..4bf913551ce1 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -19,6 +19,7 @@
 from posthog.models.utils import generate_random_token_secret
 
 from products.access_control.backend.facade.testing import create_access_control
+from products.messaging.backend.facade.contracts import TemplateManagedBy
 from products.messaging.backend.models.message_category import MessageCategory, MessageCategoryType
 from products.messaging.backend.models.message_template import MessageTemplate
 from products.messaging.backend.models.transactional_email_key import TransactionalEmailKey
@@ -32,6 +33,8 @@
 from products.workflows.backend.facade.api import set_default_email_sender_if_unset
 from products.workflows.backend.models import HogFlow, TeamWorkflowsConfig
 
+PASSWORD_RESET_HASH = "v1:973d41bbe3fdca5c52bb951cd4b5fd7159ae630b56c8f3997cbb31afd1ea76fd"
+
 
 def _stage_counts() -> dict[str, float]:
     return {
@@ -75,6 +78,9 @@ def _template(self, content: dict | None = None) -> MessageTemplate:
             type="email",
         )
 
+    def _claim_by_upload(self, template: MessageTemplate) -> None:
+        MessageTemplate.objects.filter(id=template.id).update(managed_by=TemplateManagedBy.CODE)
+
     def _workflow(self, hog_flow_id) -> dict:
         response = self.client.get(f"/api/projects/{self.team.id}/hog_flows/{hog_flow_id}")
         assert response.status_code == status.HTTP_200_OK, response.json()
@@ -381,10 +387,11 @@ def _code_send(self, **fields: Any) -> dict[str, Any]:
             **fields,
         }
 
-    @parameterized.expand([("new_key", "welcome"), ("key_that_names_a_template", "password-reset")])
+    @parameterized.expand([("new_key", "welcome"), ("key_of_an_uploaded_template", "password-reset")])
     def test_a_code_send_goes_out_as_is_under_the_keys_workflow(self, mock_post, _flag, capture, _name, key):
         MessageTemplate.objects.filter(id=self.template.id).update(key="password-reset")
         self._cdp_accepts(mock_post)
+        self._claim_by_upload(self.template)
         templates_before = MessageTemplate.objects.filter(team=self.team).count()
         psak = self._psak_client(["hog_flow:write"])
 
@@ -835,6 +842,7 @@ def setUp(self):
         self.template = MessageTemplate.objects.create(
             team=self.team,
             name="Password reset",
+            key="password-reset",
             content={"email": {"subject": "Reset your password", "html": "<p>Reset</p>"}},
             type="email",
         )
@@ -872,7 +880,9 @@ def test_a_member_denied_the_workflow_cannot_send_or_change_it(self, mock_post,
         mock_post.assert_not_called()
 
     def test_a_member_denied_the_workflow_cannot_send_code_under_its_template_key(self, mock_post, _flag):
-        MessageTemplate.objects.filter(id=self.template.id).update(key="password-reset")
+        MessageTemplate.objects.filter(id=self.template.id).update(
+            key="password-reset", managed_by=TemplateManagedBy.CODE
+        )
 
         response = self.client.post(
             f"/api/projects/{self.team.id}/messaging/send/email/",
@@ -898,6 +908,44 @@ def test_a_member_who_cannot_create_workflows_cannot_send_code_under_a_new_key(s
         assert not TransactionalEmailKey.objects.for_team(self.team.id).exists()
         mock_post.assert_not_called()
 
+    @parameterized.expand(
+        [
+            ("unchanged_content", False, {"content_hash": PASSWORD_RESET_HASH}),
+            (
+                "superseded_content",
+                True,
+                {"content_hash": "v1:" + "0" * 64, "superseded_content_hashes": [PASSWORD_RESET_HASH]},
+            ),
+        ]
+    )
+    def test_a_member_denied_the_workflow_cannot_upload_to_it(
+        self, mock_post, _flag, _name, if_not_superseded, stored_hashes
+    ):
+        MessageTemplate.objects.filter(id=self.template.id).update(managed_by="code", **stored_hashes)
+
+        with patch(
+            "products.messaging.backend.presentation.views.message_templates.posthoganalytics.capture"
+        ) as capture:
+            response = self.client.put(
+                f"/api/projects/{self.team.id}/messaging_templates/by_key/password-reset/",
+                {
+                    "name": "Password reset",
+                    "subject": "Reset your password",
+                    "html": "<p>Reset</p>",
+                    "source": {"repository": "github.com/example/other"},
+                    "if_not_superseded": if_not_superseded,
+                },
+                format="json",
+            )
+
+        assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
+        self.template.refresh_from_db()
+        assert self.template.source_repository is None
+        uploaded_events = [
+            c for c in capture.call_args_list if c.kwargs["event"] == "transactional email template uploaded"
+        ]
+        assert [e.kwargs["properties"]["error_code"] for e in uploaded_events] == ["permission_denied"]
+
     @parameterized.expand([("unlinked", None), ("linked_to_a_deleted_workflow", uuid4())])
     def test_editor_access_to_one_workflow_cannot_create_another(self, mock_post, _flag, _name, linked_hog_flow_id):
         self._login_member("viewer@example.com", {None: "viewer", str(self.hog_flow_id): "editor"})
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index c2589162ff0b..91c5e4e810db 100644
--- a/products/messaging/frontend/generated/api.schemas.ts
+++ b/products/messaging/frontend/generated/api.schemas.ts
@@ -78,7 +78,7 @@ export interface SendEmailApi {
     /** The transactional email template to send. Send either `template` or `template_key`. */
     template?: SendEmailTemplateApi
     /**
-     * Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template.
+     * Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template. Once you upload a template under this key, these sends run through that template's workflow, so their metrics and logs group with the template from then on.
      * @maxLength 400
      * @pattern ^[a-zA-Z0-9_-]+$
      */
@@ -757,6 +757,17 @@ export interface UserBasicApi {
     role_at_organization?: RoleAtOrganizationEnumApi | BlankEnumApi | null
 }
 
+/**
+ * * `gui` - GUI
+ * * `code` - Code
+ */
+export type TemplateManagedByEnumApi = (typeof TemplateManagedByEnumApi)[keyof typeof TemplateManagedByEnumApi]
+
+export const TemplateManagedByEnumApi = {
+    Gui: 'gui',
+    Code: 'code',
+} as const
+
 export interface MessageTemplateApi {
     readonly id: string
     /**
@@ -798,6 +809,36 @@ export interface MessageTemplateApi {
     readonly transactional_hog_flow_id: string | null
     /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
     draft_content?: MessageTemplateContentApi | null
+    /**
+     * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
+     * @nullable
+     */
+    readonly key: string | null
+    /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+     *
+     * * `gui` - GUI
+     * * `code` - Code */
+    readonly managed_by: TemplateManagedByEnumApi | null
+    /**
+     * Repository the template was last uploaded from, such as `github.com/example/app`.
+     * @nullable
+     */
+    readonly source_repository: string | null
+    /**
+     * Path of the template file in the source repository.
+     * @nullable
+     */
+    readonly source_path: string | null
+    /**
+     * Commit or branch the template was last uploaded from.
+     * @nullable
+     */
+    readonly source_ref: string | null
+    /**
+     * Hash of the published subject, preheader, HTML and text, as `v1:` and 64 hex characters. Changes with every save that changes them.
+     * @nullable
+     */
+    readonly content_hash: string | null
 }
 
 export interface PaginatedMessageTemplateListApi {
@@ -850,6 +891,36 @@ export interface PatchedMessageTemplateApi {
     readonly transactional_hog_flow_id?: string | null
     /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
     draft_content?: MessageTemplateContentApi | null
+    /**
+     * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
+     * @nullable
+     */
+    readonly key?: string | null
+    /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+     *
+     * * `gui` - GUI
+     * * `code` - Code */
+    readonly managed_by?: TemplateManagedByEnumApi | null
+    /**
+     * Repository the template was last uploaded from, such as `github.com/example/app`.
+     * @nullable
+     */
+    readonly source_repository?: string | null
+    /**
+     * Path of the template file in the source repository.
+     * @nullable
+     */
+    readonly source_path?: string | null
+    /**
+     * Commit or branch the template was last uploaded from.
+     * @nullable
+     */
+    readonly source_ref?: string | null
+    /**
+     * Hash of the published subject, preheader, HTML and text, as `v1:` and 64 hex characters. Changes with every save that changes them.
+     * @nullable
+     */
+    readonly content_hash?: string | null
 }
 
 /**
@@ -932,6 +1003,110 @@ export interface SendTransactionalEmailApi {
     message_data?: SendTransactionalEmailApiMessageData
 }
 
+export interface TemplateSourceApi {
+    /**
+     * Host and path of the repository the file is in, such as `github.com/example/app`.
+     * @maxLength 400
+     * @nullable
+     */
+    repository?: string | null
+    /**
+     * Path of the template file in the repository, such as `emails/welcome.html`.
+     * @maxLength 400
+     * @nullable
+     */
+    path?: string | null
+    /**
+     * Commit or branch the file was uploaded from.
+     * @maxLength 400
+     * @nullable
+     */
+    ref?: string | null
+}
+
+export interface UploadTemplateApi {
+    /**
+     * Template name shown in the template library.
+     * @maxLength 400
+     */
+    name: string
+    /** Email subject line. Supports Liquid, such as `{{ variables.first_name }}`. */
+    subject: string
+    /** Email body as HTML, stored as sent. Supports Liquid, such as `{{ variables.first_name }}`. */
+    html: string
+    /** Plain-text body for email clients that can't show HTML. Leaving it out removes the stored one. */
+    text?: string
+    /** Inbox preview text shown after the subject. Leaving it out removes the stored one. */
+    preheader?: string
+    /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
+    if_not_superseded?: boolean
+    /** Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored. */
+    source?: TemplateSourceApi
+}
+
+/**
+ * * `created` - Created
+ * * `updated` - Updated
+ * * `unchanged` - Unchanged
+ * * `superseded` - Superseded
+ */
+export type TemplateUploadResultEnumApi = (typeof TemplateUploadResultEnumApi)[keyof typeof TemplateUploadResultEnumApi]
+
+export const TemplateUploadResultEnumApi = {
+    Created: 'created',
+    Updated: 'updated',
+    Unchanged: 'unchanged',
+    Superseded: 'superseded',
+} as const
+
+export interface UploadTemplateResponseApi {
+    /** ID of the template. */
+    id: string
+    /** Key of the template. */
+    key: string
+    /** `created`: the upload made a new template. `updated`: it published the uploaded content. `unchanged`: the template already had this content, so nothing was published. `superseded`: the upload set `if_not_superseded` and newer content already replaced this content, so nothing was published.
+     *
+     * * `created` - Created
+     * * `updated` - Updated
+     * * `unchanged` - Unchanged
+     * * `superseded` - Superseded */
+    result: TemplateUploadResultEnumApi
+    /** Hash of the published content, as `v1:` and 64 hex characters. After `superseded` it is the hash of the newer content. */
+    content_hash: string
+    /** `code` after every upload except `superseded`, which changes nothing. After `superseded` it is what the template had, which is null for a template made in PostHog that no upload claimed yet.
+     *
+     * * `gui` - GUI
+     * * `code` - Code */
+    managed_by: TemplateManagedByEnumApi | null
+    /**
+     * The workflow that sends this template. Each upload that changes the content writes a new version of it. Null only after `superseded`, on a template that is not transactional yet.
+     * @nullable
+     */
+    transactional_hog_flow_id: string | null
+    /** Where the template file lives, as stored after the upload. */
+    source: TemplateSourceApi
+}
+
+export interface TemplateErrorApi {
+    /** Error class, such as `invalid_request`. */
+    type: string
+    /** Stable error code to branch on, such as `invalid_template_key`. */
+    code: string
+    /** What went wrong. */
+    detail: string
+    /**
+     * The request field the error is about, if any.
+     * @nullable
+     */
+    attr: string | null
+    /** Why PostHog refuses the request. */
+    why?: string
+    /** What to change before you retry. */
+    fix?: string
+    /** Documentation for this error code. */
+    docs_url?: string
+}
+
 export type MessagingCategoriesListParams = {
     /**
      * Number of results to return per page.
diff --git a/products/messaging/frontend/generated/api.ts b/products/messaging/frontend/generated/api.ts
index 9a664794b377..95621f803b8b 100644
--- a/products/messaging/frontend/generated/api.ts
+++ b/products/messaging/frontend/generated/api.ts
@@ -42,6 +42,8 @@ import type {
     SendTransactionalEmailResponseApi,
     StartProviderImportApi,
     SupabaseAuthEmailSettingsApi,
+    UploadTemplateApi,
+    UploadTemplateResponseApi,
     WebhookUrlApi,
 } from './api.schemas'
 
@@ -977,3 +979,25 @@ export const messagingTemplatesSendCreate = async (
         body: JSON.stringify(sendTransactionalEmailApi),
     })
 }
+
+export const getMessagingTemplatesByKeyUpdateUrl = (projectId: string, key: string) => {
+    return `/api/projects/${projectId}/messaging_templates/by_key/${key}/`
+}
+
+/**
+ * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps the template's sender and never turns a paused template back on.
+ * @summary Upload a template by key
+ */
+export const messagingTemplatesByKeyUpdate = async (
+    projectId: string,
+    key: string,
+    uploadTemplateApi: UploadTemplateApi,
+    options?: RequestInit
+): Promise<UploadTemplateResponseApi> => {
+    return apiMutator<UploadTemplateResponseApi>(getMessagingTemplatesByKeyUpdateUrl(projectId, key), {
+        ...options,
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json', ...options?.headers },
+        body: JSON.stringify(uploadTemplateApi),
+    })
+}
diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.ts
index eb0657a06905..035e47924c17 100644
--- a/products/messaging/frontend/generated/api.zod.ts
+++ b/products/messaging/frontend/generated/api.zod.ts
@@ -54,7 +54,7 @@ export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({
         .regex(messagingSendEmailCreateBodyTemplateKeyRegExp)
         .optional()
         .describe(
-            'Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template.'
+            "Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template. Once you upload a template under this key, these sends run through that template's workflow, so their metrics and logs group with the template from then on."
         ),
     distinct_id: zod
         .string()
@@ -1399,3 +1399,63 @@ export const MessagingTemplatesSendCreateBody = /* @__PURE__ */ zod.object({
             'Data for the template\'s Liquid placeholders, available as `variables`. For example `{\"reset_link\": \"https:\/\/...\"}` fills `{{ variables.reset_link }}`.'
         ),
 })
+
+/**
+ * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps the template's sender and never turns a paused template back on.
+ * @summary Upload a template by key
+ */
+export const messagingTemplatesByKeyUpdateBodyNameMax = 400
+
+export const messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault = false
+export const messagingTemplatesByKeyUpdateBodySourceOneRepositoryMax = 400
+
+export const messagingTemplatesByKeyUpdateBodySourceOnePathMax = 400
+
+export const messagingTemplatesByKeyUpdateBodySourceOneRefMax = 400
+
+export const MessagingTemplatesByKeyUpdateBody = /* @__PURE__ */ zod.object({
+    name: zod
+        .string()
+        .max(messagingTemplatesByKeyUpdateBodyNameMax)
+        .describe('Template name shown in the template library.'),
+    subject: zod.string().describe('Email subject line. Supports Liquid, such as `{{ variables.first_name }}`.'),
+    html: zod
+        .string()
+        .describe('Email body as HTML, stored as sent. Supports Liquid, such as `{{ variables.first_name }}`.'),
+    text: zod
+        .string()
+        .optional()
+        .describe("Plain-text body for email clients that can't show HTML. Leaving it out removes the stored one."),
+    preheader: zod
+        .string()
+        .optional()
+        .describe('Inbox preview text shown after the subject. Leaving it out removes the stored one.'),
+    if_not_superseded: zod
+        .boolean()
+        .default(messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault)
+        .describe(
+            'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
+        ),
+    source: zod
+        .object({
+            repository: zod
+                .string()
+                .max(messagingTemplatesByKeyUpdateBodySourceOneRepositoryMax)
+                .nullish()
+                .describe('Host and path of the repository the file is in, such as `github.com\/example\/app`.'),
+            path: zod
+                .string()
+                .max(messagingTemplatesByKeyUpdateBodySourceOnePathMax)
+                .nullish()
+                .describe('Path of the template file in the repository, such as `emails\/welcome.html`.'),
+            ref: zod
+                .string()
+                .max(messagingTemplatesByKeyUpdateBodySourceOneRefMax)
+                .nullish()
+                .describe('Commit or branch the file was uploaded from.'),
+        })
+        .optional()
+        .describe(
+            'Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored.'
+        ),
+})
diff --git a/products/workflows/mcp/email_templates.yaml b/products/workflows/mcp/email_templates.yaml
index 98f6995beab7..f9f67c862a28 100644
--- a/products/workflows/mcp/email_templates.yaml
+++ b/products/workflows/mcp/email_templates.yaml
@@ -186,6 +186,30 @@ tools:
                 - content.email.design
                 - created_by
                 - draft_content
+    workflows-upload-email-template:
+        operation: messaging_templates_by_key_update
+        enabled: true
+        feature_flag: workflows-email-from-code
+        annotations:
+            readOnly: false
+            destructive: false
+            idempotent: true
+        enrich_url: '{id}'
+        title: Upload email template by key
+        description: >
+            Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or
+            password-reset). Use this for templates that live in code; use workflows-create-email-template for
+            templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source
+            (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates
+            can't read person properties. The first upload creates the template and makes it sendable over the
+            transactional email API with the project's default verified sender, so verify a sender first. Later uploads
+            publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made
+            in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content: an
+            answer of superseded means newer content is already published and nothing changed. The check covers the
+            last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish
+            this content even when newer content replaced it, such as to roll back. A 404 with code not_found means
+            sending email from code is not enabled for this project, or the project does not exist: stop and tell
+            the user.
     workflows-update-email-template:
         operation: messaging_templates_partial_update
         enabled: true
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index dfe1cbc1ba77..97693ceef442 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -17360,6 +17360,22 @@
             "readOnlyHint": false
         }
     },
+    "workflows-upload-email-template": {
+        "description": "Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or password-reset). Use this for templates that live in code; use workflows-create-email-template for templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates can't read person properties. The first upload creates the template and makes it sendable over the transactional email API with the project's default verified sender, so verify a sender first. Later uploads publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content: an answer of superseded means newer content is already published and nothing changed. The check covers the last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish this content even when newer content replaced it, such as to roll back. A 404 with code not_found means sending email from code is not enabled for this project, or the project does not exist: stop and tell the user.",
+        "category": "Workflows",
+        "feature": "workflows",
+        "summary": "Upload email template by key",
+        "title": "Upload email template by key",
+        "required_scopes": ["hog_flow:write"],
+        "api_operations": ["PUT /api/projects/{project_id}/messaging_templates/by_key/{key}/"],
+        "annotations": {
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": true,
+            "readOnlyHint": false
+        },
+        "feature_flag": "workflows-email-from-code"
+    },
     "workflows-version-stats": {
         "description": "Execution stats for a single published version of a workflow, in the same shape as workflows-stats. That is how you tell whether a change helped: compare the version before it with the version after it. The unversioned read in workflows-stats keys batch and broadcast runs on the run rather than the workflow, so it is not the sum of the versions - compare versions with each other, not with it. Set instance_id to the step you are reading, or several steps share one denominator.",
         "category": "Workflows",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 42551aab6a87..ba67e6f8528a 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -18207,6 +18207,22 @@
             "readOnlyHint": false
         }
     },
+    "workflows-upload-email-template": {
+        "description": "Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or password-reset). Use this for templates that live in code; use workflows-create-email-template for templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates can't read person properties. The first upload creates the template and makes it sendable over the transactional email API with the project's default verified sender, so verify a sender first. Later uploads publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content: an answer of superseded means newer content is already published and nothing changed. The check covers the last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish this content even when newer content replaced it, such as to roll back. A 404 with code not_found means sending email from code is not enabled for this project, or the project does not exist: stop and tell the user.",
+        "category": "Workflows",
+        "feature": "workflows",
+        "summary": "Upload email template by key",
+        "title": "Upload email template by key",
+        "required_scopes": ["hog_flow:write"],
+        "api_operations": ["PUT /api/projects/{project_id}/messaging_templates/by_key/{key}/"],
+        "annotations": {
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": true,
+            "readOnlyHint": false
+        },
+        "feature_flag": "workflows-email-from-code"
+    },
     "workflows-version-stats": {
         "description": "Execution stats for a single published version of a workflow, in the same shape as workflows-stats. That is how you tell whether a change helped: compare the version before it with the version after it. The unversioned read in workflows-stats keys batch and broadcast runs on the run rather than the workflow, so it is not the sum of the versions - compare versions with each other, not with it. Set instance_id to the step you are reading, or several steps share one denominator.",
         "category": "Workflows",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index fbe769cbeea5..70c85f265f0e 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -72925,6 +72925,18 @@ export namespace Schemas {
       email?: EmailTemplate | null;
     }
 
+    /**
+     * * `gui` - GUI
+     * * `code` - Code
+     */
+    export type TemplateManagedByEnum = typeof TemplateManagedByEnum[keyof typeof TemplateManagedByEnum];
+
+
+    export const TemplateManagedByEnum = {
+      Gui: 'gui',
+      Code: 'code',
+    } as const;
+
     export interface MessageTemplate {
       readonly id: string;
       /**
@@ -72966,6 +72978,36 @@ export namespace Schemas {
       readonly transactional_hog_flow_id: string | null;
       /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
       draft_content?: MessageTemplateContent | null;
+      /**
+         * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
+         * @nullable
+         */
+      readonly key: string | null;
+      /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+       *
+       * * `gui` - GUI
+       * * `code` - Code */
+      readonly managed_by: TemplateManagedByEnum | null;
+      /**
+         * Repository the template was last uploaded from, such as `github.com/example/app`.
+         * @nullable
+         */
+      readonly source_repository: string | null;
+      /**
+         * Path of the template file in the source repository.
+         * @nullable
+         */
+      readonly source_path: string | null;
+      /**
+         * Commit or branch the template was last uploaded from.
+         * @nullable
+         */
+      readonly source_ref: string | null;
+      /**
+         * Hash of the published subject, preheader, HTML and text, as `v1:` and 64 hex characters. Changes with every save that changes them.
+         * @nullable
+         */
+      readonly content_hash: string | null;
     }
 
     export interface MessagingError {
@@ -90460,6 +90502,36 @@ export namespace Schemas {
       readonly transactional_hog_flow_id?: string | null;
       /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
       draft_content?: MessageTemplateContent | null;
+      /**
+         * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
+         * @nullable
+         */
+      readonly key?: string | null;
+      /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+       *
+       * * `gui` - GUI
+       * * `code` - Code */
+      readonly managed_by?: TemplateManagedByEnum | null;
+      /**
+         * Repository the template was last uploaded from, such as `github.com/example/app`.
+         * @nullable
+         */
+      readonly source_repository?: string | null;
+      /**
+         * Path of the template file in the source repository.
+         * @nullable
+         */
+      readonly source_path?: string | null;
+      /**
+         * Commit or branch the template was last uploaded from.
+         * @nullable
+         */
+      readonly source_ref?: string | null;
+      /**
+         * Hash of the published subject, preheader, HTML and text, as `v1:` and 64 hex characters. Changes with every save that changes them.
+         * @nullable
+         */
+      readonly content_hash?: string | null;
     }
 
     /**
@@ -110909,7 +110981,7 @@ export namespace Schemas {
       /** The transactional email template to send. Send either `template` or `template_key`. */
       template?: SendEmailTemplate;
       /**
-         * Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template.
+         * Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template. Once you upload a template under this key, these sends run through that template's workflow, so their metrics and logs group with the template from then on.
          * @maxLength 400
          * @pattern ^[a-zA-Z0-9_-]+$
          */
@@ -122060,6 +122132,26 @@ export namespace Schemas {
       readonly retention_last_updated: string | null;
     }
 
+    export interface TemplateError {
+      /** Error class, such as `invalid_request`. */
+      type: string;
+      /** Stable error code to branch on, such as `invalid_template_key`. */
+      code: string;
+      /** What went wrong. */
+      detail: string;
+      /**
+         * The request field the error is about, if any.
+         * @nullable
+         */
+      attr: string | null;
+      /** Why PostHog refuses the request. */
+      why?: string;
+      /** What to change before you retry. */
+      fix?: string;
+      /** Documentation for this error code. */
+      docs_url?: string;
+    }
+
     export interface TemplateInfo {
       /** Template identifier, e.g. 'likely_active_soon'. Pass to autoresearch-resolve-template-create.
        *
@@ -122083,6 +122175,43 @@ export namespace Schemas {
       notes: string;
     }
 
+    export interface TemplateSource {
+      /**
+         * Host and path of the repository the file is in, such as `github.com/example/app`.
+         * @maxLength 400
+         * @nullable
+         */
+      repository?: string | null;
+      /**
+         * Path of the template file in the repository, such as `emails/welcome.html`.
+         * @maxLength 400
+         * @nullable
+         */
+      path?: string | null;
+      /**
+         * Commit or branch the file was uploaded from.
+         * @maxLength 400
+         * @nullable
+         */
+      ref?: string | null;
+    }
+
+    /**
+     * * `created` - Created
+     * * `updated` - Updated
+     * * `unchanged` - Unchanged
+     * * `superseded` - Superseded
+     */
+    export type TemplateUploadResultEnum = typeof TemplateUploadResultEnum[keyof typeof TemplateUploadResultEnum];
+
+
+    export const TemplateUploadResultEnum = {
+      Created: 'created',
+      Updated: 'updated',
+      Unchanged: 'unchanged',
+      Superseded: 'superseded',
+    } as const;
+
     /**
      * Anthropic text, image, or tool content blocks.
      */
@@ -123398,6 +123527,54 @@ export namespace Schemas {
       results: ResultSubmission[];
     }
 
+    export interface UploadTemplate {
+      /**
+         * Template name shown in the template library.
+         * @maxLength 400
+         */
+      name: string;
+      /** Email subject line. Supports Liquid, such as `{{ variables.first_name }}`. */
+      subject: string;
+      /** Email body as HTML, stored as sent. Supports Liquid, such as `{{ variables.first_name }}`. */
+      html: string;
+      /** Plain-text body for email clients that can't show HTML. Leaving it out removes the stored one. */
+      text?: string;
+      /** Inbox preview text shown after the subject. Leaving it out removes the stored one. */
+      preheader?: string;
+      /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
+      if_not_superseded?: boolean;
+      /** Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored. */
+      source?: TemplateSource;
+    }
+
+    export interface UploadTemplateResponse {
+      /** ID of the template. */
+      id: string;
+      /** Key of the template. */
+      key: string;
+      /** `created`: the upload made a new template. `updated`: it published the uploaded content. `unchanged`: the template already had this content, so nothing was published. `superseded`: the upload set `if_not_superseded` and newer content already replaced this content, so nothing was published.
+       *
+       * * `created` - Created
+       * * `updated` - Updated
+       * * `unchanged` - Unchanged
+       * * `superseded` - Superseded */
+      result: TemplateUploadResultEnum;
+      /** Hash of the published content, as `v1:` and 64 hex characters. After `superseded` it is the hash of the newer content. */
+      content_hash: string;
+      /** `code` after every upload except `superseded`, which changes nothing. After `superseded` it is what the template had, which is null for a template made in PostHog that no upload claimed yet.
+       *
+       * * `gui` - GUI
+       * * `code` - Code */
+      managed_by: TemplateManagedByEnum | null;
+      /**
+         * The workflow that sends this template. Each upload that changes the content writes a new version of it. Null only after `superseded`, on a template that is not transactional yet.
+         * @nullable
+         */
+      transactional_hog_flow_id: string | null;
+      /** Where the template file lives, as stored after the upload. */
+      source: TemplateSource;
+    }
+
     export interface UploadVersionRequest {
       /** Zip archive containing the Streamlit app sources (max 10 MB). */
       file: string;
diff --git a/services/mcp/src/generated/email_templates/api.ts b/services/mcp/src/generated/email_templates/api.ts
index 1e1f69891b61..c9c0288b7844 100644
--- a/services/mcp/src/generated/email_templates/api.ts
+++ b/services/mcp/src/generated/email_templates/api.ts
@@ -3,7 +3,7 @@
  * MCP service uses these Zod schemas for generated tool handlers.
  * To regenerate: hogli build:openapi
  *
- * PostHog API - MCP 7 enabled ops
+ * PostHog API - MCP 8 enabled ops
  * OpenAPI spec version: 1.0.0
  */
 import * as zod from 'zod'
@@ -44,7 +44,7 @@ export const MessagingSendEmailCreateBody = () => zod.object({
         .regex(messagingSendEmailCreateBodyTemplateKeyRegExp)
         .optional()
         .describe(
-            'Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template.'
+            "Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template. Once you upload a template under this key, these sends run through that template's workflow, so their metrics and logs group with the template from then on."
         ),
     distinct_id: zod
         .string()
@@ -488,3 +488,76 @@ export const MessagingTemplatesMakeTransactionalCreateBody = () => zod.object({
             "ID of the verified email sender integration the email is sent from. Defaults to the project's default sender."
         ),
 })
+
+/**
+ * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps the template's sender and never turns a paused template back on.
+ * @summary Upload a template by key
+ */
+export const MessagingTemplatesByKeyUpdateParams = () => zod.object({
+    key: zod
+        .string()
+        .describe(
+            'Key of the template, chosen by you. Letters, digits, hyphens (-) and underscores (_), at most 400 characters. The same key names the template in every project.'
+        ),
+    project_id: zod
+        .string()
+        .describe(
+            "Project ID of the project you're trying to access. To find the ID of the project, make a call to \/api\/projects\/."
+        ),
+})
+
+export const messagingTemplatesByKeyUpdateBodyNameMax = 400
+
+export const messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault = false
+export const messagingTemplatesByKeyUpdateBodySourceOneRepositoryMax = 400
+
+export const messagingTemplatesByKeyUpdateBodySourceOnePathMax = 400
+
+export const messagingTemplatesByKeyUpdateBodySourceOneRefMax = 400
+
+export const MessagingTemplatesByKeyUpdateBody = () => zod.object({
+    name: zod
+        .string()
+        .max(messagingTemplatesByKeyUpdateBodyNameMax)
+        .describe('Template name shown in the template library.'),
+    subject: zod.string().describe('Email subject line. Supports Liquid, such as `{{ variables.first_name }}`.'),
+    html: zod
+        .string()
+        .describe('Email body as HTML, stored as sent. Supports Liquid, such as `{{ variables.first_name }}`.'),
+    text: zod
+        .string()
+        .optional()
+        .describe("Plain-text body for email clients that can't show HTML. Leaving it out removes the stored one."),
+    preheader: zod
+        .string()
+        .optional()
+        .describe('Inbox preview text shown after the subject. Leaving it out removes the stored one.'),
+    if_not_superseded: zod
+        .boolean()
+        .default(messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault)
+        .describe(
+            'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
+        ),
+    source: zod
+        .object({
+            repository: zod
+                .string()
+                .max(messagingTemplatesByKeyUpdateBodySourceOneRepositoryMax)
+                .nullish()
+                .describe('Host and path of the repository the file is in, such as `github.com\/example\/app`.'),
+            path: zod
+                .string()
+                .max(messagingTemplatesByKeyUpdateBodySourceOnePathMax)
+                .nullish()
+                .describe('Path of the template file in the repository, such as `emails\/welcome.html`.'),
+            ref: zod
+                .string()
+                .max(messagingTemplatesByKeyUpdateBodySourceOneRefMax)
+                .nullish()
+                .describe('Commit or branch the file was uploaded from.'),
+        })
+        .optional()
+        .describe(
+            'Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored.'
+        ),
+})
diff --git a/services/mcp/src/tools/generated/email_templates.ts b/services/mcp/src/tools/generated/email_templates.ts
index cebec5e645a2..fc5aac13015e 100644
--- a/services/mcp/src/tools/generated/email_templates.ts
+++ b/services/mcp/src/tools/generated/email_templates.ts
@@ -311,6 +311,53 @@ const workflowsShowEmailTemplate = (): ToolBase<
         },
     })
 
+const WorkflowsUploadEmailTemplateSchema = () => {
+    const MessagingTemplatesByKeyUpdateBody = orvalSchemas.MessagingTemplatesByKeyUpdateBody()
+    const MessagingTemplatesByKeyUpdateParams = orvalSchemas.MessagingTemplatesByKeyUpdateParams()
+    return MessagingTemplatesByKeyUpdateParams.omit({ project_id: true }).extend(
+        MessagingTemplatesByKeyUpdateBody.shape
+    )
+}
+
+const workflowsUploadEmailTemplate = (): ToolBase<
+    ReturnType<typeof WorkflowsUploadEmailTemplateSchema>,
+    WithPostHogUrl<Schemas.UploadTemplateResponse>
+> => ({
+    name: 'workflows-upload-email-template',
+    schema: WorkflowsUploadEmailTemplateSchema(),
+    handler: async (context: Context, params: z.infer<ReturnType<typeof WorkflowsUploadEmailTemplateSchema>>) => {
+        const projectId = await context.stateManager.getProjectId()
+        const body: Record<string, unknown> = {}
+        if (params.name !== undefined) {
+            body['name'] = params.name
+        }
+        if (params.subject !== undefined) {
+            body['subject'] = params.subject
+        }
+        if (params.html !== undefined) {
+            body['html'] = params.html
+        }
+        if (params.text !== undefined) {
+            body['text'] = params.text
+        }
+        if (params.preheader !== undefined) {
+            body['preheader'] = params.preheader
+        }
+        if (params.if_not_superseded !== undefined) {
+            body['if_not_superseded'] = params.if_not_superseded
+        }
+        if (params.source !== undefined) {
+            body['source'] = params.source
+        }
+        const result = await context.api.request<Schemas.UploadTemplateResponse>({
+            method: 'PUT',
+            path: `/api/projects/${encodeURIComponent(String(projectId))}/messaging_templates/by_key/${encodeURIComponent(String(params.key))}/`,
+            body,
+        })
+        return await withPostHogUrl(context, result, `/workflows/library/templates/${result.id}`)
+    },
+})
+
 const WorkflowsUpdateEmailTemplateSchema = () => {
     const MessagingTemplatesPartialUpdateBody = orvalSchemas.MessagingTemplatesPartialUpdateBody()
     const MessagingTemplatesPartialUpdateParams = orvalSchemas.MessagingTemplatesPartialUpdateParams()
@@ -371,5 +418,6 @@ export const GENERATED_TOOLS: Record<string, () => ToolBase<ZodObjectAny>> = {
     'workflows-make-email-template-transactional-execute': workflowsMakeEmailTemplateTransactionalExecute,
     'workflows-patch-email-template': workflowsPatchEmailTemplate,
     'workflows-show-email-template': workflowsShowEmailTemplate,
+    'workflows-upload-email-template': workflowsUploadEmailTemplate,
     'workflows-update-email-template': workflowsUpdateEmailTemplate,
 }
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
index f627c1c4b881..ce7b83db975e 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
@@ -33,7 +33,7 @@
             "type": "string"
         },
         "template_key": {
-            "description": "Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template.",
+            "description": "Names an email whose content your code rendered, such as `password-reset`, so its metrics, logs and status group under it. Letters, numbers, hyphens (-) and underscores (_) only. Send it with `subject` and `html` or `text`. PostHog sends the content as is and never stores it as a template. Once you upload a template under this key, these sends run through that template's workflow, so their metrics and logs group with the template from then on.",
             "maxLength": 400,
             "pattern": "^[a-zA-Z0-9_-]+$",
             "type": "string"
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
new file mode 100644
index 000000000000..61be523f4553
--- /dev/null
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
@@ -0,0 +1,79 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "properties": {
+        "html": {
+            "description": "Email body as HTML, stored as sent. Supports Liquid, such as `{{ variables.first_name }}`.",
+            "type": "string"
+        },
+        "if_not_superseded": {
+            "default": false,
+            "description": "Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.",
+            "type": "boolean"
+        },
+        "key": {
+            "description": "Key of the template, chosen by you. Letters, digits, hyphens (-) and underscores (_), at most 400 characters. The same key names the template in every project.",
+            "type": "string"
+        },
+        "name": {
+            "description": "Template name shown in the template library.",
+            "maxLength": 400,
+            "type": "string"
+        },
+        "preheader": {
+            "description": "Inbox preview text shown after the subject. Leaving it out removes the stored one.",
+            "type": "string"
+        },
+        "source": {
+            "description": "Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored.",
+            "properties": {
+                "path": {
+                    "anyOf": [
+                        {
+                            "maxLength": 400,
+                            "type": "string"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ],
+                    "description": "Path of the template file in the repository, such as `emails/welcome.html`."
+                },
+                "ref": {
+                    "anyOf": [
+                        {
+                            "maxLength": 400,
+                            "type": "string"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ],
+                    "description": "Commit or branch the file was uploaded from."
+                },
+                "repository": {
+                    "anyOf": [
+                        {
+                            "maxLength": 400,
+                            "type": "string"
+                        },
+                        {
+                            "type": "null"
+                        }
+                    ],
+                    "description": "Host and path of the repository the file is in, such as `github.com/example/app`."
+                }
+            },
+            "type": "object"
+        },
+        "subject": {
+            "description": "Email subject line. Supports Liquid, such as `{{ variables.first_name }}`.",
+            "type": "string"
+        },
+        "text": {
+            "description": "Plain-text body for email clients that can't show HTML. Leaving it out removes the stored one.",
+            "type": "string"
+        }
+    },
+    "required": ["key", "name", "subject", "html"],
+    "type": "object"
+}

From 7a74cedd3d762e14954d212e013cde4cecac500f Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 12:25:45 +0000
Subject: [PATCH 03/42] fix(messaging): check the key's workflow before an
 upload takes its code sends

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../backend/services/template_uploads.py      | 10 +++++-
 .../backend/tests/api/test_template_upload.py | 33 ++++++++++++++++++-
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/products/messaging/backend/services/template_uploads.py b/products/messaging/backend/services/template_uploads.py
index 936e430f9fcd..4ad56332ad4f 100644
--- a/products/messaging/backend/services/template_uploads.py
+++ b/products/messaging/backend/services/template_uploads.py
@@ -18,7 +18,7 @@
 from products.messaging.backend.services.content_hash import email_content_hash, sent_hash_state
 from products.messaging.backend.services.message_templates import record_content_hash
 from products.messaging.backend.services.template_saves import WorkflowEditorCheck, save_locked_template
-from products.messaging.backend.services.transactional_email import is_transactional, make_transactional
+from products.messaging.backend.services.transactional_email import is_transactional, known_key, make_transactional
 
 SOURCE_PARTS = ("repository", "path", "ref")
 
@@ -70,6 +70,8 @@ def _upload(
     require_workflow_create: WorkflowCreateCheck,
 ) -> Uploaded:
     template = locked_template_with_key(team_id, upload.key)
+    if template is None or template.managed_by is None:
+        _require_editor_of_the_key_workflow(team_id, upload.key, require_workflow_editor)
     if template is None:
         require_workflow_create()
         return Uploaded(result=TemplateUploadResult.CREATED, template=_create(team_id, upload, user_id=user_id))
@@ -93,6 +95,12 @@ def _upload(
     return Uploaded(result=TemplateUploadResult.UPDATED, template=template)
 
 
+def _require_editor_of_the_key_workflow(team_id: int, key: str, require_workflow_editor: WorkflowEditorCheck) -> None:
+    key_workflow = known_key(team_id, key)
+    if key_workflow is not None:
+        require_workflow_editor(key_workflow.hog_flow_id)
+
+
 def locked_template_with_key(team_id: int, key: str) -> MessageTemplate | None:
     return MessageTemplate.objects.select_for_update().filter(team_id=team_id, key=key, deleted=False).first()
 
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index f46956de14ba..fff1fc79e2e7 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -7,11 +7,13 @@
 from rest_framework import status
 from rest_framework.test import APIClient
 
-from posthog.models import ProjectSecretAPIKey, Team
+from posthog.constants import AvailableFeature
+from posthog.models import OrganizationMembership, ProjectSecretAPIKey, Team
 from posthog.models.integration import Integration
 from posthog.models.personal_api_key import hash_key_value
 from posthog.models.utils import generate_random_token_secret
 
+from products.access_control.backend.models.access_control import AccessControl
 from products.messaging.backend.models.message_template import MessageTemplate
 from products.messaging.backend.presentation.views.message_templates import (
     EMAIL_FROM_CODE_FLAG,
@@ -300,6 +302,35 @@ def test_refuses_an_upload_it_does_not_allow(
         assert response.status_code == expected_status, response.json()
         assert not MessageTemplate.objects.exists()
 
+    def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edit(
+        self, post: MagicMock, _flag, _capture
+    ):
+        post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
+        code_send = {
+            "to": "user@example.com",
+            "distinct_id": "user-1",
+            "template_key": "welcome",
+            "subject": "Hi",
+            "html": "<p>Hi</p>",
+        }
+        sent = self.psak.post(f"/api/projects/{self.team.id}/messaging/send/email/", code_send, format="json")
+        assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
+        key_workflow_id = post.call_args.args[0].split("/hog_flows/")[1].split("/")[0]
+        self.organization.available_product_features = [
+            {"name": AvailableFeature.ACCESS_CONTROL, "key": AvailableFeature.ACCESS_CONTROL}
+        ]
+        self.organization.save()
+        self.organization_membership.level = OrganizationMembership.Level.MEMBER
+        self.organization_membership.save()
+        AccessControl.objects.create(
+            team=self.team, resource="hog_flow", resource_id=key_workflow_id, access_level="viewer"
+        )
+
+        response = self.client.put(self.url, WELCOME, format="json")
+
+        assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
+        assert not MessageTemplate.objects.exists()
+
     @patch("posthog.rate_limit.is_rate_limit_enabled", return_value=True)
     def test_uploads_leave_the_send_rate_limit_to_sends(self, _rate_limit, post: MagicMock, _flag, _capture):
         post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})

From e8fff1d8895e2ec92b5f32ca6eec30e90fd5f6ef Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 11:54:32 +0000
Subject: [PATCH 04/42] feat(messaging): lock code-managed templates and adopt
 templates into code

A template managed by code now refuses edits in PostHog with
`403 immutable` until someone releases it with `managed_by: gui`, which
captures a `message template released` usage event. A template made in
PostHog moves into code when someone gives it a `key`: the next upload
under that key keeps its id, workflow and sender, and takes over the code
sends under the key from then on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/facade/contracts.py     |  29 +++
 .../messaging/backend/facade/templates.py     |  57 ++++-
 .../presentation/views/message_templates.py   | 114 +++++++++-
 .../backend/services/template_keys.py         |  75 +++++++
 .../backend/services/template_ownership.py    |  53 +++++
 .../backend/services/template_saves.py        |  19 ++
 .../api/test_code_managed_template_lock.py    | 209 ++++++++++++++++++
 .../tests/api/test_template_adoption.py       | 119 ++++++++++
 .../backend/tests/api/test_template_upload.py |  87 ++++++++
 .../frontend/generated/api.schemas.ts         |  68 +++---
 products/messaging/frontend/generated/api.ts  |   6 +-
 .../messaging/frontend/generated/api.zod.ts   |  16 ++
 products/workflows/mcp/email_templates.yaml   |  11 +-
 .../schema/generated-tool-definitions.json    |   4 +-
 services/mcp/schema/tool-definitions-all.json |   4 +-
 services/mcp/src/api/generated.ts             |  29 ++-
 .../mcp/src/generated/email_templates/api.ts  |   9 +
 .../src/tools/generated/email_templates.ts    |   3 +
 .../workflows-update-email-template.json      |   5 +
 19 files changed, 859 insertions(+), 58 deletions(-)
 create mode 100644 products/messaging/backend/services/template_keys.py
 create mode 100644 products/messaging/backend/services/template_ownership.py
 create mode 100644 products/messaging/backend/tests/api/test_code_managed_template_lock.py
 create mode 100644 products/messaging/backend/tests/api/test_template_adoption.py

diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 7744ebe3b122..625b908e1636 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any
@@ -204,6 +205,10 @@ class TemplateManagedBy(LabeledStrEnum):
     CODE = "code", "Code"
 
 
+class TemplateReleasedTo(LabeledStrEnum):
+    GUI = "gui", "GUI"
+
+
 class TemplateUploadResult(LabeledStrEnum):
     CREATED = "created", "Created"
     UPDATED = "updated", "Updated"
@@ -218,6 +223,30 @@ class ContentHashState(LabeledStrEnum):
     OUTDATED = "outdated", "Outdated"
 
 
+@frozen
+class TemplateWriteIntent:
+    action: str
+    payload: Mapping[str, Any]
+
+
+class TemplateWriteRefused(Exception):
+    def __init__(self, *, code: str, detail: str, why: str, fix: str) -> None:
+        super().__init__(detail)
+        self.code = code
+        self.detail = detail
+        self.why = why
+        self.fix = fix
+
+
+class TemplateManagedByCode(TemplateWriteRefused):
+    def __init__(self, *, detail: str, why: str, fix: str) -> None:
+        super().__init__(code="immutable", detail=detail, why=why, fix=fix)
+
+
+class TemplateKeyRefused(TemplateWriteRefused):
+    pass
+
+
 @frozen
 class TemplateSource:
     repository: str | None
diff --git a/products/messaging/backend/facade/templates.py b/products/messaging/backend/facade/templates.py
index 01773546093c..eb3190b3e1bc 100644
--- a/products/messaging/backend/facade/templates.py
+++ b/products/messaging/backend/facade/templates.py
@@ -10,10 +10,17 @@
 from posthog.api.tagged_item import current_tag_names
 from posthog.dataclasses import frozen
 
-from products.messaging.backend.facade.contracts import TemplateManagedBy, TemplateUpload, TemplateUploadResult
+from products.messaging.backend.facade.contracts import (
+    TemplateManagedBy,
+    TemplateUpload,
+    TemplateUploadResult,
+    TemplateWriteIntent,
+)
 from products.messaging.backend.models.message_template import MessageTemplate
 from products.messaging.backend.services import (
     message_templates as templates_service,
+    template_keys,
+    template_ownership,
     template_saves,
     template_uploads,
 )
@@ -122,10 +129,13 @@ def save_template_draft(
     template_id: UUID,
     draft: dict[str, Any] | None,
     *,
+    intent: TemplateWriteIntent,
     require_workflow_editor: Callable[[UUID], None],
 ) -> MessageTemplateRow:
     return _to_contract(
-        template_saves.save_locked_draft(team_id, template_id, draft, require_workflow_editor=require_workflow_editor)
+        template_saves.save_locked_draft(
+            team_id, template_id, draft, intent=intent, require_workflow_editor=require_workflow_editor
+        )
     )
 
 
@@ -134,6 +144,7 @@ def save_template_fields(
     template_id: UUID,
     fields: dict[str, Any],
     *,
+    intent: TemplateWriteIntent,
     user_id: int | None,
     require_workflow_editor: Callable[[UUID], None],
 ) -> MessageTemplateRow:
@@ -149,6 +160,7 @@ def write(template: MessageTemplate) -> None:
             team_id,
             template_id,
             write,
+            intent=intent,
             user_id=user_id,
             require_workflow_editor=require_workflow_editor,
         )
@@ -160,6 +172,7 @@ def save_template_content(
     template_id: UUID,
     edit: Callable[[dict[str, Any]], dict[str, Any]],
     *,
+    intent: TemplateWriteIntent,
     user_id: int | None,
     require_workflow_editor: Callable[[UUID], None],
 ) -> MessageTemplateRow:
@@ -168,12 +181,52 @@ def save_template_content(
             team_id,
             template_id,
             lambda template: templates_service.edit_content(template, edit),
+            intent=intent,
             user_id=user_id,
             require_workflow_editor=require_workflow_editor,
         )
     )
 
 
+def check_template_write(template: MessageTemplateRow, intent: TemplateWriteIntent) -> None:
+    template_ownership.check_write(template, intent)
+
+
+def is_release(intent: TemplateWriteIntent) -> bool:
+    return template_ownership.is_release(intent)
+
+
+def release_template(
+    team_id: int, template_id: UUID, *, require_workflow_editor: Callable[[UUID], None]
+) -> MessageTemplateRow:
+    return _to_contract(
+        template_saves.release_template(team_id, template_id, require_workflow_editor=require_workflow_editor)
+    )
+
+
+def is_adoption(intent: TemplateWriteIntent) -> bool:
+    return template_keys.is_adoption(intent)
+
+
+def check_template_key_write(template: MessageTemplateRow, intent: TemplateWriteIntent) -> None:
+    template_keys.check_key_unchanged(template, intent)
+
+
+def adopt_template(
+    team_id: int,
+    template_id: UUID,
+    key: str,
+    *,
+    intent: TemplateWriteIntent,
+    require_workflow_editor: Callable[[UUID], None],
+) -> MessageTemplateRow:
+    return _to_contract(
+        template_keys.adopt_template(
+            team_id, template_id, key, intent=intent, require_workflow_editor=require_workflow_editor
+        )
+    )
+
+
 def upload_template(
     team_id: int,
     upload: TemplateUpload,
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index a18afb2ec84d..049c848b485a 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -19,7 +19,7 @@
     extend_schema_field,
     extend_schema_view,
 )
-from rest_framework import exceptions, serializers, status, viewsets
+from rest_framework import exceptions, permissions, serializers, status, viewsets
 from rest_framework.decorators import action
 from rest_framework.exceptions import NotFound
 from rest_framework.permissions import IsAuthenticated
@@ -48,19 +48,30 @@
     validate_design,
 )
 from products.messaging.backend.facade.contracts import (
+    TEMPLATE_KEY_MAX_LENGTH,
     TemplateManagedBy,
+    TemplateManagedByCode,
+    TemplateReleasedTo,
     TemplateSource,
     TemplateUpload,
     TemplateUploadResult,
+    TemplateWriteIntent,
+    TemplateWriteRefused,
 )
 from products.messaging.backend.facade.templates import (
     MessageCategoryNotInTeam,
     MessageTemplateMissing,
     MessageTemplateRow,
     UploadedTemplate,
+    adopt_template,
+    check_template_key_write,
+    check_template_write,
     create_template,
     get_template,
+    is_adoption,
+    is_release,
     list_templates,
+    release_template,
     save_template_content,
     save_template_draft,
     save_template_fields,
@@ -87,6 +98,7 @@
 from products.messaging.backend.presentation.views.serializers import DesignOperationSerializer
 from products.messaging.backend.presentation.views.template_refusals import (
     TemplateErrorSerializer,
+    TemplateRefusal,
     invalid_request,
     invalid_template_key,
 )
@@ -340,14 +352,15 @@ class MessageTemplateSerializer(serializers.Serializer):
         read_only=True,
         allow_null=True,
         help_text="Stable identifier code uses to upload and send this template, unique within the project. Null "
-        "for templates that have no key. Set once, by the first upload.",
+        "for templates that have no key. Set once, by the first upload or by a PATCH whose only field is `key`.",
     )
     managed_by = serializers.ChoiceField(
         choices=TemplateManagedBy.choices,
         read_only=True,
         allow_null=True,
-        help_text="Who owns the content. `code` when it was uploaded from a repository, and the template changes "
-        "through its next upload. `gui` or null when it is edited in PostHog.",
+        help_text="Who owns the content. `code` when it was uploaded from a repository: PostHog then refuses edits, and "
+        "the template changes through its next upload. To edit it in PostHog, send a PATCH whose only field is "
+        "`managed_by` set to `gui`. `gui` or null when it is edited in PostHog.",
     )
     source_repository = serializers.CharField(
         read_only=True,
@@ -413,6 +426,23 @@ def validate(self, data: Any) -> Any:
         return data
 
 
+class MessageTemplateUpdateSerializer(MessageTemplateSerializer):
+    key = serializers.CharField(
+        required=False,
+        max_length=TEMPLATE_KEY_MAX_LENGTH,
+        help_text="Give a template that has no key one, so code can take it over: the next upload under this key "
+        "updates this template and keeps its id, workflow and sender. Code sends that already use this key keep "
+        "their own workflow until that upload, then run through this template's workflow. Send it as the only field "
+        "of the PATCH. Letters, digits, hyphens (-) and underscores (_). Set once: a template that has a key keeps it.",
+    )
+    managed_by = serializers.ChoiceField(
+        choices=TemplateReleasedTo.choices,
+        required=False,
+        help_text="Send `gui` as the only field to stop managing a template in code, so it can be edited in PostHog. "
+        "It keeps its key, so the next upload under that key manages it in code again.",
+    )
+
+
 class DesignPatchSerializer(serializers.Serializer):
     operations = serializers.ListField(
         child=DesignOperationSerializer(),
@@ -983,10 +1013,32 @@ def get_fields(self) -> dict[str, serializers.Field]:
 )
 
 
+MANAGED_BY_CODE_RESPONSE = OpenApiResponse(
+    response=TemplateErrorSerializer,
+    description="The template is managed by code. `immutable`: change its file and upload it, or release it first",
+)
+TEMPLATE_UPDATE_SCHEMA = extend_schema(
+    parameters=[TEMPLATE_ID_PARAMETER], responses={200: MessageTemplateSerializer, 403: MANAGED_BY_CODE_RESPONSE}
+)
+TEMPLATE_PARTIAL_UPDATE_SCHEMA = extend_schema(
+    parameters=[TEMPLATE_ID_PARAMETER],
+    request=MessageTemplateUpdateSerializer,
+    responses={
+        200: MessageTemplateSerializer,
+        400: OpenApiResponse(
+            response=TemplateErrorSerializer,
+            description="A field is invalid. For `key`: `invalid_template_key`, `key_already_set`, `key_in_use`, or "
+            "`invalid_request` when it is sent with other fields",
+        ),
+        403: MANAGED_BY_CODE_RESPONSE,
+    },
+)
+
+
 @extend_schema_view(
     retrieve=extend_schema(parameters=[TEMPLATE_ID_PARAMETER]),
-    update=extend_schema(parameters=[TEMPLATE_ID_PARAMETER]),
-    partial_update=extend_schema(parameters=[TEMPLATE_ID_PARAMETER]),
+    update=TEMPLATE_UPDATE_SCHEMA,
+    partial_update=TEMPLATE_PARTIAL_UPDATE_SCHEMA,
     destroy=extend_schema(parameters=[TEMPLATE_ID_PARAMETER]),
 )
 class MessageTemplatesViewSet(
@@ -1033,6 +1085,25 @@ def dangerously_get_object(self) -> MessageTemplateRow:
         self.check_object_permissions(self.request, template)
         return template
 
+    def check_object_permissions(self, request: Request, obj: Any) -> None:
+        super().check_object_permissions(request, obj)
+        if request.method not in permissions.SAFE_METHODS:
+            check_template_write(obj, self._write_intent())
+
+    def _write_intent(self) -> TemplateWriteIntent:
+        payload = self.request.data
+        return TemplateWriteIntent(action=self.action, payload=payload if isinstance(payload, Mapping) else {})
+
+    def handle_exception(self, exc: Exception) -> Response:
+        if isinstance(exc, TemplateWriteRefused):
+            managed_by_code = isinstance(exc, TemplateManagedByCode)
+            refusal = TemplateRefusal(
+                code=exc.code, detail=exc.detail, attr=None if managed_by_code else "key", why=exc.why, fix=exc.fix
+            )
+            refused_status = status.HTTP_403_FORBIDDEN if managed_by_code else status.HTTP_400_BAD_REQUEST
+            return Response(TemplateErrorSerializer(refusal).data, status=refused_status)
+        return super().handle_exception(exc)
+
     def _with_creators(self, templates: Sequence[MessageTemplateRow]) -> list[SimpleNamespace]:
         creator_ids = {template.created_by_id for template in templates if template.created_by_id}
         creators = {user.id: user for user in User.objects.filter(id__in=creator_ids)} if creator_ids else {}
@@ -1072,6 +1143,18 @@ def create(self, request: Request, *args: Any, **kwargs: Any) -> Response:
     def update(self, request: Request, *args: Any, **kwargs: Any) -> Response:
         partial = kwargs.pop("partial", False)
         template = self.get_object()
+        intent = self._write_intent()
+        if is_release(intent):
+            released = release_template(
+                self.team_id, template.id, require_workflow_editor=self._require_workflow_editor
+            )
+            self._emit_resource_edited(released)
+            if template.managed_by == TemplateManagedBy.CODE:
+                self._report_user_action("message template released", {"template_id": str(released.id)})
+            return Response(self._serialize(released))
+        if is_adoption(intent):
+            return self._adopt(template, intent)
+        check_template_key_write(template, intent)
         serializer = self.get_serializer(self._with_creators([template])[0], data=request.data, partial=partial)
         serializer.is_valid(raise_exception=True)
         fields = serializer.validated_data
@@ -1080,6 +1163,7 @@ def update(self, request: Request, *args: Any, **kwargs: Any) -> Response:
                 self.team_id,
                 template.id,
                 fields["draft_content"],
+                intent=intent,
                 require_workflow_editor=self._require_workflow_editor,
             )
             self._emit_resource_edited(updated)
@@ -1097,6 +1181,7 @@ def update(self, request: Request, *args: Any, **kwargs: Any) -> Response:
                 self.team_id,
                 template.id,
                 fields,
+                intent=intent,
                 user_id=self._actor_id(),
                 require_workflow_editor=self._require_workflow_editor,
             )
@@ -1105,6 +1190,18 @@ def update(self, request: Request, *args: Any, **kwargs: Any) -> Response:
         self._emit_resource_edited(updated)
         return Response(self._serialize(updated))
 
+    def _adopt(self, template: MessageTemplateRow, intent: TemplateWriteIntent) -> Response:
+        key = intent.payload["key"]
+        refused = invalid_template_key(key)
+        if refused is not None:
+            return Response(TemplateErrorSerializer(refused).data, status=status.HTTP_400_BAD_REQUEST)
+        adopted = adopt_template(
+            self.team_id, template.id, key, intent=intent, require_workflow_editor=self._require_workflow_editor
+        )
+        self._emit_resource_edited(adopted)
+        self._report_user_action("message template adopted", {"template_id": str(adopted.id)})
+        return Response(self._serialize(adopted))
+
     def _report_user_action(self, event: str, properties: dict[str, Any]) -> None:
         try:
             report_user_action(
@@ -1139,7 +1236,9 @@ def _emit_resource_edited(self, instance: MessageTemplateRow) -> None:
             logger.warning("Failed to publish message template edited event", error=str(e))
 
     @extend_schema(
-        request=DesignPatchSerializer, responses={200: MessageTemplateSerializer}, parameters=[TEMPLATE_ID_PARAMETER]
+        request=DesignPatchSerializer,
+        responses={200: MessageTemplateSerializer, 403: MANAGED_BY_CODE_RESPONSE},
+        parameters=[TEMPLATE_ID_PARAMETER],
     )
     @action(detail=True, methods=["PATCH"])
     def design(self, request: Request, *args: Any, **kwargs: Any) -> Response:
@@ -1186,6 +1285,7 @@ def apply_operations(content: dict[str, Any]) -> dict[str, Any]:
                 self.team_id,
                 template.id,
                 apply_operations,
+                intent=self._write_intent(),
                 user_id=self._actor_id(),
                 require_workflow_editor=self._require_workflow_editor,
             )
diff --git a/products/messaging/backend/services/template_keys.py b/products/messaging/backend/services/template_keys.py
new file mode 100644
index 000000000000..256ea32bd832
--- /dev/null
+++ b/products/messaging/backend/services/template_keys.py
@@ -0,0 +1,75 @@
+from typing import Protocol
+from uuid import UUID
+
+from django.db import IntegrityError, transaction
+
+from products.messaging.backend.facade.contracts import TemplateKeyRefused, TemplateWriteIntent
+from products.messaging.backend.models import MessageTemplate
+from products.messaging.backend.models.message_template import KEY_CONSTRAINT
+from products.messaging.backend.services.template_ownership import check_write, patches_only
+from products.messaging.backend.services.template_saves import WorkflowEditorCheck, lock_template
+
+
+class KeyedTemplate(Protocol):
+    @property
+    def key(self) -> str | None: ...
+
+
+def is_adoption(intent: TemplateWriteIntent) -> bool:
+    return patches_only(intent, "key")
+
+
+def check_key_unchanged(template: KeyedTemplate, intent: TemplateWriteIntent) -> None:
+    if "key" not in intent.payload or intent.payload["key"] == template.key:
+        return
+    if template.key:
+        raise _key_already_set(template.key)
+    raise TemplateKeyRefused(
+        code="invalid_request",
+        detail="`key` can't be set together with other fields.",
+        why="A key prepares the template for uploads from code, so it is set in a request of its own.",
+        fix="Send a PATCH whose only field is `key`, then send the other changes.",
+    )
+
+
+def adopt_template(
+    team_id: int,
+    template_id: UUID,
+    key: str,
+    *,
+    intent: TemplateWriteIntent,
+    require_workflow_editor: WorkflowEditorCheck,
+) -> MessageTemplate:
+    try:
+        with transaction.atomic():
+            template = lock_template(team_id, template_id)
+            check_write(template, intent)
+            if template.transactional_hog_flow_id:
+                require_workflow_editor(template.transactional_hog_flow_id)
+            if template.key:
+                raise _key_already_set(template.key)
+            template.key = key
+            template.save(update_fields=["key", "updated_at"])
+    except IntegrityError as error:
+        if KEY_CONSTRAINT not in str(error):
+            raise
+        raise _key_in_use(key) from error
+    return template
+
+
+def _key_already_set(key: str) -> TemplateKeyRefused:
+    return TemplateKeyRefused(
+        code="key_already_set",
+        detail=f"This template already has the key `{key}`.",
+        why="Code names the template by its key, so a key never changes.",
+        fix=f"Use `{key}` in your code, or duplicate the template and give the copy a key.",
+    )
+
+
+def _key_in_use(key: str) -> TemplateKeyRefused:
+    return TemplateKeyRefused(
+        code="key_in_use",
+        detail=f"Another template in this project has the key `{key}`.",
+        why="A key names one template in a project.",
+        fix="Pick another key, or upload your file to the template that has this key.",
+    )
diff --git a/products/messaging/backend/services/template_ownership.py b/products/messaging/backend/services/template_ownership.py
new file mode 100644
index 000000000000..3b4571f983bd
--- /dev/null
+++ b/products/messaging/backend/services/template_ownership.py
@@ -0,0 +1,53 @@
+from typing import Final, Protocol
+
+from products.messaging.backend.facade.contracts import TemplateManagedBy, TemplateManagedByCode, TemplateWriteIntent
+
+CONTENT_NEUTRAL_ACTIONS: Final = frozenset({"upload", "send", "make_transactional"})
+OPERATIONAL_FIELDS: Final = ("sensitive", "tags")
+
+
+class OwnedTemplate(Protocol):
+    @property
+    def managed_by(self) -> str | None: ...
+
+    @property
+    def source_repository(self) -> str | None: ...
+
+    @property
+    def source_path(self) -> str | None: ...
+
+
+def patches_only(intent: TemplateWriteIntent, field: str) -> bool:
+    return intent.action == "partial_update" and set(intent.payload.keys()) == {field}
+
+
+def is_release(intent: TemplateWriteIntent) -> bool:
+    return patches_only(intent, "managed_by") and intent.payload["managed_by"] == TemplateManagedBy.GUI
+
+
+def check_write(template: OwnedTemplate, intent: TemplateWriteIntent) -> None:
+    if template.managed_by != TemplateManagedBy.CODE:
+        return
+    if (
+        intent.action in CONTENT_NEUTRAL_ACTIONS
+        or is_release(intent)
+        or any(patches_only(intent, f) for f in OPERATIONAL_FIELDS)
+    ):
+        return
+    raise TemplateManagedByCode(
+        detail="This template is managed by code, so it can't be changed in PostHog.",
+        why="Its content comes from a file in a repository. The next upload of that file replaces changes made here.",
+        fix=f"Change {_template_file(template)} and upload it again. To edit the template in PostHog instead, stop "
+        "managing it in code first: send a PATCH whose only field is `managed_by` set to `gui`.",
+    )
+
+
+def _template_file(template: OwnedTemplate) -> str:
+    path, repository = template.source_path, template.source_repository
+    if path and repository:
+        return f"`{path}` in `{repository}`"
+    if path:
+        return f"`{path}`"
+    if repository:
+        return f"the template's file in `{repository}`"
+    return "the template's file"
diff --git a/products/messaging/backend/services/template_saves.py b/products/messaging/backend/services/template_saves.py
index a9d7516fa8cf..03641c017ffd 100644
--- a/products/messaging/backend/services/template_saves.py
+++ b/products/messaging/backend/services/template_saves.py
@@ -4,8 +4,10 @@
 
 from django.db import transaction
 
+from products.messaging.backend.facade.contracts import TemplateManagedBy, TemplateWriteIntent
 from products.messaging.backend.models import MessageTemplate
 from products.messaging.backend.services.message_templates import record_content_hash
+from products.messaging.backend.services.template_ownership import check_write
 from products.messaging.backend.services.transactional_email import check_still_sendable, sync_transactional_workflow
 
 TemplateWrite = Callable[[MessageTemplate], None]
@@ -17,11 +19,13 @@ def save_template(
     template_id: UUID,
     write: TemplateWrite,
     *,
+    intent: TemplateWriteIntent,
     user_id: int | None,
     require_workflow_editor: WorkflowEditorCheck,
 ) -> MessageTemplate:
     with transaction.atomic():
         template = lock_template(team_id, template_id)
+        check_write(template, intent)
         save_locked_template(template, write, user_id=user_id, require_workflow_editor=require_workflow_editor)
     return template
 
@@ -31,10 +35,12 @@ def save_locked_draft(
     template_id: UUID,
     draft: dict[str, Any] | None,
     *,
+    intent: TemplateWriteIntent,
     require_workflow_editor: WorkflowEditorCheck,
 ) -> MessageTemplate:
     with transaction.atomic():
         template = lock_template(team_id, template_id)
+        check_write(template, intent)
         if template.transactional_hog_flow_id:
             require_workflow_editor(template.transactional_hog_flow_id)
         template.draft_content = draft
@@ -42,6 +48,19 @@ def save_locked_draft(
     return template
 
 
+def release_template(
+    team_id: int, template_id: UUID, *, require_workflow_editor: WorkflowEditorCheck
+) -> MessageTemplate:
+    with transaction.atomic():
+        template = lock_template(team_id, template_id)
+        if template.transactional_hog_flow_id:
+            require_workflow_editor(template.transactional_hog_flow_id)
+        if template.managed_by == TemplateManagedBy.CODE:
+            template.managed_by = TemplateManagedBy.GUI
+            template.save(update_fields=["managed_by", "updated_at"])
+    return template
+
+
 def lock_template(team_id: int, template_id: UUID) -> MessageTemplate:
     return MessageTemplate.objects.select_for_update().get(team_id=team_id, id=template_id, deleted=False)
 
diff --git a/products/messaging/backend/tests/api/test_code_managed_template_lock.py b/products/messaging/backend/tests/api/test_code_managed_template_lock.py
new file mode 100644
index 000000000000..783822b8d34a
--- /dev/null
+++ b/products/messaging/backend/tests/api/test_code_managed_template_lock.py
@@ -0,0 +1,209 @@
+from typing import Any
+
+from posthog.test.base import APIBaseTest
+from unittest.mock import MagicMock, patch
+
+from parameterized import parameterized
+from rest_framework import status
+from rest_framework.test import APIClient
+
+from posthog.models import ProjectSecretAPIKey
+from posthog.models.integration import Integration
+from posthog.models.personal_api_key import PersonalAPIKey, hash_key_value
+from posthog.models.utils import generate_random_token_personal, generate_random_token_secret
+
+from products.messaging.backend.models.message_template import MessageTemplate
+from products.messaging.backend.presentation.views.message_templates import MessageTemplatesViewSet
+from products.workflows.backend.facade.api import set_default_email_sender_if_unset
+
+WELCOME: dict[str, Any] = {
+    "name": "Welcome",
+    "subject": "Welcome, {{ variables.first_name }}",
+    "html": "<p>Hi {{ variables.first_name }}</p>",
+    "source": {"repository": "github.com/example/app", "path": "emails/welcome.html", "ref": "3f2c1ab"},
+}
+WELCOME_HASH = "v1:f74cd913f3aa2e5667a588f2865634e56693df77793ca594d18e9b5f89e3d2e6"
+EDITS: list[tuple[str, str, str, dict[str, Any]]] = [
+    (
+        "update",
+        "put",
+        "",
+        {"name": "Welcome", "content": {"email": {"subject": "Edited", "html": "<p>Edited</p>"}}, "type": "email"},
+    ),
+    ("partial_update", "patch", "", {"name": "Renamed in PostHog"}),
+    ("soft_delete", "patch", "", {"deleted": True}),
+    ("save_draft", "patch", "", {"draft_content": {"email": {"subject": "Edited", "html": "<p>Edited</p>"}}}),
+    ("release_with_an_edit", "patch", "", {"managed_by": "gui", "name": "Renamed in PostHog"}),
+    (
+        "design",
+        "patch",
+        "design/",
+        {"operations": [{"op": "update_body", "patch": {"values": {"backgroundColor": "#000000"}}}]},
+    ),
+]
+
+
+@patch("products.messaging.backend.presentation.views.message_templates.posthoganalytics.capture")
+@patch(
+    "products.messaging.backend.presentation.views.message_templates.posthoganalytics.feature_enabled",
+    return_value=True,
+)
+@patch("posthog.plugins.plugin_server_api.internal_requests.post")
+class TestCodeManagedTemplateLock(APIBaseTest):
+    def setUp(self):
+        super().setUp()
+        sender = Integration.objects.create(
+            team=self.team, kind="email", integration_id="hello@example.com", config={"verified": True}
+        )
+        set_default_email_sender_if_unset(self.team.id, sender.id)
+
+    def _upload(self, body: dict[str, Any], key: str = "welcome") -> dict[str, Any]:
+        response = self.client.put(
+            f"/api/projects/{self.team.id}/messaging_templates/by_key/{key}/", body, format="json"
+        )
+        assert response.status_code in (status.HTTP_200_OK, status.HTTP_201_CREATED), response.json()
+        return response.json()
+
+    def _url(self, template_id: str, suffix: str = "") -> str:
+        return f"/api/projects/{self.team.id}/messaging_templates/{template_id}/{suffix}"
+
+    def _template(self, template_id: str) -> dict[str, Any]:
+        return self.client.get(self._url(template_id)).json()
+
+    def _workflow_version(self, hog_flow_id: str) -> int:
+        return self.client.get(f"/api/projects/{self.team.id}/hog_flows/{hog_flow_id}").json()["version"]
+
+    def _rename(self, template_id: str, client: APIClient | None = None) -> Any:
+        return (client or self.client).patch(self._url(template_id), {"name": "Renamed in PostHog"}, format="json")
+
+    def _assert_refused(self, response: Any) -> dict[str, Any]:
+        assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
+        body = response.json()
+        assert body["code"] == "immutable"
+        assert body["docs_url"] == "https://posthog.com/docs/workflows/transactional-email-api#immutable"
+        assert body["detail"] and body["why"]
+        return body
+
+    @parameterized.expand(EDITS)
+    def test_refuses_an_edit_and_says_how_to_change_it_in_code(
+        self, _post, _flag, _capture, _name, method, suffix, body
+    ):
+        uploaded = self._upload(WELCOME)
+
+        response = getattr(self.client, method)(self._url(uploaded["id"], suffix), body, format="json")
+
+        refusal = self._assert_refused(response)
+        assert "`emails/welcome.html` in `github.com/example/app`" in refusal["fix"]
+        template = self._template(uploaded["id"])
+        assert (template["name"], template["deleted"], template["content_hash"], template["draft_content"]) == (
+            "Welcome",
+            False,
+            WELCOME_HASH,
+            None,
+        )
+        assert self._workflow_version(uploaded["transactional_hog_flow_id"]) == 1
+
+    def test_an_mcp_update_gets_the_same_refusal(self, _post, _flag, _capture):
+        uploaded = self._upload(WELCOME)
+        token = generate_random_token_personal()
+        PersonalAPIKey.objects.create(
+            label="MCP", user=self.user, secure_value=hash_key_value(token), scopes=["hog_flow:write"]
+        )
+        mcp = APIClient()
+        mcp.credentials(HTTP_AUTHORIZATION=f"Bearer {token}", HTTP_X_POSTHOG_CLIENT="mcp")
+
+        self._assert_refused(self._rename(uploaded["id"], mcp))
+
+    @parameterized.expand(
+        [
+            ("path_and_repository", WELCOME["source"], "`emails/welcome.html` in `github.com/example/app`"),
+            ("path_only", {"path": "emails/welcome.html"}, "`emails/welcome.html`"),
+            ("no_source", None, "the template's file"),
+        ]
+    )
+    def test_the_fix_names_the_file_as_far_as_the_template_records_it(
+        self, _post, _flag, _capture, _name, source, expected_file
+    ):
+        body = {key: value for key, value in WELCOME.items() if key != "source"}
+        uploaded = self._upload({**body, "source": source} if source else body, key=_name.replace("_", "-"))
+
+        refusal = self._assert_refused(self._rename(uploaded["id"]))
+
+        assert refusal["fix"].startswith(f"Change {expected_file} and upload it again.")
+
+    @patch("products.messaging.backend.services.transactional_email.reload_hog_flows_on_workers")
+    def test_a_code_managed_template_still_sends_takes_the_sensitive_setting_and_tags_and_stays_transactional(
+        self, _reload, post: MagicMock, _flag, _capture
+    ):
+        uploaded = self._upload(WELCOME)
+        post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
+        raw_token = generate_random_token_secret()
+        ProjectSecretAPIKey.objects.create(
+            team=self.team,
+            label="lock test",
+            secure_value=hash_key_value(raw_token),
+            scopes=["hog_flow:write"],
+            mask_value=f"{raw_token[:4]}...{raw_token[-4:]}",
+        )
+        psak = APIClient()
+        psak.credentials(HTTP_AUTHORIZATION=f"Bearer {raw_token}")
+
+        sent = psak.post(self._url(uploaded["id"], "send/"), {"to": "jane@example.com"}, format="json")
+        made_transactional = self.client.post(self._url(uploaded["id"], "make_transactional/"), {}, format="json")
+        protected = self.client.patch(self._url(uploaded["id"]), {"sensitive": True}, format="json")
+        tagged = self.client.patch(self._url(uploaded["id"]), {"tags": ["onboarding"]}, format="json")
+
+        assert protected.status_code == status.HTTP_200_OK, protected.json()
+        workflow = self.client.get(f"/api/projects/{self.team.id}/hog_flows/{uploaded['transactional_hog_flow_id']}")
+        assert [action["config"].get("sensitive") for action in workflow.json()["actions"]] == [None, True, None]
+        assert tagged.status_code == status.HTTP_200_OK, tagged.json()
+        assert self._template(uploaded["id"])["tags"] == ["onboarding"]
+        assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
+        assert made_transactional.status_code == status.HTTP_200_OK, made_transactional.json()
+        assert made_transactional.json()["transactional_hog_flow_id"] == uploaded["transactional_hog_flow_id"]
+
+    def test_a_release_hands_the_template_to_posthog_until_the_next_upload(self, _post, _flag, _capture):
+        uploaded = self._upload(WELCOME)
+
+        with patch("products.messaging.backend.presentation.views.message_templates.report_user_action") as report:
+            released = self.client.patch(self._url(uploaded["id"]), {"managed_by": "gui"}, format="json")
+        renamed = self._rename(uploaded["id"])
+        claimed = self._upload(WELCOME)
+        refused = self.client.patch(self._url(uploaded["id"]), {"name": "Renamed again"}, format="json")
+
+        assert released.status_code == status.HTTP_200_OK, released.json()
+        assert (released.json()["managed_by"], released.json()["key"]) == ("gui", "welcome")
+        assert [(c.args[1], c.args[2]["template_id"]) for c in report.call_args_list] == [
+            ("message template released", uploaded["id"])
+        ]
+        assert renamed.status_code == status.HTTP_200_OK, renamed.json()
+        assert renamed.json()["name"] == "Renamed in PostHog"
+        assert (claimed["id"], claimed["result"], claimed["managed_by"]) == (uploaded["id"], "updated", "code")
+        self._assert_refused(refused)
+        assert self._template(uploaded["id"])["name"] == "Welcome"
+
+    @parameterized.expand(
+        [
+            ("rename", {"name": "Renamed in PostHog"}),
+            ("save_draft", {"draft_content": {"email": {"subject": "Edited", "html": "<p>Edited</p>"}}}),
+        ]
+    )
+    def test_an_upload_that_claims_the_template_mid_request_still_refuses_the_edit(
+        self, _post, _flag, _capture, _name, edit
+    ):
+        uploaded = self._upload(WELCOME)
+        released = self.client.patch(self._url(uploaded["id"]), {"managed_by": "gui"}, format="json")
+        assert released.status_code == status.HTTP_200_OK, released.json()
+        original = MessageTemplatesViewSet.dangerously_get_object
+
+        def read_then_upload_claims(viewset: MessageTemplatesViewSet) -> Any:
+            template = original(viewset)
+            MessageTemplate.objects.filter(id=template.id).update(managed_by="code")
+            return template
+
+        with patch.object(MessageTemplatesViewSet, "dangerously_get_object", read_then_upload_claims):
+            response = self.client.patch(self._url(uploaded["id"]), edit, format="json")
+
+        self._assert_refused(response)
+        template = self._template(uploaded["id"])
+        assert (template["name"], template["draft_content"]) == ("Welcome", None)
diff --git a/products/messaging/backend/tests/api/test_template_adoption.py b/products/messaging/backend/tests/api/test_template_adoption.py
new file mode 100644
index 000000000000..ce9a8b5f41db
--- /dev/null
+++ b/products/messaging/backend/tests/api/test_template_adoption.py
@@ -0,0 +1,119 @@
+from typing import Any
+
+from posthog.test.base import APIBaseTest
+
+from parameterized import parameterized
+from rest_framework import status
+from rest_framework.test import APIClient
+
+from posthog.models import ProjectSecretAPIKey
+from posthog.models.personal_api_key import PersonalAPIKey, hash_key_value
+from posthog.models.utils import generate_random_token_personal, generate_random_token_secret
+
+from products.messaging.backend.models.message_template import MessageTemplate
+
+DOCS_URL = "https://posthog.com/docs/workflows/transactional-email-api"
+
+
+class TestTemplateAdoption(APIBaseTest):
+    def setUp(self):
+        super().setUp()
+        self.template = self._template_made_in_posthog("Welcome")
+
+    def _template_made_in_posthog(self, name: str, key: str | None = None) -> MessageTemplate:
+        return MessageTemplate.objects.create(
+            team=self.team,
+            name=name,
+            key=key,
+            content={"email": {"subject": "Hello", "html": "<p>Hello</p>"}},
+            type="email",
+        )
+
+    def _url(self, template: MessageTemplate) -> str:
+        return f"/api/projects/{self.team.id}/messaging_templates/{template.id}/"
+
+    def _adopt(self, key: Any, client: APIClient | None = None) -> Any:
+        return (client or self.client).patch(self._url(self.template), {"key": key}, format="json")
+
+    def _stored_key(self) -> str | None:
+        return self.client.get(self._url(self.template)).json()["key"]
+
+    def _personal_api_key_client(self) -> APIClient:
+        token = generate_random_token_personal()
+        PersonalAPIKey.objects.create(
+            label="MCP", user=self.user, secure_value=hash_key_value(token), scopes=["hog_flow:write"]
+        )
+        client = APIClient()
+        client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}", HTTP_X_POSTHOG_CLIENT="mcp")
+        return client
+
+    def _project_secret_api_key_client(self) -> APIClient:
+        token = generate_random_token_secret()
+        ProjectSecretAPIKey.objects.create(
+            team=self.team,
+            label="adoption",
+            secure_value=hash_key_value(token),
+            scopes=["hog_flow:write"],
+            mask_value=f"{token[:4]}...{token[-4:]}",
+        )
+        client = APIClient()
+        client.credentials(HTTP_AUTHORIZATION=f"Bearer {token}")
+        return client
+
+    @parameterized.expand([("session", None), ("personal_api_key", "_personal_api_key_client")])
+    def test_gives_a_template_without_a_key_its_key_and_keeps_its_content(self, _name, client_factory):
+        client = getattr(self, client_factory)() if client_factory else None
+
+        response = self._adopt("welcome", client)
+
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        adopted = response.json()
+        assert (adopted["id"], adopted["key"], adopted["managed_by"]) == (str(self.template.id), "welcome", None)
+        assert adopted["content"]["email"]["subject"] == "Hello"
+        assert self._stored_key() == "welcome"
+
+    def test_a_project_secret_api_key_cannot_adopt(self):
+        response = self._adopt("welcome", self._project_secret_api_key_client())
+
+        assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
+        assert self._stored_key() is None
+
+    @parameterized.expand(
+        [
+            ("twice", "welcome", {"key": "welcome"}, "key_already_set", "welcome"),
+            ("taken_key", None, {"key": "taken"}, "key_in_use", None),
+            ("invalid_key", None, {"key": "wel come"}, "invalid_template_key", None),
+            ("trailing_newline", None, {"key": "welcome\n"}, "invalid_template_key", None),
+            ("null_key", None, {"key": None}, "invalid_template_key", None),
+            ("key_with_other_fields", None, {"key": "welcome", "name": "Renamed"}, "invalid_request", None),
+            (
+                "changed_key_with_other_fields",
+                "welcome",
+                {"key": "other", "name": "Renamed"},
+                "key_already_set",
+                "welcome",
+            ),
+        ]
+    )
+    def test_refuses_a_key_it_cannot_set_and_says_how_to_fix_it(self, _name, adopted_key, body, code, stored_key):
+        self._template_made_in_posthog("Taken", key="taken")
+        if adopted_key:
+            assert self._adopt(adopted_key).status_code == status.HTTP_200_OK
+
+        response = self.client.patch(self._url(self.template), body, format="json")
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        refusal = response.json()
+        assert (refusal["code"], refusal["attr"], refusal["docs_url"]) == (code, "key", f"{DOCS_URL}#{code}")
+        assert refusal["detail"] and refusal["why"] and refusal["fix"]
+        template = self.client.get(self._url(self.template)).json()
+        assert (template["key"], template["name"]) == (stored_key, "Welcome")
+
+    def test_a_form_save_that_sends_the_stored_key_back_keeps_working(self):
+        assert self._adopt("welcome").status_code == status.HTTP_200_OK
+        form = self.client.get(self._url(self.template)).json()
+
+        response = self.client.patch(self._url(self.template), {**form, "name": "Renamed"}, format="json")
+
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        assert (response.json()["name"], response.json()["key"]) == ("Renamed", "welcome")
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index fff1fc79e2e7..17636656c8f9 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -21,6 +21,7 @@
     TransactionalEmailBurstThrottle,
 )
 from products.messaging.backend.services import template_uploads
+from products.messaging.backend.services.transactional_email import make_transactional
 from products.workflows.backend.facade.api import set_default_email_sender_if_unset
 
 WELCOME: dict[str, Any] = {
@@ -182,6 +183,88 @@ def test_a_changed_upload_is_what_the_next_send_delivers(self, _reload, post: Ma
         )
         assert self._workflow(hog_flow_id)["version"] == 2
 
+    def test_an_upload_claims_an_adopted_template_and_keeps_its_id_sender_and_paused_workflow(
+        self, _post, _flag, _capture
+    ):
+        other_sender = self._verified_sender("team@example.com")
+        made_in_posthog = MessageTemplate.objects.create(
+            team=self.team,
+            name="Welcome",
+            content={
+                "email": {
+                    "subject": "Hello",
+                    "html": "<p>Hello</p>",
+                    "from": {"email": "hello@example.com", "name": "Example team"},
+                    "replyTo": "replies@example.com",
+                }
+            },
+            draft_content={"email": {"subject": "Hello draft", "html": "<p>Hello draft</p>"}},
+            type="email",
+        )
+        hog_flow_id = make_transactional(
+            self.team.id, made_in_posthog.id, user_id=self.user.id, from_integration_id=other_sender.id
+        )
+        paused = self.client.patch(f"/api/projects/{self.team.id}/hog_flows/{hog_flow_id}", {"status": "archived"})
+        assert paused.status_code == status.HTTP_200_OK, paused.json()
+
+        adopted = self.client.patch(
+            f"/api/projects/{self.team.id}/messaging_templates/{made_in_posthog.id}/", {"key": "welcome"}, format="json"
+        )
+        response = self.psak.put(self.url, WELCOME, format="json")
+
+        assert adopted.status_code == status.HTTP_200_OK, adopted.json()
+        assert (adopted.json()["key"], adopted.json()["managed_by"]) == ("welcome", None)
+        assert response.status_code == status.HTTP_200_OK, response.json()
+        assert (response.json()["result"], response.json()["id"]) == ("updated", str(made_in_posthog.id))
+        assert response.json()["managed_by"] == "code"
+        assert response.json()["transactional_hog_flow_id"] == str(hog_flow_id)
+        workflow = self._workflow(str(hog_flow_id))
+        assert workflow["status"] == "archived"
+        email = self._sent_email(str(hog_flow_id))
+        assert (email["subject"], email["from"], email["replyTo"]) == (
+            WELCOME["subject"],
+            {"integrationId": other_sender.id, "email": "hello@example.com", "name": "Example team"},
+            "replies@example.com",
+        )
+        made_in_posthog.refresh_from_db()
+        assert made_in_posthog.draft_content is None
+
+    def _code_send_workflow_id(self, post: MagicMock) -> str:
+        sent = self.psak.post(
+            f"/api/projects/{self.team.id}/messaging/send/email/",
+            {"to": "user@example.com", "template_key": "welcome", "subject": "Hi", "html": "<p>Hi</p>"},
+            format="json",
+        )
+        assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
+        return post.call_args.args[0].split("/hog_flows/")[1].split("/")[0]
+
+    @patch("products.messaging.backend.services.transactional_email.reload_hog_flows_on_workers")
+    def test_code_sends_under_a_key_move_to_its_template_only_once_an_upload_claims_it(
+        self, _reload, post: MagicMock, _flag, _capture
+    ):
+        post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
+        made_in_posthog = MessageTemplate.objects.create(
+            team=self.team,
+            name="Welcome",
+            content={"email": {"subject": "Hello", "html": "<p>Hello</p>"}},
+            type="email",
+        )
+        template_url = f"/api/projects/{self.team.id}/messaging_templates/{made_in_posthog.id}/"
+
+        before_adoption = self._code_send_workflow_id(post)
+        adopted = self.client.patch(template_url, {"key": "welcome"}, format="json")
+        after_adoption = self._code_send_workflow_id(post)
+        uploaded = self._upload(WELCOME)
+        after_upload = self._code_send_workflow_id(post)
+        released = self.client.patch(template_url, {"managed_by": "gui"}, format="json")
+        after_release = self._code_send_workflow_id(post)
+
+        assert adopted.status_code == status.HTTP_200_OK, adopted.json()
+        assert released.status_code == status.HTTP_200_OK, released.json()
+        template_workflow = uploaded["transactional_hog_flow_id"]
+        assert template_workflow != before_adoption
+        assert [after_adoption, after_upload, after_release] == [before_adoption, template_workflow, template_workflow]
+
     def _adopted_template_sending_from(self, sender: Integration) -> MessageTemplate:
         return MessageTemplate.objects.create(
             team=self.team,
@@ -364,6 +447,10 @@ def misses_the_winner_once(team_id: int, key: str) -> MessageTemplate | None:
 
     def test_a_publish_moves_the_replaced_hash_to_the_superseded_list(self, _post, _flag, _capture):
         first = self._upload(WELCOME)
+        released = self.client.patch(
+            f"/api/projects/{self.team.id}/messaging_templates/{first['id']}/", {"managed_by": "gui"}, format="json"
+        )
+        assert released.status_code == status.HTTP_200_OK, released.json()
 
         edited = self.client.patch(
             f"/api/projects/{self.team.id}/messaging_templates/{first['id']}/",
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index 91c5e4e810db..85181fbe2cbf 100644
--- a/products/messaging/frontend/generated/api.schemas.ts
+++ b/products/messaging/frontend/generated/api.schemas.ts
@@ -810,11 +810,11 @@ export interface MessageTemplateApi {
     /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
     draft_content?: MessageTemplateContentApi | null
     /**
-     * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
+     * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload or by a PATCH whose only field is `key`.
      * @nullable
      */
     readonly key: string | null
-    /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+    /** Who owns the content. `code` when it was uploaded from a repository: PostHog then refuses edits, and the template changes through its next upload. To edit it in PostHog, send a PATCH whose only field is `managed_by` set to `gui`. `gui` or null when it is edited in PostHog.
      *
      * * `gui` - GUI
      * * `code` - Code */
@@ -850,7 +850,36 @@ export interface PaginatedMessageTemplateListApi {
     results: MessageTemplateApi[]
 }
 
-export interface PatchedMessageTemplateApi {
+export interface TemplateErrorApi {
+    /** Error class, such as `invalid_request`. */
+    type: string
+    /** Stable error code to branch on, such as `invalid_template_key`. */
+    code: string
+    /** What went wrong. */
+    detail: string
+    /**
+     * The request field the error is about, if any.
+     * @nullable
+     */
+    attr: string | null
+    /** Why PostHog refuses the request. */
+    why?: string
+    /** What to change before you retry. */
+    fix?: string
+    /** Documentation for this error code. */
+    docs_url?: string
+}
+
+/**
+ * * `gui` - GUI
+ */
+export type TemplateReleasedToEnumApi = (typeof TemplateReleasedToEnumApi)[keyof typeof TemplateReleasedToEnumApi]
+
+export const TemplateReleasedToEnumApi = {
+    Gui: 'gui',
+} as const
+
+export interface PatchedMessageTemplateUpdateApi {
     readonly id?: string
     /**
      * Human-readable template name shown in the library.
@@ -892,15 +921,14 @@ export interface PatchedMessageTemplateApi {
     /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
     draft_content?: MessageTemplateContentApi | null
     /**
-     * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
-     * @nullable
+     * Give a template that has no key one, so code can take it over: the next upload under this key updates this template and keeps its id, workflow and sender. Code sends that already use this key keep their own workflow until that upload, then run through this template's workflow. Send it as the only field of the PATCH. Letters, digits, hyphens (-) and underscores (_). Set once: a template that has a key keeps it.
+     * @maxLength 400
      */
-    readonly key?: string | null
-    /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+    key?: string
+    /** Send `gui` as the only field to stop managing a template in code, so it can be edited in PostHog. It keeps its key, so the next upload under that key manages it in code again.
      *
-     * * `gui` - GUI
-     * * `code` - Code */
-    readonly managed_by?: TemplateManagedByEnumApi | null
+     * * `gui` - GUI */
+    managed_by?: TemplateReleasedToEnumApi
     /**
      * Repository the template was last uploaded from, such as `github.com/example/app`.
      * @nullable
@@ -1087,26 +1115,6 @@ export interface UploadTemplateResponseApi {
     source: TemplateSourceApi
 }
 
-export interface TemplateErrorApi {
-    /** Error class, such as `invalid_request`. */
-    type: string
-    /** Stable error code to branch on, such as `invalid_template_key`. */
-    code: string
-    /** What went wrong. */
-    detail: string
-    /**
-     * The request field the error is about, if any.
-     * @nullable
-     */
-    attr: string | null
-    /** Why PostHog refuses the request. */
-    why?: string
-    /** What to change before you retry. */
-    fix?: string
-    /** Documentation for this error code. */
-    docs_url?: string
-}
-
 export type MessagingCategoriesListParams = {
     /**
      * Number of results to return per page.
diff --git a/products/messaging/frontend/generated/api.ts b/products/messaging/frontend/generated/api.ts
index 95621f803b8b..041612f8d153 100644
--- a/products/messaging/frontend/generated/api.ts
+++ b/products/messaging/frontend/generated/api.ts
@@ -32,7 +32,7 @@ import type {
     PaginatedOptOutsApi,
     PatchedDesignPatchApi,
     PatchedMessageCategoryApi,
-    PatchedMessageTemplateApi,
+    PatchedMessageTemplateUpdateApi,
     PatchedSupabaseAuthEmailSettingsUpdateApi,
     PreferencesLinkApi,
     ProviderImportRunApi,
@@ -889,14 +889,14 @@ export const getMessagingTemplatesPartialUpdateUrl = (projectId: string, id: str
 export const messagingTemplatesPartialUpdate = async (
     projectId: string,
     id: string,
-    patchedMessageTemplateApi?: NonReadonly<PatchedMessageTemplateApi>,
+    patchedMessageTemplateUpdateApi?: NonReadonly<PatchedMessageTemplateUpdateApi>,
     options?: RequestInit
 ): Promise<MessageTemplateApi> => {
     return apiMutator<MessageTemplateApi>(getMessagingTemplatesPartialUpdateUrl(projectId, id), {
         ...options,
         method: 'PATCH',
         headers: { 'Content-Type': 'application/json', ...options?.headers },
-        body: JSON.stringify(patchedMessageTemplateApi),
+        body: JSON.stringify(patchedMessageTemplateUpdateApi),
     })
 }
 
diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.ts
index 035e47924c17..fb381da48dfb 100644
--- a/products/messaging/frontend/generated/api.zod.ts
+++ b/products/messaging/frontend/generated/api.zod.ts
@@ -1054,6 +1054,8 @@ export const messagingTemplatesPartialUpdateBodyTypeMax = 24
 export const messagingTemplatesPartialUpdateBodyDraftContentOneTemplatingDefault = `liquid`
 export const messagingTemplatesPartialUpdateBodyDraftContentOneEmailOneFromOneEmailMax = 254
 
+export const messagingTemplatesPartialUpdateBodyKeyMax = 400
+
 export const MessagingTemplatesPartialUpdateBody = /* @__PURE__ */ zod.object({
     name: zod
         .string()
@@ -1295,6 +1297,20 @@ export const MessagingTemplatesPartialUpdateBody = /* @__PURE__ */ zod.object({
         .describe(
             "Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft."
         ),
+    key: zod
+        .string()
+        .max(messagingTemplatesPartialUpdateBodyKeyMax)
+        .optional()
+        .describe(
+            "Give a template that has no key one, so code can take it over: the next upload under this key updates this template and keeps its id, workflow and sender. Code sends that already use this key keep their own workflow until that upload, then run through this template's workflow. Send it as the only field of the PATCH. Letters, digits, hyphens (-) and underscores (_). Set once: a template that has a key keeps it."
+        ),
+    managed_by: zod
+        .enum(['gui'])
+        .describe('\* `gui` - GUI')
+        .optional()
+        .describe(
+            'Send `gui` as the only field to stop managing a template in code, so it can be edited in PostHog. It keeps its key, so the next upload under that key manages it in code again.\n\n\* `gui` - GUI'
+        ),
 })
 
 export const MessagingTemplatesDesignPartialUpdateBody = /* @__PURE__ */ zod.object({
diff --git a/products/workflows/mcp/email_templates.yaml b/products/workflows/mcp/email_templates.yaml
index f9f67c862a28..a6a82e4318b1 100644
--- a/products/workflows/mcp/email_templates.yaml
+++ b/products/workflows/mcp/email_templates.yaml
@@ -159,7 +159,8 @@ tools:
             changes; ids and Unlayer numbering for added blocks are assigned for you. Operations apply atomically — the
             design is read, the ops applied in order, the result validated and re-rendered to HTML, and saved only if
             valid, otherwise nothing changes. After patching, call workflows-show-email-template so the user sees the
-            result.
+            result. A template whose managed_by is code refuses this with 403 immutable: change its file in the
+            repository and upload it with workflows-upload-email-template instead.
         response:
             exclude:
                 - content
@@ -228,10 +229,16 @@ tools:
             workflows-get-email-template first (the design may carry fresh human edits from the visual editor) and send
             back the complete content.email with your edited design. The server re-renders the sent email from the
             design on save. After updating, call workflows-show-email-template so the user sees the result, and share
-            the returned _posthogUrl edit link.
+            the returned _posthogUrl edit link. A template whose managed_by is code refuses every update with 403
+            immutable: change its file in the repository and upload it with workflows-upload-email-template instead.
+            To move a template made in PostHog into code, send key (such as welcome) as the only field. A key is set
+            once and never changes. The next workflows-upload-email-template with that key updates this template and
+            keeps its id, workflow and sender. Emails your code already sends under that key with workflows-send-email
+            keep their own workflow until that upload, then run through this template's workflow.
         exclude_params:
             - content.email.html
             - draft_content
+            - managed_by
         response:
             exclude:
                 - content
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 97693ceef442..29cda664aa7d 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -17116,7 +17116,7 @@
         }
     },
     "workflows-patch-email-template": {
-        "description": "Surgically edit an email template's design by sending a small, ordered list of operations instead of resending the whole design JSON. Prefer this over workflows-update-email-template for any change to an existing design. Reference blocks by their id (call workflows-get-email-template first to read the current design and its ids). For the common case — tweak one block — use update_content with a deep-merge patch (e.g. {op: update_content, id: '<block-id>', patch: {values: {text: '<p>New copy</p>'}}}); a null leaf deletes that key. Use add_content / remove_content / move_content / add_row / remove_row for structural changes; ids and Unlayer numbering for added blocks are assigned for you. Operations apply atomically — the design is read, the ops applied in order, the result validated and re-rendered to HTML, and saved only if valid, otherwise nothing changes. After patching, call workflows-show-email-template so the user sees the result.",
+        "description": "Surgically edit an email template's design by sending a small, ordered list of operations instead of resending the whole design JSON. Prefer this over workflows-update-email-template for any change to an existing design. Reference blocks by their id (call workflows-get-email-template first to read the current design and its ids). For the common case — tweak one block — use update_content with a deep-merge patch (e.g. {op: update_content, id: '<block-id>', patch: {values: {text: '<p>New copy</p>'}}}); a null leaf deletes that key. Use add_content / remove_content / move_content / add_row / remove_row for structural changes; ids and Unlayer numbering for added blocks are assigned for you. Operations apply atomically — the design is read, the ops applied in order, the result validated and re-rendered to HTML, and saved only if valid, otherwise nothing changes. After patching, call workflows-show-email-template so the user sees the result. A template whose managed_by is code refuses this with 403 immutable: change its file in the repository and upload it with workflows-upload-email-template instead.",
         "category": "Workflows",
         "feature": "workflows",
         "summary": "Patch email template design",
@@ -17331,7 +17331,7 @@
         }
     },
     "workflows-update-email-template": {
-        "description": "Replace an email template's content as a whole. For small edits to an existing design (change a heading, a button color, one paragraph), prefer workflows-patch-email-template — it sends just the changed fields instead of the entire design JSON. Use this tool to set content from scratch or replace it wholesale: call workflows-get-email-template first (the design may carry fresh human edits from the visual editor) and send back the complete content.email with your edited design. The server re-renders the sent email from the design on save. After updating, call workflows-show-email-template so the user sees the result, and share the returned _posthogUrl edit link.",
+        "description": "Replace an email template's content as a whole. For small edits to an existing design (change a heading, a button color, one paragraph), prefer workflows-patch-email-template — it sends just the changed fields instead of the entire design JSON. Use this tool to set content from scratch or replace it wholesale: call workflows-get-email-template first (the design may carry fresh human edits from the visual editor) and send back the complete content.email with your edited design. The server re-renders the sent email from the design on save. After updating, call workflows-show-email-template so the user sees the result, and share the returned _posthogUrl edit link. A template whose managed_by is code refuses every update with 403 immutable: change its file in the repository and upload it with workflows-upload-email-template instead. To move a template made in PostHog into code, send key (such as welcome) as the only field. A key is set once and never changes. The next workflows-upload-email-template with that key updates this template and keeps its id, workflow and sender. Emails your code already sends under that key with workflows-send-email keep their own workflow until that upload, then run through this template's workflow.",
         "category": "Workflows",
         "feature": "workflows",
         "summary": "Update email template",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index ba67e6f8528a..38069b6b34be 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -17935,7 +17935,7 @@
         }
     },
     "workflows-patch-email-template": {
-        "description": "Surgically edit an email template's design by sending a small, ordered list of operations instead of resending the whole design JSON. Prefer this over workflows-update-email-template for any change to an existing design. Reference blocks by their id (call workflows-get-email-template first to read the current design and its ids). For the common case — tweak one block — use update_content with a deep-merge patch (e.g. {op: update_content, id: '<block-id>', patch: {values: {text: '<p>New copy</p>'}}}); a null leaf deletes that key. Use add_content / remove_content / move_content / add_row / remove_row for structural changes; ids and Unlayer numbering for added blocks are assigned for you. Operations apply atomically — the design is read, the ops applied in order, the result validated and re-rendered to HTML, and saved only if valid, otherwise nothing changes. After patching, call workflows-show-email-template so the user sees the result.",
+        "description": "Surgically edit an email template's design by sending a small, ordered list of operations instead of resending the whole design JSON. Prefer this over workflows-update-email-template for any change to an existing design. Reference blocks by their id (call workflows-get-email-template first to read the current design and its ids). For the common case — tweak one block — use update_content with a deep-merge patch (e.g. {op: update_content, id: '<block-id>', patch: {values: {text: '<p>New copy</p>'}}}); a null leaf deletes that key. Use add_content / remove_content / move_content / add_row / remove_row for structural changes; ids and Unlayer numbering for added blocks are assigned for you. Operations apply atomically — the design is read, the ops applied in order, the result validated and re-rendered to HTML, and saved only if valid, otherwise nothing changes. After patching, call workflows-show-email-template so the user sees the result. A template whose managed_by is code refuses this with 403 immutable: change its file in the repository and upload it with workflows-upload-email-template instead.",
         "category": "Workflows",
         "feature": "workflows",
         "summary": "Patch email template design",
@@ -18178,7 +18178,7 @@
         }
     },
     "workflows-update-email-template": {
-        "description": "Replace an email template's content as a whole. For small edits to an existing design (change a heading, a button color, one paragraph), prefer workflows-patch-email-template — it sends just the changed fields instead of the entire design JSON. Use this tool to set content from scratch or replace it wholesale: call workflows-get-email-template first (the design may carry fresh human edits from the visual editor) and send back the complete content.email with your edited design. The server re-renders the sent email from the design on save. After updating, call workflows-show-email-template so the user sees the result, and share the returned _posthogUrl edit link.",
+        "description": "Replace an email template's content as a whole. For small edits to an existing design (change a heading, a button color, one paragraph), prefer workflows-patch-email-template — it sends just the changed fields instead of the entire design JSON. Use this tool to set content from scratch or replace it wholesale: call workflows-get-email-template first (the design may carry fresh human edits from the visual editor) and send back the complete content.email with your edited design. The server re-renders the sent email from the design on save. After updating, call workflows-show-email-template so the user sees the result, and share the returned _posthogUrl edit link. A template whose managed_by is code refuses every update with 403 immutable: change its file in the repository and upload it with workflows-upload-email-template instead. To move a template made in PostHog into code, send key (such as welcome) as the only field. A key is set once and never changes. The next workflows-upload-email-template with that key updates this template and keeps its id, workflow and sender. Emails your code already sends under that key with workflows-send-email keep their own workflow until that upload, then run through this template's workflow.",
         "category": "Workflows",
         "feature": "workflows",
         "summary": "Update email template",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 70c85f265f0e..396391c2c738 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -72979,11 +72979,11 @@ export namespace Schemas {
       /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
       draft_content?: MessageTemplateContent | null;
       /**
-         * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
+         * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload or by a PATCH whose only field is `key`.
          * @nullable
          */
       readonly key: string | null;
-      /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+      /** Who owns the content. `code` when it was uploaded from a repository: PostHog then refuses edits, and the template changes through its next upload. To edit it in PostHog, send a PATCH whose only field is `managed_by` set to `gui`. `gui` or null when it is edited in PostHog.
        *
        * * `gui` - GUI
        * * `code` - Code */
@@ -90461,7 +90461,17 @@ export namespace Schemas {
       deleted?: boolean;
     }
 
-    export interface PatchedMessageTemplate {
+    /**
+     * * `gui` - GUI
+     */
+    export type TemplateReleasedToEnum = typeof TemplateReleasedToEnum[keyof typeof TemplateReleasedToEnum];
+
+
+    export const TemplateReleasedToEnum = {
+      Gui: 'gui',
+    } as const;
+
+    export interface PatchedMessageTemplateUpdate {
       readonly id?: string;
       /**
          * Human-readable template name shown in the library.
@@ -90503,15 +90513,14 @@ export namespace Schemas {
       /** Unpublished edits to a transactional template's content. Sends keep using `content`. Saving `content` publishes it and clears the draft. Set null to discard the draft. */
       draft_content?: MessageTemplateContent | null;
       /**
-         * Stable identifier code uses to upload and send this template, unique within the project. Null for templates that have no key. Set once, by the first upload.
-         * @nullable
+         * Give a template that has no key one, so code can take it over: the next upload under this key updates this template and keeps its id, workflow and sender. Code sends that already use this key keep their own workflow until that upload, then run through this template's workflow. Send it as the only field of the PATCH. Letters, digits, hyphens (-) and underscores (_). Set once: a template that has a key keeps it.
+         * @maxLength 400
          */
-      readonly key?: string | null;
-      /** Who owns the content. `code` when it was uploaded from a repository, and the template changes through its next upload. `gui` or null when it is edited in PostHog.
+      key?: string;
+      /** Send `gui` as the only field to stop managing a template in code, so it can be edited in PostHog. It keeps its key, so the next upload under that key manages it in code again.
        *
-       * * `gui` - GUI
-       * * `code` - Code */
-      readonly managed_by?: TemplateManagedByEnum | null;
+       * * `gui` - GUI */
+      managed_by?: TemplateReleasedToEnum;
       /**
          * Repository the template was last uploaded from, such as `github.com/example/app`.
          * @nullable
diff --git a/services/mcp/src/generated/email_templates/api.ts b/services/mcp/src/generated/email_templates/api.ts
index c9c0288b7844..055c10fd8f33 100644
--- a/services/mcp/src/generated/email_templates/api.ts
+++ b/services/mcp/src/generated/email_templates/api.ts
@@ -267,6 +267,8 @@ export const messagingTemplatesPartialUpdateBodyContentOneEmailOneFromOneEmailMa
 
 export const messagingTemplatesPartialUpdateBodyTypeMax = 24
 
+export const messagingTemplatesPartialUpdateBodyKeyMax = 400
+
 export const MessagingTemplatesPartialUpdateBody = () => zod.object({
     name: zod
         .string()
@@ -394,6 +396,13 @@ export const MessagingTemplatesPartialUpdateBody = () => zod.object({
         .describe(
             "For emails that carry login codes, reset links or other secrets. PostHog keeps no copy of each sent email's body or filled-in subject, and clicked links keep only the site address. Can change at any time."
         ),
+    key: zod
+        .string()
+        .max(messagingTemplatesPartialUpdateBodyKeyMax)
+        .optional()
+        .describe(
+            "Give a template that has no key one, so code can take it over: the next upload under this key updates this template and keeps its id, workflow and sender. Code sends that already use this key keep their own workflow until that upload, then run through this template's workflow. Send it as the only field of the PATCH. Letters, digits, hyphens (-) and underscores (_). Set once: a template that has a key keeps it."
+        ),
 })
 
 export const MessagingTemplatesDesignPartialUpdateParams = () => zod.object({
diff --git a/services/mcp/src/tools/generated/email_templates.ts b/services/mcp/src/tools/generated/email_templates.ts
index fc5aac13015e..8271677df731 100644
--- a/services/mcp/src/tools/generated/email_templates.ts
+++ b/services/mcp/src/tools/generated/email_templates.ts
@@ -399,6 +399,9 @@ const workflowsUpdateEmailTemplate = (): ToolBase<
         if (params.sensitive !== undefined) {
             body['sensitive'] = params.sensitive
         }
+        if (params.key !== undefined) {
+            body['key'] = params.key
+        }
         const result = await context.api.request<Schemas.MessageTemplate>({
             method: 'PATCH',
             path: `/api/projects/${encodeURIComponent(String(projectId))}/messaging_templates/${encodeURIComponent(String(params.id))}/`,
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-update-email-template.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-update-email-template.json
index aa998c3d50e8..5a9b550bade2 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-update-email-template.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-update-email-template.json
@@ -132,6 +132,11 @@
             "description": "A UUID string identifying this message template.",
             "type": "string"
         },
+        "key": {
+            "description": "Give a template that has no key one, so code can take it over: the next upload under this key updates this template and keeps its id, workflow and sender. Code sends that already use this key keep their own workflow until that upload, then run through this template's workflow. Send it as the only field of the PATCH. Letters, digits, hyphens (-) and underscores (_). Set once: a template that has a key keeps it.",
+            "maxLength": 400,
+            "type": "string"
+        },
         "message_category": {
             "anyOf": [
                 {

From 98e10b5f7ada1b114368daaba8cbaf3b6d50358c Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 15:54:19 +0000
Subject: [PATCH 05/42] chore(messaging): test the key workflow check when an
 upload adopts a template

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../backend/tests/api/test_template_upload.py | 21 ++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index 17636656c8f9..e51a2245417b 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -385,8 +385,9 @@ def test_refuses_an_upload_it_does_not_allow(
         assert response.status_code == expected_status, response.json()
         assert not MessageTemplate.objects.exists()
 
-    def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edit(
-        self, post: MagicMock, _flag, _capture
+    @parameterized.expand([("a_first_upload", False), ("an_upload_that_adopts_a_template", True)])
+    def test_refuses_under_a_key_whose_workflow_the_member_cannot_edit(
+        self, post: MagicMock, _flag, _capture, _name, adopts_a_template
     ):
         post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
         code_send = {
@@ -399,6 +400,17 @@ def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edi
         sent = self.psak.post(f"/api/projects/{self.team.id}/messaging/send/email/", code_send, format="json")
         assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
         key_workflow_id = post.call_args.args[0].split("/hog_flows/")[1].split("/")[0]
+        made_in_posthog = (
+            MessageTemplate.objects.create(
+                team=self.team,
+                name="Welcome",
+                key="welcome",
+                type="email",
+                content={"email": {"subject": "Hello", "html": "<p>Hello</p>"}},
+            )
+            if adopts_a_template
+            else None
+        )
         self.organization.available_product_features = [
             {"name": AvailableFeature.ACCESS_CONTROL, "key": AvailableFeature.ACCESS_CONTROL}
         ]
@@ -412,7 +424,10 @@ def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edi
         response = self.client.put(self.url, WELCOME, format="json")
 
         assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
-        assert not MessageTemplate.objects.exists()
+        assert [
+            (template.id, template.managed_by, template.content["email"]["subject"], template.transactional_hog_flow_id)
+            for template in MessageTemplate.objects.all()
+        ] == ([(made_in_posthog.id, None, "Hello", None)] if made_in_posthog else [])
 
     @patch("posthog.rate_limit.is_rate_limit_enabled", return_value=True)
     def test_uploads_leave_the_send_rate_limit_to_sends(self, _rate_limit, post: MagicMock, _flag, _capture):

From 3d3a661ebf57da497282979b4001998c075dac1f Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 25 Oct 2026 07:33:25 +0000
Subject: [PATCH 06/42] feat(workflows): link a file and ref on any known git
 host

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../components/Git/gitMetadataParser.spec.ts  | 52 +++++++++++++
 .../lib/components/Git/gitMetadataParser.ts   | 75 ++++++++++++++++---
 2 files changed, 118 insertions(+), 9 deletions(-)

diff --git a/frontend/src/lib/components/Git/gitMetadataParser.spec.ts b/frontend/src/lib/components/Git/gitMetadataParser.spec.ts
index 0ff93905ac42..5f66711f3073 100644
--- a/frontend/src/lib/components/Git/gitMetadataParser.spec.ts
+++ b/frontend/src/lib/components/Git/gitMetadataParser.spec.ts
@@ -18,6 +18,11 @@ describe('GitMetadataParser', () => {
                 remote_url: 'git@gitlab.com:posthog-bot-group/posthog-bot-project.git',
                 expected: 'https://gitlab.com/posthog-bot-group/posthog-bot-project/-/commit/commit-sha',
             },
+            {
+                description: 'should create commit link for bitbucket URL',
+                remote_url: 'https://bitbucket.org/user/repo.git',
+                expected: 'https://bitbucket.org/user/repo/commits/commit-sha',
+            },
             {
                 description: 'should create commit link for gitlab URL',
                 remote_url: 'invalid_url',
@@ -51,6 +56,21 @@ describe('GitMetadataParser', () => {
                 remote_url: 'git@gitlab.com:posthog-bot-group/posthog-bot-project.git',
                 expected: 'https://gitlab.com/posthog-bot-group/posthog-bot-project/-/tree/branch-name',
             },
+            {
+                description: 'should create branch link for bitbucket URL',
+                remote_url: 'https://bitbucket.org/user/repo.git',
+                expected: 'https://bitbucket.org/user/repo/src/branch-name',
+            },
+            {
+                description: 'should create branch link for a gitlab project in a subgroup',
+                remote_url: 'gitlab.com/group/subgroup/project',
+                expected: 'https://gitlab.com/group/subgroup/project/-/tree/branch-name',
+            },
+            {
+                description: 'should create branch link for a gitlab remote with a trailing slash',
+                remote_url: 'https://gitlab.com/group/project/',
+                expected: 'https://gitlab.com/group/project/-/tree/branch-name',
+            },
         ])('$description', ({ remote_url, expected }) => {
             const result = GitMetadataParser.getBranchLink(remote_url, 'branch-name')
             expect(result).toBe(expected)
@@ -80,4 +100,36 @@ describe('GitMetadataParser', () => {
             expect(GitMetadataParser.getGitHubRepositorySlug(remote_url)).toBe(expected)
         })
     })
+
+    describe('getFileLink', () => {
+        it.each([
+            {
+                description: 'a GitHub remote without a scheme',
+                remote_url: 'github.com/example/app',
+                expected: 'https://github.com/example/app/blob/main/emails/welcome.html',
+            },
+            {
+                description: 'a GitLab SSH remote',
+                remote_url: 'git@gitlab.com:example/app.git',
+                expected: 'https://gitlab.com/example/app/-/blob/main/emails/welcome.html',
+            },
+            {
+                description: 'a Bitbucket HTTPS remote',
+                remote_url: 'https://bitbucket.org/example/app',
+                expected: 'https://bitbucket.org/example/app/src/main/emails/welcome.html',
+            },
+            { description: 'an unknown host', remote_url: 'git.example.com/example/app', expected: undefined },
+        ])('links the file for $description', ({ remote_url, expected }) => {
+            expect(GitMetadataParser.getFileLink(remote_url, 'main', './emails/welcome.html')).toBe(expected)
+        })
+
+        it('encodes each part of the ref and the path', () => {
+            expect(GitMetadataParser.getFileLink('github.com/example/app', 'feat/a b', 'emails/a#b.html')).toBe(
+                'https://github.com/example/app/blob/feat/a%20b/emails/a%23b.html'
+            )
+            expect(GitMetadataParser.getRefLink('github.com/example/app', 'fix#12')).toBe(
+                'https://github.com/example/app/tree/fix%2312'
+            )
+        })
+    })
 })
diff --git a/frontend/src/lib/components/Git/gitMetadataParser.ts b/frontend/src/lib/components/Git/gitMetadataParser.ts
index 6c6f198438c9..5c1382fb92dc 100644
--- a/frontend/src/lib/components/Git/gitMetadataParser.ts
+++ b/frontend/src/lib/components/Git/gitMetadataParser.ts
@@ -9,6 +9,11 @@ export type ParsedRemoteUrl = {
 }
 
 const GITHUB_SLUG_PATTERN = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/
+const COMMIT_SHA_PATTERN = /^[0-9a-f]{7,40}$/i
+
+function encodePathSegments(value: string): string {
+    return value.split('/').map(encodeURIComponent).join('/')
+}
 
 export class GitMetadataParser {
     static getCommitLink(remote_url?: string, commit_id?: string): string | undefined {
@@ -33,6 +38,28 @@ export class GitMetadataParser {
         return this.buildBranchLink(parsedRemoteUrl, branch)
     }
 
+    static getRefLink(remote_url?: string, ref?: string): string | undefined {
+        if (!ref) {
+            return undefined
+        }
+        return this.isCommitSha(ref) ? this.getCommitLink(remote_url, ref) : this.getBranchLink(remote_url, ref)
+    }
+
+    static getFileLink(remote_url?: string, ref?: string, path?: string): string | undefined {
+        if (!remote_url || !ref || !path) {
+            return undefined
+        }
+        const parsedRemoteUrl = this.parseRemoteUrl(remote_url)
+        if (!parsedRemoteUrl) {
+            return undefined
+        }
+        return this.buildFileLink(parsedRemoteUrl, ref, path)
+    }
+
+    static isCommitSha(ref: string): boolean {
+        return COMMIT_SHA_PATTERN.test(ref)
+    }
+
     static getRepoLink(remote_url?: string): string | undefined {
         if (!remote_url) {
             return undefined
@@ -57,7 +84,11 @@ export class GitMetadataParser {
     }
 
     static parseRemoteUrl(remoteUrl: string): ParsedRemoteUrl | undefined {
-        return this.parseSshRemoteUrl(remoteUrl) || this.parseHttpsRemoteUrl(remoteUrl)
+        return (
+            this.parseSshRemoteUrl(remoteUrl) ||
+            this.parseHttpsRemoteUrl(remoteUrl) ||
+            this.parseSchemelessRemoteUrl(remoteUrl)
+        )
     }
 
     private static buildRemoteLink(parsedUrl: ParsedRemoteUrl): string | undefined {
@@ -74,10 +105,11 @@ export class GitMetadataParser {
     private static buildBranchLink(parsedUrl: ParsedRemoteUrl, branch: string): string | undefined {
         switch (parsedUrl.provider) {
             case 'github':
-            case 'bitbucket':
-                return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/tree/${branch}`
+                return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/tree/${encodePathSegments(branch)}`
             case 'gitlab':
-                return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/-/tree/${branch}`
+                return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/-/tree/${encodePathSegments(branch)}`
+            case 'bitbucket':
+                return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/src/${encodePathSegments(branch)}`
             default:
                 return undefined
         }
@@ -86,8 +118,9 @@ export class GitMetadataParser {
     private static buildCommitLink(parsedUrl: ParsedRemoteUrl, commitSha: string): string | undefined {
         switch (parsedUrl.provider) {
             case 'github':
-            case 'bitbucket':
                 return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/commit/${commitSha}`
+            case 'bitbucket':
+                return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/commits/${commitSha}`
             case 'gitlab':
                 return `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}/-/commit/${commitSha}`
             default:
@@ -95,6 +128,21 @@ export class GitMetadataParser {
         }
     }
 
+    private static buildFileLink(parsedUrl: ParsedRemoteUrl, ref: string, path: string): string | undefined {
+        const base = `${parsedUrl.providerUrl}/${parsedUrl.owner}/${parsedUrl.repository}`
+        const refAndPath = `${encodePathSegments(ref)}/${encodePathSegments(path.replace(/^\.?\//, ''))}`
+        switch (parsedUrl.provider) {
+            case 'github':
+                return `${base}/blob/${refAndPath}`
+            case 'gitlab':
+                return `${base}/-/blob/${refAndPath}`
+            case 'bitbucket':
+                return `${base}/src/${refAndPath}`
+            default:
+                return undefined
+        }
+    }
+
     private static parseSshRemoteUrl(remoteUrl: string): ParsedRemoteUrl | undefined {
         // git@github.com:user/repo.git
 
@@ -136,23 +184,32 @@ export class GitMetadataParser {
         }
 
         const domain = withoutProtocol.slice(0, firstSlashIdx)
-        const pathParts = withoutProtocol.slice(firstSlashIdx + 1).split('/')
+        const pathParts = withoutProtocol
+            .slice(firstSlashIdx + 1)
+            .split('/')
+            .filter((part) => part !== '')
 
         if (pathParts.length < 2) {
             return undefined
         }
 
+        const [provider, providerUrl] = this.parseDomain(domain)
         const owner = pathParts[0]
-        let repository = pathParts[1]
+        let repository = provider === 'gitlab' ? pathParts.slice(1).join('/') : pathParts[1]
         if (repository.endsWith('.git')) {
             repository = repository.slice(0, -4)
         }
 
-        const [provider, providerUrl] = this.parseDomain(domain)
-
         return { provider, owner, repository, providerUrl }
     }
 
+    private static parseSchemelessRemoteUrl(remoteUrl: string): ParsedRemoteUrl | undefined {
+        if (remoteUrl.includes('://') || remoteUrl.includes('@')) {
+            return undefined
+        }
+        return this.parseHttpsRemoteUrl(`https://${remoteUrl}`)
+    }
+
     private static parseDomain(domain: string): [GitProvider, string | undefined] {
         switch (domain) {
             case 'github.com':

From ca3de9c476b9ef812b5796534df1b2c3c394240b Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 25 Oct 2026 07:33:42 +0000
Subject: [PATCH 07/42] feat(workflows): show code-managed email templates
 read-only

A template uploaded from code opens as a read-only preview with its key
and source. Edits refused by an upload wait in a banner that offers a
duplicate, and the menu can stop managing the template in code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 frontend/src/lib/constants.tsx                |   1 +
 .../CodeManagedSource.stories.tsx             |  55 +++
 .../TemplateLibrary/CodeManagedSource.tsx     |  42 +++
 .../TemplateLibrary/CodeManagedTag.tsx        |  25 ++
 .../TemplateLibrary/EmailHtmlFrame.test.tsx   |  47 +++
 .../TemplateLibrary/EmailHtmlFrame.tsx        |  33 ++
 .../TemplateLibrary/MessageTemplate.tsx       | 315 +++++++++-------
 .../TemplateLibrary/MessageTemplateCard.tsx   |  10 +-
 .../MessageTemplateMenu.test.tsx              |  91 +++++
 .../TemplateLibrary/MessageTemplateMenu.tsx   |  82 +++++
 .../TemplateLibrary/MessageTemplatesTable.tsx |   4 +
 .../QuillMessageTemplateActions.tsx           |  29 +-
 .../ReadOnlyTemplatePreview.stories.tsx       |  23 ++
 .../ReadOnlyTemplatePreview.tsx               |  33 ++
 .../TemplateLibrary/RefusedEditsBanner.tsx    |  34 ++
 .../TransactionalEmailApiExample.tsx          |  24 +-
 .../TemplateLibrary/codeManagedTemplate.ts    |  50 +++
 .../messageTemplateLogic.test.ts              | 345 ++++++++++++++++++
 .../TemplateLibrary/messageTemplateLogic.ts   | 232 ++++++++++--
 .../TemplateLibrary/messageTemplatesLogic.ts  |   7 +-
 .../TemplateLibrary/releaseTemplateDialog.ts  |  17 +
 .../frontend/TemplateLibrary/templateCopy.ts  |   9 +
 .../frontend/TemplateLibrary/types.ts         |   5 +
 23 files changed, 1336 insertions(+), 177 deletions(-)
 create mode 100644 products/workflows/frontend/TemplateLibrary/CodeManagedSource.stories.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/CodeManagedSource.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/CodeManagedTag.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.test.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/codeManagedTemplate.ts
 create mode 100644 products/workflows/frontend/TemplateLibrary/releaseTemplateDialog.ts
 create mode 100644 products/workflows/frontend/TemplateLibrary/templateCopy.ts

diff --git a/frontend/src/lib/constants.tsx b/frontend/src/lib/constants.tsx
index f18891915b6a..9fe80d32fa06 100644
--- a/frontend/src/lib/constants.tsx
+++ b/frontend/src/lib/constants.tsx
@@ -623,6 +623,7 @@ export const FEATURE_FLAGS = {
     WORKFLOWS_DESTINATION_SUGGESTION: 'workflows-destination-suggestion', // owner: #team-workflows, offers workflows instead of a new email tool destination
     WORKFLOWS_EMAIL_DOMAIN_AGENT_SETUP: 'workflows-email-domain-agent-setup', // owner: @silthus #team-workflows
     WORKFLOWS_EMAIL_DOMAIN_WIZARD: 'workflows-email-domain-wizard', // owner: @silthus #team-workflows
+    WORKFLOWS_EMAIL_FROM_CODE: 'workflows-email-from-code', // owner: @silthus #team-workflows
     WORKFLOWS_EMAIL_SENDER_ROTATION: 'workflows-email-sender-rotation', // owner: @arthurdedeus #team-workflows
     WORKFLOWS_INTERNAL_EVENT_FILTERS: 'workflows-internal-event-filters', // owner: @haven #team-workflows
     WORKFLOWS_LINEAR_VIEW: 'workflows-linear-view', // owner: #team-workflows
diff --git a/products/workflows/frontend/TemplateLibrary/CodeManagedSource.stories.tsx b/products/workflows/frontend/TemplateLibrary/CodeManagedSource.stories.tsx
new file mode 100644
index 000000000000..9938c90b05eb
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/CodeManagedSource.stories.tsx
@@ -0,0 +1,55 @@
+import { Meta, StoryFn } from '@storybook/react'
+
+import { CodeManagedSource } from './CodeManagedSource'
+import { CodeManagedTag } from './CodeManagedTag'
+import { templateSource } from './codeManagedTemplate'
+import { NEW_TEMPLATE } from './constants'
+import { MessageTemplate } from './types'
+
+const meta: Meta<typeof CodeManagedSource> = {
+    title: 'Products/Workflows/Template library/Code managed source',
+    component: CodeManagedSource,
+}
+export default meta
+
+function template(overrides: Partial<MessageTemplate> = {}): MessageTemplate {
+    return {
+        ...NEW_TEMPLATE,
+        id: 'template-1',
+        name: 'Welcome',
+        key: 'welcome',
+        managed_by: 'code',
+        source_repository: 'github.com/example/app',
+        source_path: 'emails/welcome.html',
+        source_ref: '3f2c1ab9d4e5f60718293a4b5c6d7e8f90a1b2c3',
+        ...overrides,
+    }
+}
+
+const Template: StoryFn<{ template: MessageTemplate }> = ({ template }) => (
+    <div className="flex flex-col gap-1 w-80">
+        <div className="flex flex-wrap items-center gap-2">
+            <h2 className="m-0">{template.name}</h2>
+            <CodeManagedTag template={template} />
+        </div>
+        <CodeManagedSource source={templateSource(template)} />
+    </div>
+)
+
+export const UploadedFromACommit = Template.bind({})
+UploadedFromACommit.args = { template: template() }
+
+export const LongPathOnGitLabBranch = Template.bind({})
+LongPathOnGitLabBranch.args = {
+    template: template({
+        source_repository: 'gitlab.com/example/customer-lifecycle-emails',
+        source_path: 'emails/onboarding/workspace-owners/welcome-to-your-new-workspace.html',
+        source_ref: 'main',
+    }),
+}
+
+export const UnknownHost = Template.bind({})
+UnknownHost.args = { template: template({ source_repository: 'git.example.com/team/app' }) }
+
+export const NoRecordedSource = Template.bind({})
+NoRecordedSource.args = { template: template({ source_repository: null, source_path: null, source_ref: null }) }
diff --git a/products/workflows/frontend/TemplateLibrary/CodeManagedSource.tsx b/products/workflows/frontend/TemplateLibrary/CodeManagedSource.tsx
new file mode 100644
index 000000000000..e1c26c23a594
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/CodeManagedSource.tsx
@@ -0,0 +1,42 @@
+import { Link } from '@posthog/lemon-ui'
+
+import { cn } from 'lib/utils/css-classes'
+
+import { TemplateSource } from './codeManagedTemplate'
+
+function SourcePart({ label, url }: { label: string; url: string | undefined }): JSX.Element {
+    return url ? (
+        <Link to={url} target="_blank" className="font-mono break-all">
+            {label}
+        </Link>
+    ) : (
+        <span className="font-mono break-all">{label}</span>
+    )
+}
+
+export function CodeManagedSource({
+    source,
+    className,
+}: {
+    source: TemplateSource | null
+    className?: string
+}): JSX.Element | null {
+    if (!source) {
+        return null
+    }
+    const { path, fileUrl, repository, repositoryUrl, ref, refUrl } = source
+
+    return (
+        <p className={cn('m-0 text-sm text-secondary min-w-0', className)} data-attr="message-template-code-source">
+            {path && <SourcePart label={path} url={fileUrl} />}
+            {path && repository && <span> in </span>}
+            {repository && <SourcePart label={repository} url={repositoryUrl} />}
+            {ref && (
+                <>
+                    <span>{path || repository ? ', last uploaded from ' : 'Last uploaded from '}</span>
+                    <SourcePart label={ref} url={refUrl} />
+                </>
+            )}
+        </p>
+    )
+}
diff --git a/products/workflows/frontend/TemplateLibrary/CodeManagedTag.tsx b/products/workflows/frontend/TemplateLibrary/CodeManagedTag.tsx
new file mode 100644
index 000000000000..0bf9585acc16
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/CodeManagedTag.tsx
@@ -0,0 +1,25 @@
+import { IconCode } from '@posthog/icons'
+import { LemonTag, LemonTagProps, Tooltip } from '@posthog/lemon-ui'
+
+import { isCodeManagedTemplate } from './codeManagedTemplate'
+import { MessageTemplate } from './types'
+
+export function CodeManagedTag({
+    template,
+    size,
+}: {
+    template: Pick<MessageTemplate, 'managed_by'> | null | undefined
+    size?: LemonTagProps['size']
+}): JSX.Element | null {
+    if (!isCodeManagedTemplate(template)) {
+        return null
+    }
+
+    return (
+        <Tooltip title="This template is uploaded from a file in a repository. To change it, edit the file and upload it again.">
+            <LemonTag type="default" size={size} icon={<IconCode />} data-attr="message-template-managed-by-code">
+                Managed by code
+            </LemonTag>
+        </Tooltip>
+    )
+}
diff --git a/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx
new file mode 100644
index 000000000000..a1be44c16426
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx
@@ -0,0 +1,47 @@
+import { cleanup, render } from '@testing-library/react'
+
+import { EmailHtmlFrame } from './EmailHtmlFrame'
+
+describe('EmailHtmlFrame', () => {
+    afterEach(() => cleanup())
+
+    function renderedDocument(html: string): Document {
+        const { container } = render(<EmailHtmlFrame html={html} />)
+        return new DOMParser().parseFromString(
+            container.querySelector('iframe')?.getAttribute('srcdoc') ?? '',
+            'text/html'
+        )
+    }
+
+    it.each([
+        ['a link without a target', '<p><a href="https://example.com">Go</a></p>'],
+        ['a link that targets the frame itself', '<p><a href="https://example.com" target="_self">Go</a></p>'],
+        [
+            'a link in a full document',
+            '<!DOCTYPE html><html><head><title>Hi</title></head><body><a href="https://example.com" target="_top">Go</a></body></html>',
+        ],
+    ])('opens %s in a new tab instead of the preview', (_case, html) => {
+        const link = renderedDocument(html).querySelector('a')
+
+        expect(link?.getAttribute('target')).toEqual('_blank')
+        expect(link?.textContent).toEqual('Go')
+    })
+
+    it('keeps the doctype, so the email renders in the same mode', () => {
+        const html =
+            '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><body><p>Hi</p></body></html>'
+        const { container } = render(<EmailHtmlFrame html={html} />)
+
+        expect(container.querySelector('iframe')?.getAttribute('srcdoc')).toMatch(
+            /^<!DOCTYPE html PUBLIC "-\/\/W3C\/\/DTD XHTML 1\.0 Transitional\/\/EN" "http:\/\/www\.w3\.org\/TR\/xhtml1\/DTD\/xhtml1-transitional\.dtd">/
+        )
+    })
+
+    it('lets links open a new tab but never runs scripts', () => {
+        const { container } = render(<EmailHtmlFrame html="<p>Hi</p>" />)
+        const sandbox = container.querySelector('iframe')?.getAttribute('sandbox')?.split(' ')
+
+        expect(sandbox).toEqual(expect.arrayContaining(['allow-popups', 'allow-popups-to-escape-sandbox']))
+        expect(sandbox).not.toContain('allow-scripts')
+    })
+})
diff --git a/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx
new file mode 100644
index 000000000000..9361fb86293b
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx
@@ -0,0 +1,33 @@
+import { useMemo } from 'react'
+
+import { cn } from 'lib/utils/css-classes'
+
+function doctypeOf(parsed: Document): string {
+    const doctype = parsed.doctype
+    if (!doctype) {
+        return ''
+    }
+    const publicId = doctype.publicId ? ` PUBLIC "${doctype.publicId}"` : ''
+    const systemId = doctype.systemId ? `${doctype.publicId ? '' : ' SYSTEM'} "${doctype.systemId}"` : ''
+    return `<!DOCTYPE ${doctype.name}${publicId}${systemId}>`
+}
+
+function withLinksInNewTab(html: string): string {
+    const parsed = new DOMParser().parseFromString(html, 'text/html')
+    for (const link of parsed.querySelectorAll('a[href], area[href]')) {
+        link.setAttribute('target', '_blank')
+    }
+    return doctypeOf(parsed) + parsed.documentElement.outerHTML
+}
+
+export function EmailHtmlFrame({ html, className }: { html: string; className?: string }): JSX.Element {
+    const previewDocument = useMemo(() => withLinksInNewTab(html), [html])
+    return (
+        <iframe
+            srcDoc={previewDocument}
+            sandbox="allow-same-origin allow-popups allow-popups-to-escape-sandbox"
+            title="Message template preview"
+            className={cn('w-full border-0 bg-white', className)}
+        />
+    )
+}
diff --git a/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx b/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx
index d871ce47f60e..9507f4ff6c7e 100644
--- a/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx
+++ b/products/workflows/frontend/TemplateLibrary/MessageTemplate.tsx
@@ -15,9 +15,9 @@ import {
     Tooltip,
 } from '@posthog/lemon-ui'
 
+import { CopyToClipboardInline } from 'lib/components/CopyToClipboard'
 import { SceneTags } from 'lib/components/Scenes/SceneTags'
 import { useFeatureFlag } from 'lib/hooks/useFeatureFlag'
-import { More } from 'lib/lemon-ui/LemonButton/More'
 import { LemonTabs } from 'lib/lemon-ui/LemonTabs'
 import { useAttachedLogic } from 'lib/logic/scenes/useAttachedLogic'
 import { EmailTemplater, TemplatePickerModal } from 'scenes/hog-functions/email-templater/EmailTemplater'
@@ -35,13 +35,19 @@ import { WorkflowInvocations } from '../Workflows/WorkflowInvocations'
 import { workflowLogic } from '../Workflows/workflowLogic'
 import { WorkflowMetrics } from '../Workflows/WorkflowMetrics'
 import { WorkflowRevisions } from '../Workflows/WorkflowRevisions'
+import { CodeManagedSource } from './CodeManagedSource'
+import { CodeManagedTag } from './CodeManagedTag'
 import { MakeTransactionalPrompt } from './MakeTransactionalPrompt'
 import { messageTemplateLogic } from './messageTemplateLogic'
+import { MessageTemplateMenu } from './MessageTemplateMenu'
 import { MessageTemplateSceneLogicProps, messageTemplateSceneLogic } from './messageTemplateSceneLogic'
 import { messageTemplateTestSendLogic } from './messageTemplateTestSendLogic'
 import { NewTemplateAgent } from './NewTemplateAgent'
 import { newTemplateAgentLogic } from './newTemplateAgentLogic'
 import { QuillMessageTemplateActions } from './QuillMessageTemplateActions'
+import { ReadOnlyTemplatePreview } from './ReadOnlyTemplatePreview'
+import { DUPLICATE_REFUSED_EDITS_REASON, RefusedEditsBanner } from './RefusedEditsBanner'
+import { openReleaseTemplateDialog } from './releaseTemplateDialog'
 import { SendTestEmailModal } from './SendTestEmailModal'
 import { NEW_TEMPLATE_AGENT_HEADLINES } from './templateAgentContext'
 import { TransactionalEmailApiExample } from './TransactionalEmailApiExample'
@@ -65,6 +71,7 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
         setTemplateValue,
         duplicateTemplate,
         deleteTemplate,
+        releaseTemplate,
         setTemplatePickerOpen,
         syncExternalEdit,
         keepMyTemplateVersion,
@@ -91,6 +98,10 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
         isSavingDraft,
         isDiscardingDraft,
         isSavingSensitive,
+        isCodeManaged,
+        isDuplicating,
+        refusedEdits,
+        templateSource,
     } = useValues(logic)
     const transactionalEmailsEnabled = useFeatureFlag('WORKFLOWS_TRANSACTIONAL_EMAIL_API')
     const todayRailNav = useFeatureFlag('TODAY_RAIL_NAV')
@@ -132,6 +143,8 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
             {isSyncingExternalEdit && <SpinnerOverlay />}
             {(messageLoading || templateLoading) && !isSyncingExternalEdit ? (
                 <Spinner className="text-lg" />
+            ) : isCodeManaged ? (
+                <ReadOnlyTemplatePreview email={originalTemplate.content.email} />
             ) : (
                 <EmailTemplater
                     value={template?.content.email}
@@ -160,7 +173,7 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
             className="flex flex-col grow [&>div]:flex [&>div]:flex-col [&>div]:grow"
             tabs={[
                 // Unmounting the editor would drop a canvas edit it hasn't exported yet.
-                { key: 'design', label: 'Design', content: editor, keepMounted: true },
+                { key: 'design', label: isCodeManaged ? 'Preview' : 'Design', content: editor, keepMounted: true },
                 transactionalHogFlowId
                     ? {
                           key: 'metrics',
@@ -209,7 +222,7 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
                                     />
                                 </div>
                             </LemonCard>
-                            <TransactionalEmailApiExample templateId={props.id} />
+                            <TransactionalEmailApiExample templateId={props.id} templateKey={originalTemplate.key} />
                         </div>
                     ) : (
                         <MakeTransactionalPrompt {...props} />
@@ -231,42 +244,45 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
                     name={template.name}
                     description={template.description}
                     resourceType={{ type: 'template' }}
-                    canEdit
+                    canEdit={!isCodeManaged}
                     descriptionAlwaysVisible
                     isLoading={messageLoading || templateLoading}
                     onNameChange={(name) => setTemplateValue('name', name)}
                     onDescriptionChange={(description) => setTemplateValue('description', description)}
                     nameSuffix={
-                        showTransactional && transactionalHogFlowId ? (
-                            <>
-                                <LemonTag type="success" className="ml-1">
-                                    Transactional
-                                </LemonTag>
-                                {originalTemplate.sensitive && (
-                                    <Tooltip title="PostHog keeps no copy of what each email contained, and doesn't track link clicks.">
-                                        <LemonTag
-                                            type="highlight"
-                                            icon={<IconLock />}
-                                            className="ml-1"
-                                            data-attr="message-template-sensitive-tag"
-                                        >
-                                            Sensitive
-                                        </LemonTag>
-                                    </Tooltip>
-                                )}
-                                {(hasDraft || hasUnsavedChanges) && (
-                                    <Tooltip title="Your changes save as a draft. Sends use the live version until you publish.">
-                                        <LemonTag
-                                            type="warning"
-                                            className="ml-1"
-                                            data-attr="message-template-draft-tag"
-                                        >
-                                            {isSavingDraft ? 'Saving draft…' : 'Editing draft'}
-                                        </LemonTag>
-                                    </Tooltip>
-                                )}
-                            </>
-                        ) : undefined
+                        <>
+                            {showTransactional && transactionalHogFlowId && (
+                                <>
+                                    <LemonTag type="success" className="ml-1">
+                                        Transactional
+                                    </LemonTag>
+                                    {originalTemplate.sensitive && (
+                                        <Tooltip title="PostHog keeps no copy of what each email contained, and doesn't track link clicks.">
+                                            <LemonTag
+                                                type="highlight"
+                                                icon={<IconLock />}
+                                                className="ml-1"
+                                                data-attr="message-template-sensitive-tag"
+                                            >
+                                                Sensitive
+                                            </LemonTag>
+                                        </Tooltip>
+                                    )}
+                                    {(hasDraft || hasUnsavedChanges) && (
+                                        <Tooltip title="Your changes save as a draft. Sends use the live version until you publish.">
+                                            <LemonTag
+                                                type="warning"
+                                                className="ml-1"
+                                                data-attr="message-template-draft-tag"
+                                            >
+                                                {isSavingDraft ? 'Saving draft…' : 'Editing draft'}
+                                            </LemonTag>
+                                        </Tooltip>
+                                    )}
+                                </>
+                            )}
+                            <CodeManagedTag template={originalTemplate} />
+                        </>
                     }
                     actions={
                         todayRailNav ? (
@@ -276,26 +292,45 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
                                     !template.content.email?.subject ? 'Add a subject first' : undefined
                                 }
                                 saveDisabledReason={
-                                    draftsEnabled && isSavingDraft
-                                        ? 'Saving your draft'
-                                        : draftsEnabled && !hasDraft && !hasUnsavedChanges
-                                          ? 'No changes to publish'
-                                          : !draftsEnabled && !templateChanged && props.id !== 'new'
-                                            ? 'No changes to save'
-                                            : !template.name
-                                              ? 'Name is required'
-                                              : undefined
+                                    isCodeManaged
+                                        ? 'This template is managed by code'
+                                        : draftsEnabled && isSavingDraft
+                                          ? 'Saving your draft'
+                                          : draftsEnabled && !hasDraft && !hasUnsavedChanges
+                                            ? 'No changes to publish'
+                                            : !draftsEnabled && !templateChanged && props.id !== 'new'
+                                              ? 'No changes to save'
+                                              : !template.name
+                                                ? 'Name is required'
+                                                : undefined
                                 }
                                 duplicateDisabledReason={
-                                    templateChanged ? 'Save your changes before duplicating' : undefined
+                                    isDuplicating
+                                        ? 'Duplicating…'
+                                        : refusedEdits
+                                          ? DUPLICATE_REFUSED_EDITS_REASON
+                                          : templateChanged
+                                            ? 'Save your changes before duplicating'
+                                            : undefined
                                 }
-                                templateChanged={templateChanged && !draftsEnabled}
+                                templateChanged={templateChanged && !draftsEnabled && !isCodeManaged}
                                 saving={isTemplateSubmitting || templateLoading}
                                 onSendTest={() => setSendTestEmailModalOpen(true)}
                                 onDiscard={() => resetTemplate(originalTemplate)}
                                 onSave={submitTemplate}
-                                onSaveAsNew={() => setIsSaveTemplateModalOpen(true)}
+                                onSaveAsNew={isCodeManaged ? undefined : () => setIsSaveTemplateModalOpen(true)}
                                 onDuplicate={duplicateTemplate}
+                                onRelease={
+                                    isCodeManaged
+                                        ? () => openReleaseTemplateDialog(originalTemplate, releaseTemplate)
+                                        : undefined
+                                }
+                                releaseDisabledReason={templateLoading ? 'Wait for the template to load' : undefined}
+                                deleteDisabledReason={
+                                    isCodeManaged
+                                        ? 'This template is managed by code. To delete it, stop managing it in code first.'
+                                        : undefined
+                                }
                                 onDelete={deleteTemplate}
                             />
                         ) : (
@@ -312,7 +347,7 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
                                 >
                                     Send test
                                 </LemonButton>
-                                {templateChanged && !draftsEnabled && (
+                                {templateChanged && !draftsEnabled && !isCodeManaged && (
                                     <LemonButton
                                         data-attr="cancel-message-template"
                                         type="secondary"
@@ -322,95 +357,59 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
                                         Discard changes
                                     </LemonButton>
                                 )}
-                                <LemonButton
-                                    type="primary"
-                                    htmlType="submit"
-                                    form="template"
-                                    onClick={submitTemplate}
-                                    loading={isTemplateSubmitting || templateLoading}
-                                    disabledReason={
-                                        draftsEnabled && isSavingDraft
-                                            ? 'Saving your draft'
-                                            : draftsEnabled && !hasDraft && !hasUnsavedChanges
-                                              ? 'No changes to publish'
-                                              : !draftsEnabled && !templateChanged && props.id !== 'new'
-                                                ? 'No changes to save'
-                                                : !template.name
-                                                  ? 'Name is required'
-                                                  : undefined
-                                    }
-                                    size="small"
-                                    sideAction={
-                                        draftsEnabled
-                                            ? {
-                                                  'data-attr': 'message-template-draft-actions',
-                                                  'aria-label': 'More draft actions',
-                                                  dropdown: {
-                                                      placement: 'bottom-end',
-                                                      overlay: (
-                                                          <LemonMenuOverlay
-                                                              items={[
-                                                                  {
-                                                                      label: 'Discard draft',
-                                                                      icon: <IconTrash />,
-                                                                      status: 'danger',
-                                                                      onClick: discardDraft,
-                                                                      disabledReason: !hasDraft
-                                                                          ? 'There is no draft to discard'
-                                                                          : isSavingDraft || isDiscardingDraft
-                                                                            ? 'Wait for the draft to finish saving'
-                                                                            : undefined,
-                                                                      'data-attr': 'message-template-discard-draft',
-                                                                  },
-                                                              ]}
-                                                          />
-                                                      ),
-                                                  },
-                                              }
-                                            : undefined
-                                    }
-                                >
-                                    {props.id === 'new' ? 'Create' : draftsEnabled ? 'Publish' : 'Save'}
-                                </LemonButton>
-                                <More
-                                    size="small"
-                                    overlay={
-                                        <>
-                                            <LemonButton
-                                                data-attr="save-as-new-template"
-                                                fullWidth
-                                                onClick={() => setIsSaveTemplateModalOpen(true)}
-                                            >
-                                                Save as new template
-                                            </LemonButton>
-                                            {props.id !== 'new' && (
-                                                <>
-                                                    <LemonButton
-                                                        data-attr="duplicate-message-template"
-                                                        fullWidth
-                                                        onClick={duplicateTemplate}
-                                                        disabledReason={
-                                                            hasUnsavedChanges
-                                                                ? 'Save your changes before duplicating'
-                                                                : undefined
-                                                        }
-                                                    >
-                                                        Duplicate
-                                                    </LemonButton>
-                                                    <LemonDivider />
-                                                    <LemonButton
-                                                        data-attr="delete-message-template"
-                                                        status="danger"
-                                                        fullWidth
-                                                        onClick={deleteTemplate}
-                                                    >
-                                                        Delete
-                                                    </LemonButton>
-                                                </>
-                                            )}
-                                        </>
-                                    }
-                                />
+                                {!isCodeManaged && (
+                                    <LemonButton
+                                        type="primary"
+                                        htmlType="submit"
+                                        form="template"
+                                        onClick={submitTemplate}
+                                        loading={isTemplateSubmitting || templateLoading}
+                                        disabledReason={
+                                            draftsEnabled && isSavingDraft
+                                                ? 'Saving your draft'
+                                                : draftsEnabled && !hasDraft && !hasUnsavedChanges
+                                                  ? 'No changes to publish'
+                                                  : !draftsEnabled && !templateChanged && props.id !== 'new'
+                                                    ? 'No changes to save'
+                                                    : !template.name
+                                                      ? 'Name is required'
+                                                      : undefined
+                                        }
+                                        size="small"
+                                        sideAction={
+                                            draftsEnabled
+                                                ? {
+                                                      'data-attr': 'message-template-draft-actions',
+                                                      'aria-label': 'More draft actions',
+                                                      dropdown: {
+                                                          placement: 'bottom-end',
+                                                          overlay: (
+                                                              <LemonMenuOverlay
+                                                                  items={[
+                                                                      {
+                                                                          label: 'Discard draft',
+                                                                          icon: <IconTrash />,
+                                                                          status: 'danger',
+                                                                          onClick: discardDraft,
+                                                                          disabledReason: !hasDraft
+                                                                              ? 'There is no draft to discard'
+                                                                              : isSavingDraft || isDiscardingDraft
+                                                                                ? 'Wait for the draft to finish saving'
+                                                                                : undefined,
+                                                                          'data-attr': 'message-template-discard-draft',
+                                                                      },
+                                                                  ]}
+                                                              />
+                                                          ),
+                                                      },
+                                                  }
+                                                : undefined
+                                        }
+                                    >
+                                        {props.id === 'new' ? 'Create' : draftsEnabled ? 'Publish' : 'Save'}
+                                    </LemonButton>
+                                )}
+                                <MessageTemplateMenu {...props} />
                             </>
                         )
                     }
@@ -423,6 +422,50 @@ export function MessageTemplate(props: MessageTemplateSceneLogicProps): JSX.Elem
                     dataAttrKey="message-template"
                 />
 
+                {(originalTemplate.key || templateSource) && (
+                    <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-sm text-secondary">
+                        {originalTemplate.key && (
+                            <span
+                                className="flex items-center gap-1 min-w-0 max-w-full"
+                                data-attr="message-template-key"
+                            >
+                                <span className="shrink-0">Key</span>
+                                <span className="font-mono truncate min-w-0" title={originalTemplate.key}>
+                                    {originalTemplate.key}
+                                </span>
+                                <CopyToClipboardInline
+                                    explicitValue={originalTemplate.key}
+                                    description="template key"
+                                    iconMargin={false}
+                                />
+                            </span>
+                        )}
+                        <CodeManagedSource source={templateSource} />
+                    </div>
+                )}
+
+                <RefusedEditsBanner {...props} />
+
+                {isCodeManaged && (
+                    <LemonBanner
+                        type="info"
+                        className="shrink-0"
+                        action={
+                            refusedEdits
+                                ? undefined
+                                : {
+                                      children: 'Duplicate',
+                                      onClick: duplicateTemplate,
+                                      loading: isDuplicating,
+                                      'data-attr': 'message-template-code-managed-duplicate',
+                                  }
+                        }
+                    >
+                        This template is managed by code, so it can't be changed here. To change it, edit the file and
+                        upload it again. To edit it here, duplicate it or stop managing it in code.
+                    </LemonBanner>
+                )}
+
                 <TemplatePickerModal isOpen={templatePickerOpen} onClose={() => setTemplatePickerOpen(false)} />
                 <SendTestEmailModal {...props} isOpen={isSendTestEmailModalOpen} />
 
diff --git a/products/workflows/frontend/TemplateLibrary/MessageTemplateCard.tsx b/products/workflows/frontend/TemplateLibrary/MessageTemplateCard.tsx
index 5a76815a1de0..4cd1557e2236 100644
--- a/products/workflows/frontend/TemplateLibrary/MessageTemplateCard.tsx
+++ b/products/workflows/frontend/TemplateLibrary/MessageTemplateCard.tsx
@@ -5,6 +5,8 @@ import { ObjectTags } from 'lib/components/ObjectTags/ObjectTags'
 import { TZLabel } from 'lib/components/TZLabel'
 import { ProfilePicture } from 'lib/lemon-ui/ProfilePicture'
 
+import { CodeManagedTag } from './CodeManagedTag'
+import { EmailHtmlFrame } from './EmailHtmlFrame'
 import { MessageTemplate } from './types'
 
 export function MessageTemplateCard({
@@ -32,12 +34,7 @@ export function MessageTemplateCard({
                 )}
                 <div className="w-full overflow-hidden grow">
                     {emailHtml ? (
-                        <iframe
-                            srcDoc={emailHtml}
-                            sandbox="allow-same-origin"
-                            title="Message template preview"
-                            className="w-full h-full border-0 bg-white pointer-events-none"
-                        />
+                        <EmailHtmlFrame html={emailHtml} className="h-full pointer-events-none" />
                     ) : (
                         <FallbackCoverImage src={undefined} alt="cover photo" index={index} className="h-full" />
                     )}
@@ -51,6 +48,7 @@ export function MessageTemplateCard({
                                 Transactional
                             </LemonTag>
                         )}
+                        <CodeManagedTag template={template} size="small" />
                     </div>
                     {template.description && (
                         <p className="text-secondary text-xs line-clamp-1 mb-1">{template.description}</p>
diff --git a/products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.test.tsx b/products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.test.tsx
new file mode 100644
index 000000000000..d57357a38b70
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.test.tsx
@@ -0,0 +1,91 @@
+import '@testing-library/jest-dom'
+
+import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { expectLogic } from 'kea-test-utils'
+
+import { useMocks } from '~/mocks/jest'
+import { initKeaTests } from '~/test/init'
+
+import { messageTemplateLogic } from './messageTemplateLogic'
+import { MessageTemplateMenu } from './MessageTemplateMenu'
+
+const CODE_MANAGED = {
+    id: 'existing-id',
+    name: 'Welcome',
+    content: { templating: 'liquid', email: { subject: 'Welcome', html: '<p>Hi</p>', text: 'Hi' } },
+    key: 'welcome',
+    managed_by: 'code',
+    source_path: 'emails/welcome.html',
+}
+
+describe('MessageTemplateMenu', () => {
+    let logic: ReturnType<typeof messageTemplateLogic.build>
+    let patchBodies: Record<string, unknown>[]
+    let createBodies: Record<string, unknown>[]
+
+    const openReleaseDialog = async (): Promise<void> => {
+        fireEvent.click(await screen.findByText('Stop managing in code'))
+        await screen.findByText('Stop managing this template in code?')
+    }
+
+    beforeEach(async () => {
+        patchBodies = []
+        createBodies = []
+        useMocks({
+            get: { '/api/environments/:team_id/messaging_templates/:id/': CODE_MANAGED },
+            patch: {
+                '/api/environments/:team_id/messaging_templates/:id/': async ({ request }: { request: Request }) => {
+                    patchBodies.push(await request.json())
+                    return [200, { ...CODE_MANAGED, managed_by: 'gui' }]
+                },
+            },
+            post: {
+                '/api/environments/:team_id/messaging_templates/': async ({ request }: { request: Request }) => {
+                    createBodies.push(await request.json())
+                    return [201, { id: 'copy-id' }]
+                },
+            },
+        })
+        initKeaTests()
+        logic = messageTemplateLogic({ id: 'existing-id' })
+        logic.mount()
+        await expectLogic(logic).toDispatchActions(['loadTemplateSuccess'])
+        render(<MessageTemplateMenu id="existing-id" />)
+        fireEvent.click(screen.getByLabelText('more'))
+    })
+
+    afterEach(() => {
+        cleanup()
+        logic.unmount()
+    })
+
+    it('keeps the template managed by code when the release is cancelled', async () => {
+        await openReleaseDialog()
+        fireEvent.click(screen.getByText('Cancel'))
+
+        await waitFor(() => expect(screen.queryByText('Stop managing this template in code?')).not.toBeInTheDocument())
+        expect(patchBodies).toEqual([])
+        expect(logic.values.isCodeManaged).toBe(true)
+    })
+
+    it('releases the template to PostHog once the release is confirmed', async () => {
+        await openReleaseDialog()
+        const dialog = screen.getByText('Stop managing this template in code?').closest('.LemonModal') as HTMLElement
+        fireEvent.click(dialog.querySelector('[data-attr="message-template-release-confirm"]') as HTMLElement)
+
+        await expectLogic(logic).toDispatchActions(['releaseTemplateSuccess'])
+        expect(patchBodies).toEqual([{ managed_by: 'gui' }])
+        expect(logic.values.isCodeManaged).toBe(false)
+    })
+
+    it('points Duplicate to the refused edits instead of copying the server version', async () => {
+        act(() => logic.actions.setRefusedEdits({ ...logic.values.template, name: 'Welcome, edited here' }))
+        const duplicate = (await screen.findByText('Duplicate')).closest('button') as HTMLElement
+
+        fireEvent.click(duplicate)
+        await expectLogic(logic).toFinishAllListeners()
+
+        expect(duplicate).toHaveAttribute('aria-disabled', 'true')
+        expect(createBodies).toEqual([])
+    })
+})
diff --git a/products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.tsx b/products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.tsx
new file mode 100644
index 000000000000..32bb441dd002
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/MessageTemplateMenu.tsx
@@ -0,0 +1,82 @@
+import { useActions, useValues } from 'kea'
+
+import { IconUnlock } from '@posthog/icons'
+import { LemonButton, LemonDivider } from '@posthog/lemon-ui'
+
+import { More } from 'lib/lemon-ui/LemonButton/More'
+import { emailTemplaterLogic } from 'scenes/hog-functions/email-templater/emailTemplaterLogic'
+
+import { MessageTemplateLogicProps, messageTemplateLogic } from './messageTemplateLogic'
+import { DUPLICATE_REFUSED_EDITS_REASON } from './RefusedEditsBanner'
+import { openReleaseTemplateDialog } from './releaseTemplateDialog'
+
+export function MessageTemplateMenu(props: MessageTemplateLogicProps): JSX.Element {
+    const logic = messageTemplateLogic(props)
+    const { duplicateTemplate, deleteTemplate, releaseTemplate } = useActions(logic)
+    const { originalTemplate, hasUnsavedChanges, templateLoading, isCodeManaged, isDuplicating, refusedEdits } =
+        useValues(logic)
+    const { setIsSaveTemplateModalOpen } = useActions(emailTemplaterLogic)
+
+    return (
+        <More
+            size="small"
+            overlay={
+                <>
+                    {!isCodeManaged && (
+                        <LemonButton
+                            data-attr="save-as-new-template"
+                            fullWidth
+                            onClick={() => setIsSaveTemplateModalOpen(true)}
+                        >
+                            Save as new template
+                        </LemonButton>
+                    )}
+                    {props.id !== 'new' && (
+                        <>
+                            <LemonButton
+                                data-attr="duplicate-message-template"
+                                fullWidth
+                                onClick={duplicateTemplate}
+                                loading={isDuplicating}
+                                disabledReason={
+                                    refusedEdits
+                                        ? DUPLICATE_REFUSED_EDITS_REASON
+                                        : hasUnsavedChanges
+                                          ? 'Save your changes before duplicating'
+                                          : undefined
+                                }
+                            >
+                                Duplicate
+                            </LemonButton>
+                            {isCodeManaged && (
+                                <LemonButton
+                                    data-attr="message-template-release"
+                                    icon={<IconUnlock />}
+                                    fullWidth
+                                    onClick={() => openReleaseTemplateDialog(originalTemplate, releaseTemplate)}
+                                    disabledReason={templateLoading ? 'Wait for the template to load' : undefined}
+                                >
+                                    Stop managing in code
+                                </LemonButton>
+                            )}
+                            <LemonDivider />
+                            <LemonButton
+                                data-attr="delete-message-template"
+                                status="danger"
+                                fullWidth
+                                onClick={deleteTemplate}
+                                disabledReason={
+                                    isCodeManaged
+                                        ? 'This template is managed by code. To delete it, stop managing it in code first.'
+                                        : undefined
+                                }
+                            >
+                                Delete
+                            </LemonButton>
+                        </>
+                    )}
+                </>
+            }
+        />
+    )
+}
diff --git a/products/workflows/frontend/TemplateLibrary/MessageTemplatesTable.tsx b/products/workflows/frontend/TemplateLibrary/MessageTemplatesTable.tsx
index a006244d68b1..8774e3ba6811 100644
--- a/products/workflows/frontend/TemplateLibrary/MessageTemplatesTable.tsx
+++ b/products/workflows/frontend/TemplateLibrary/MessageTemplatesTable.tsx
@@ -25,6 +25,7 @@ import MaxTool from 'scenes/max/MaxTool'
 
 import { AccessControlLevel, AccessControlResourceType } from '~/types'
 
+import { isCodeManagedTemplate } from './codeManagedTemplate'
 import { MessageTemplateCard } from './MessageTemplateCard'
 import { messageTemplatesLogic, saveTemplateTags } from './messageTemplatesLogic'
 import { newTemplateAgentLogic } from './newTemplateAgentLogic'
@@ -208,6 +209,9 @@ export function MessageTemplatesTable(): JSX.Element {
                                                     status: 'danger' as const,
                                                     icon: <IconTrash />,
                                                     onClick: () => deleteTemplate(template),
+                                                    disabledReason: isCodeManagedTemplate(template)
+                                                        ? 'This template is managed by code. To delete it, open it and stop managing it in code first.'
+                                                        : undefined,
                                                 },
                                             ]}
                                         />
diff --git a/products/workflows/frontend/TemplateLibrary/QuillMessageTemplateActions.tsx b/products/workflows/frontend/TemplateLibrary/QuillMessageTemplateActions.tsx
index 70d2af8d047b..ae77fb82bca5 100644
--- a/products/workflows/frontend/TemplateLibrary/QuillMessageTemplateActions.tsx
+++ b/products/workflows/frontend/TemplateLibrary/QuillMessageTemplateActions.tsx
@@ -1,4 +1,4 @@
-import { IconEllipsis } from '@posthog/icons'
+import { IconEllipsis, IconUnlock } from '@posthog/icons'
 import {
     Button,
     DropdownMenu,
@@ -14,6 +14,8 @@ export function QuillMessageTemplateActions({
     sendTestDisabledReason,
     saveDisabledReason,
     duplicateDisabledReason,
+    releaseDisabledReason,
+    deleteDisabledReason,
     templateChanged,
     saving,
     onSendTest,
@@ -21,19 +23,23 @@ export function QuillMessageTemplateActions({
     onSave,
     onSaveAsNew,
     onDuplicate,
+    onRelease,
     onDelete,
 }: {
     isNew: boolean
     sendTestDisabledReason?: string
     saveDisabledReason?: string
     duplicateDisabledReason?: string
+    releaseDisabledReason?: string
+    deleteDisabledReason?: string
     templateChanged: boolean
     saving: boolean
     onSendTest: () => void
     onDiscard: () => void
     onSave: () => void
-    onSaveAsNew: () => void
+    onSaveAsNew?: () => void
     onDuplicate: () => void
+    onRelease?: () => void
     onDelete: () => void
 }): JSX.Element {
     return (
@@ -67,9 +73,11 @@ export function QuillMessageTemplateActions({
                     <IconEllipsis />
                 </DropdownMenuTrigger>
                 <DropdownMenuContent align="end">
-                    <DropdownMenuItem data-attr="save-as-new-template" onClick={onSaveAsNew}>
-                        Save as new template
-                    </DropdownMenuItem>
+                    {onSaveAsNew && (
+                        <DropdownMenuItem data-attr="save-as-new-template" onClick={onSaveAsNew}>
+                            Save as new template
+                        </DropdownMenuItem>
+                    )}
                     {!isNew && (
                         <>
                             <DropdownMenuItem
@@ -79,10 +87,21 @@ export function QuillMessageTemplateActions({
                             >
                                 Duplicate
                             </DropdownMenuItem>
+                            {onRelease && (
+                                <DropdownMenuItem
+                                    data-attr="message-template-release"
+                                    disabledReason={releaseDisabledReason}
+                                    onClick={onRelease}
+                                >
+                                    <IconUnlock />
+                                    Stop managing in code
+                                </DropdownMenuItem>
+                            )}
                             <DropdownMenuSeparator />
                             <DropdownMenuItem
                                 data-attr="delete-message-template"
                                 variant="destructive"
+                                disabledReason={deleteDisabledReason}
                                 onClick={onDelete}
                             >
                                 Delete
diff --git a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx
new file mode 100644
index 000000000000..e903d57076e1
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx
@@ -0,0 +1,23 @@
+import { Meta, StoryFn } from '@storybook/react'
+
+import { ReadOnlyTemplatePreview } from './ReadOnlyTemplatePreview'
+
+const meta: Meta<typeof ReadOnlyTemplatePreview> = {
+    title: 'Products/Workflows/Template library/Read-only template preview',
+    component: ReadOnlyTemplatePreview,
+}
+export default meta
+
+export const UploadedFromCode: StoryFn<typeof ReadOnlyTemplatePreview> = () => (
+    <ReadOnlyTemplatePreview
+        email={{
+            subject: 'Welcome to Hedgebox, {{ variables.first_name }}',
+            preheader: 'Your files are ready to share',
+            html: '<div style="font-family: sans-serif; padding: 24px"><h1>Welcome, {{ variables.first_name }}</h1><p>Your Hedgebox account is ready.</p><a href="https://example.com/start">Get started</a></div>',
+            text: 'Welcome, {{ variables.first_name }}\n\nYour Hedgebox account is ready.\n\nGet started: https://example.com/start',
+            design: null,
+            from: '',
+            to: '',
+        }}
+    />
+)
diff --git a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
new file mode 100644
index 000000000000..0b89182a886e
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
@@ -0,0 +1,33 @@
+import { LemonField } from 'lib/lemon-ui/LemonField'
+import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'
+
+import { EmailHtmlFrame } from './EmailHtmlFrame'
+
+export function ReadOnlyTemplatePreview({ email }: { email: EmailTemplate }): JSX.Element {
+    return (
+        <div className="flex flex-col flex-1 gap-4 min-h-0" data-attr="message-template-read-only-preview">
+            <div className="flex flex-col gap-3 rounded border bg-surface-primary p-3">
+                <LemonField.Pure label="Subject" className="gap-1 min-w-0">
+                    <span className="break-words">{email.subject}</span>
+                </LemonField.Pure>
+                {email.preheader && (
+                    <LemonField.Pure label="Preheader" className="gap-1 min-w-0">
+                        <span className="break-words text-secondary">{email.preheader}</span>
+                    </LemonField.Pure>
+                )}
+            </div>
+            <LemonField.Pure label="HTML" className="gap-1 min-w-0">
+                <EmailHtmlFrame html={email.html} className="h-128 rounded border" />
+            </LemonField.Pure>
+            <LemonField.Pure label="Plain text" className="gap-1 min-w-0">
+                {email.text ? (
+                    <pre className="m-0 rounded border bg-surface-primary p-3 text-sm whitespace-pre-wrap break-words">
+                        {email.text}
+                    </pre>
+                ) : (
+                    <span className="text-secondary">This template has no plain text version.</span>
+                )}
+            </LemonField.Pure>
+        </div>
+    )
+}
diff --git a/products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx b/products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx
new file mode 100644
index 000000000000..b08f293d449f
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx
@@ -0,0 +1,34 @@
+import { useActions, useValues } from 'kea'
+
+import { LemonBanner } from '@posthog/lemon-ui'
+
+import { MessageTemplateLogicProps, messageTemplateLogic } from './messageTemplateLogic'
+
+export const DUPLICATE_REFUSED_EDITS_REASON = 'To keep your changes, use "Duplicate with my changes"'
+
+export function RefusedEditsBanner(props: MessageTemplateLogicProps): JSX.Element | null {
+    const logic = messageTemplateLogic(props)
+    const { refusedEdits, isDuplicating } = useValues(logic)
+    const { duplicateWithMyChanges, setRefusedEdits } = useActions(logic)
+
+    if (!refusedEdits) {
+        return null
+    }
+
+    return (
+        <LemonBanner
+            type="warning"
+            className="shrink-0"
+            onClose={() => setRefusedEdits(null)}
+            action={{
+                children: 'Duplicate with my changes',
+                onClick: duplicateWithMyChanges,
+                loading: isDuplicating,
+                'data-attr': 'message-template-refused-edits-duplicate',
+            }}
+        >
+            Your changes weren't saved. While you were editing, an upload from code took this template back. To keep
+            your changes, duplicate the template with them. If you close this message, your changes are discarded.
+        </LemonBanner>
+    )
+}
diff --git a/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx b/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx
index 8f35f9e076fd..aaac891ec512 100644
--- a/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx
+++ b/products/workflows/frontend/TemplateLibrary/TransactionalEmailApiExample.tsx
@@ -3,18 +3,28 @@ import { useValues } from 'kea'
 import { Link } from '@posthog/lemon-ui'
 
 import { CodeSnippet, Language } from 'lib/components/CodeSnippet'
+import { useFeatureFlag } from 'lib/hooks/useFeatureFlag'
 import { teamLogic } from 'scenes/teamLogic'
 import { urls } from 'scenes/urls'
 
+function templateReference(templateId: string, templateKey: string | null | undefined): string {
+    return templateKey ? `{ "key": "${templateKey}" }` : `{ "id": "${templateId}" }`
+}
+
 export function TransactionalEmailApiExample({
     templateId,
+    templateKey,
     variables,
 }: {
     templateId: string
+    templateKey?: string | null
     /** The email's `{{ variables.* }}` names. The snippet shows a sample when the email uses none. */
     variables?: string[]
 }): JSX.Element {
     const { currentTeamIdStrict } = useValues(teamLogic)
+    const sendsByTemplateKey = useFeatureFlag('WORKFLOWS_EMAIL_FROM_CODE')
+    const sentKey = sendsByTemplateKey ? templateKey : null
+    const template = templateReference(templateId, sentKey)
     const messageData = variables?.length
         ? `{ ${variables.map((name) => `"${name}": "..."`).join(', ')} }`
         : '{ "first_name": "Jane", "reset_link": "https://example.com/reset" }'
@@ -23,7 +33,7 @@ export function TransactionalEmailApiExample({
   -H "Content-Type: application/json" \\
   -H "Idempotency-Key: password-reset-123" \\
   -d '{
-    "template": { "id": "${templateId}" },
+    "template": ${template},
     "to": "jane@example.com",
     "identifiers": { "distinct_id": "jane-distinct-id" },
     "message_data": ${messageData}
@@ -41,6 +51,18 @@ export function TransactionalEmailApiExample({
                     <Link to={urls.settings('environment-secret-api-keys')}>project secret API key</Link> that has the{' '}
                     <code>hog_flow:write</code> scope.
                 </li>
+                <li>
+                    {sentKey ? (
+                        <>
+                            <code>template.key</code> names this template. The key is the same in every project that has
+                            the template.
+                        </>
+                    ) : (
+                        <>
+                            <code>template.id</code> names this template in this project.
+                        </>
+                    )}
+                </li>
                 <li>
                     <code>message_data</code> fills the template's <code>{'{{ variables.* }}'}</code> placeholders. The
                     template can't read person properties, so pass everything it needs here.
diff --git a/products/workflows/frontend/TemplateLibrary/codeManagedTemplate.ts b/products/workflows/frontend/TemplateLibrary/codeManagedTemplate.ts
new file mode 100644
index 000000000000..1978b2a8f587
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/codeManagedTemplate.ts
@@ -0,0 +1,50 @@
+import { GitMetadataParser } from 'lib/components/Git/gitMetadataParser'
+
+import { MessageTemplate } from './types'
+
+export interface TemplateSource {
+    path: string | null
+    fileUrl: string | undefined
+    repository: string | null
+    repositoryUrl: string | undefined
+    ref: string | null
+    refUrl: string | undefined
+}
+
+export function isCodeManagedTemplate(template: Pick<MessageTemplate, 'managed_by'> | null | undefined): boolean {
+    return template?.managed_by === 'code'
+}
+
+export function templateSource(template: MessageTemplate | null | undefined): TemplateSource | null {
+    if (!isCodeManagedTemplate(template)) {
+        return null
+    }
+    const repository = template?.source_repository || undefined
+    const path = template?.source_path || undefined
+    const ref = template?.source_ref || undefined
+    if (!repository && !path && !ref) {
+        return null
+    }
+    return {
+        path: path ?? null,
+        fileUrl: GitMetadataParser.getFileLink(repository, ref, path),
+        repository: repository ?? null,
+        repositoryUrl: GitMetadataParser.getRepoLink(repository),
+        ref: ref ? shortRef(ref) : null,
+        refUrl: GitMetadataParser.getRefLink(repository, ref),
+    }
+}
+
+function shortRef(ref: string): string {
+    return GitMetadataParser.isCommitSha(ref) ? ref.slice(0, 7) : ref
+}
+
+const SERVER_OWNED_FIELDS = ['key', 'managed_by', 'source_repository', 'source_path', 'source_ref'] as const
+
+export function withoutServerOwnedFields(template: MessageTemplate): Partial<MessageTemplate> {
+    const editable: Partial<MessageTemplate> = { ...template }
+    for (const field of SERVER_OWNED_FIELDS) {
+        delete editable[field]
+    }
+    return editable
+}
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
index 979b3d0caab5..eade5c5004be 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
@@ -429,6 +429,351 @@ describe('messageTemplateLogic', () => {
         })
     })
 
+    const CODE_MANAGED = {
+        id: 'existing-id',
+        name: 'Welcome',
+        description: 'Sent after signup',
+        content: {
+            templating: 'liquid',
+            email: { subject: 'Welcome', html: '<p>Hi</p>', text: 'Hi', design: null, from: '', to: '' },
+        },
+        key: 'welcome',
+        managed_by: 'code',
+        source_repository: 'github.com/example/app',
+        source_path: 'emails/welcome.html',
+        source_ref: '3f2c1ab9d4e5f60718293a4b5c6d7e8f90a1b2c3',
+        content_hash: 'v1:0000000000000000000000000000000000000000000000000000000000000000',
+    }
+
+    describe('code-managed source', () => {
+        it.each([
+            {
+                description: 'a template made in PostHog has no source',
+                served: { id: 'existing-id', name: 'Existing', managed_by: null },
+                isCodeManaged: false,
+                templateSource: null,
+            },
+            {
+                description: 'a keyed template that PostHog still manages has no source',
+                served: { ...CODE_MANAGED, managed_by: 'gui' },
+                isCodeManaged: false,
+                templateSource: null,
+            },
+            {
+                description: 'a known host links the file, the repository and the shortened commit',
+                served: CODE_MANAGED,
+                isCodeManaged: true,
+                templateSource: {
+                    path: 'emails/welcome.html',
+                    fileUrl:
+                        'https://github.com/example/app/blob/3f2c1ab9d4e5f60718293a4b5c6d7e8f90a1b2c3/emails/welcome.html',
+                    repository: 'github.com/example/app',
+                    repositoryUrl: 'https://github.com/example/app',
+                    ref: '3f2c1ab',
+                    refUrl: 'https://github.com/example/app/commit/3f2c1ab9d4e5f60718293a4b5c6d7e8f90a1b2c3',
+                },
+            },
+            {
+                description: 'a branch links to the branch',
+                served: { ...CODE_MANAGED, source_ref: 'main' },
+                isCodeManaged: true,
+                templateSource: expect.objectContaining({
+                    ref: 'main',
+                    refUrl: 'https://github.com/example/app/tree/main',
+                }),
+            },
+            {
+                description: 'an unknown host stays plain text',
+                served: { ...CODE_MANAGED, source_repository: 'git.example.com/team/app' },
+                isCodeManaged: true,
+                templateSource: {
+                    path: 'emails/welcome.html',
+                    fileUrl: undefined,
+                    repository: 'git.example.com/team/app',
+                    repositoryUrl: undefined,
+                    ref: '3f2c1ab',
+                    refUrl: undefined,
+                },
+            },
+            {
+                description: 'an upload without a source shows none',
+                served: { ...CODE_MANAGED, source_repository: null, source_path: null, source_ref: null },
+                isCodeManaged: true,
+                templateSource: null,
+            },
+        ])('$description', async ({ served, isCodeManaged, templateSource }) => {
+            useMocks({ get: { '/api/environments/:team_id/messaging_templates/:id/': served } })
+            logic = messageTemplateLogic({ id: 'existing-id' })
+            logic.mount()
+
+            await expectLogic(logic)
+                .toDispatchActions(['loadTemplateSuccess'])
+                .toMatchValues({ isCodeManaged, templateSource })
+        })
+    })
+
+    describe('code-managed template', () => {
+        let patchBodies: Record<string, unknown>[]
+        let createBodies: Record<string, unknown>[]
+
+        beforeEach(async () => {
+            patchBodies = []
+            createBodies = []
+            useMocks({
+                get: { '/api/environments/:team_id/messaging_templates/:id/': CODE_MANAGED },
+                patch: {
+                    '/api/environments/:team_id/messaging_templates/:id/': async ({
+                        request,
+                    }: {
+                        request: Request
+                    }) => {
+                        patchBodies.push(await request.json())
+                        return [200, { ...CODE_MANAGED, managed_by: 'gui' }]
+                    },
+                },
+                post: {
+                    '/api/environments/:team_id/messaging_templates/': async ({ request }: { request: Request }) => {
+                        createBodies.push(await request.json())
+                        return [201, { id: 'copy-id' }]
+                    },
+                },
+            })
+            logic = messageTemplateLogic({ id: 'existing-id' })
+            logic.mount()
+            await expectLogic(logic).toDispatchActions(['loadTemplateSuccess'])
+        })
+
+        it('keeps its fields and never saves when they change', async () => {
+            await expectLogic(logic, () => {
+                logic.actions.setTemplateValue('content.email.subject', 'Edited here')
+                logic.actions.setTemplateValues({ name: 'Renamed here' })
+                logic.actions.submitTemplate()
+            }).toFinishAllListeners()
+
+            await expectLogic(logic).toMatchValues({ templateChanged: false })
+            expect(logic.values.template.name).toBe('Welcome')
+            expect(patchBodies).toEqual([])
+        })
+
+        it('duplicates as a copy without its key, ownership, source or hash', async () => {
+            await expectLogic(logic, () => {
+                logic.actions.duplicateTemplate()
+            }).toFinishAllListeners()
+
+            expect(createBodies).toEqual([
+                { name: 'Welcome (copy)', description: 'Sent after signup', content: CODE_MANAGED.content },
+            ])
+        })
+
+        it('becomes editable once released', async () => {
+            await expectLogic(logic, () => {
+                logic.actions.releaseTemplate()
+            })
+                .toDispatchActions(['releaseTemplateSuccess'])
+                .toFinishAllListeners()
+
+            expect(patchBodies).toEqual([{ managed_by: 'gui' }])
+            logic.actions.setTemplateValue('name', 'Edited here')
+            await expectLogic(logic).toMatchValues({ isCodeManaged: false, templateChanged: true })
+
+            await expectLogic(logic, () => {
+                logic.actions.submitTemplate()
+            })
+                .toDispatchActions(['saveTemplateSuccess'])
+                .toFinishAllListeners()
+            expect(patchBodies[1]).toMatchObject({ name: 'Edited here' })
+            const serverOwnedFieldsSent = [
+                'key',
+                'managed_by',
+                'source_repository',
+                'source_path',
+                'source_ref',
+            ].filter((field) => field in patchBodies[1])
+            expect(serverOwnedFieldsSent).toEqual([])
+        })
+    })
+
+    describe('claimed back by an upload while editing', () => {
+        const draft = { ...CODE_MANAGED.content, email: { ...CODE_MANAGED.content.email, subject: 'Draft subject' } }
+        const claimed = { ...CODE_MANAGED, transactional_hog_flow_id: 'flow-id', draft_content: null }
+        let serverTemplate: Record<string, unknown>
+        let reloadStatus: number
+        let createBodies: Record<string, unknown>[]
+
+        const editTemplate = (): void => {
+            logic.actions.setTemplateValue('name', 'Welcome, edited here')
+            logic.actions.setTemplateValue('content.email.subject', 'Edited subject')
+        }
+
+        const autosave = async (): Promise<void> => {
+            await jest.advanceTimersByTimeAsync(1500)
+        }
+
+        const autosaveThenClaim = async (): Promise<void> => {
+            await autosave()
+            await expectLogic(logic).toDispatchActions(['saveDraftDone'])
+            serverTemplate = claimed
+        }
+
+        const publish = async (): Promise<void> => {
+            await autosaveThenClaim()
+            logic.actions.submitTemplate()
+        }
+
+        const discardDraft = async (): Promise<void> => {
+            await autosaveThenClaim()
+            logic.actions.confirmDiscardDraft()
+        }
+
+        const claimThenAutosave = async (): Promise<void> => {
+            serverTemplate = claimed
+            await autosave()
+        }
+
+        const refuse = async (refusal: () => Promise<void>): Promise<void> => {
+            editTemplate()
+            await refusal()
+            await jest.advanceTimersByTimeAsync(3000)
+            await expectLogic(logic).toDispatchActions([
+                reloadStatus === 200 ? 'loadTemplateSuccess' : 'loadTemplateFailure',
+            ])
+        }
+
+        beforeEach(async () => {
+            serverTemplate = { ...claimed, managed_by: 'gui', draft_content: draft }
+            reloadStatus = 200
+            createBodies = []
+            const patch = async ({ request }: { request: Request }): Promise<[number, Record<string, unknown>]> => {
+                const body = (await request.json()) as Record<string, unknown>
+                if (serverTemplate.managed_by === 'code') {
+                    return [
+                        403,
+                        { type: 'invalid_request', code: 'immutable', detail: 'This template is managed by code.' },
+                    ]
+                }
+                return [200, { ...serverTemplate, ...body, updated_at: '2026-01-01T00:01:00Z' }]
+            }
+            useMocks({
+                get: {
+                    '/api/environments/:team_id/messaging_templates/:id/': () => [reloadStatus, serverTemplate],
+                },
+                patch: {
+                    '/api/environments/:team_id/messaging_templates/:id/': patch,
+                    '/api/projects/:team_id/messaging_templates/:id/': patch,
+                },
+                post: {
+                    '/api/environments/:team_id/messaging_templates/': async ({ request }: { request: Request }) => {
+                        createBodies.push(await request.json())
+                        return [201, { id: 'copy-id' }]
+                    },
+                },
+            })
+            logic = messageTemplateLogic({ id: 'existing-id' })
+            logic.mount()
+            await expectLogic(logic).toDispatchActions(['loadTemplateSuccess'])
+            jest.useFakeTimers()
+        })
+
+        afterEach(() => {
+            jest.useRealTimers()
+        })
+
+        const keptEdits = expect.objectContaining({ name: 'Welcome, edited here' })
+
+        it.each([
+            { refusal: 'an autosave', refuse: claimThenAutosave, reload: 'succeeds', status: 200, edits: keptEdits },
+            { refusal: 'an autosave', refuse: claimThenAutosave, reload: 'fails', status: 500, edits: keptEdits },
+            { refusal: 'a publish', refuse: publish, reload: 'succeeds', status: 200, edits: keptEdits },
+            { refusal: 'a publish', refuse: publish, reload: 'fails', status: 500, edits: keptEdits },
+            { refusal: 'a draft discard', refuse: discardDraft, reload: 'fails', status: 500, edits: null },
+        ])(
+            'turns read-only when $refusal is refused and the reload $reload',
+            async ({ refuse: refusal, status, edits }) => {
+                reloadStatus = status
+                await refuse(refusal)
+
+                await expectLogic(logic).toMatchValues({
+                    isCodeManaged: true,
+                    hasDraft: false,
+                    hasUnsavedChanges: false,
+                    refusedEdits: edits,
+                })
+                expect(logic.values.template.name).toBe('Welcome')
+            }
+        )
+
+        it.each([
+            {
+                requests: 'an autosave and a publish',
+                refuse: async (): Promise<void> => {
+                    serverTemplate = claimed
+                    logic.actions.saveDraft()
+                    logic.actions.submitTemplate()
+                },
+            },
+            {
+                requests: 'an autosave, then a draft discard',
+                refuse: async (): Promise<void> => {
+                    await claimThenAutosave()
+                    logic.actions.confirmDiscardDraft()
+                },
+            },
+        ])('keeps the edits the first refusal rescued when $requests are refused', async ({ refuse: refusal }) => {
+            await refuse(refusal)
+            await expectLogic(logic).toFinishAllListeners()
+
+            await expectLogic(logic).toMatchValues({ isCodeManaged: true, refusedEdits: keptEdits })
+        })
+
+        it('keeps the edits from before and after a release when a second upload refuses them', async () => {
+            await refuse(claimThenAutosave)
+            serverTemplate = { ...claimed, managed_by: 'gui' }
+            await expectLogic(logic, () => {
+                logic.actions.releaseTemplate()
+            }).toDispatchActions(['releaseTemplateSuccess'])
+            await expectLogic(logic).toMatchValues({ refusedEdits: null, hasUnsavedChanges: true })
+
+            logic.actions.setTemplateValue('description', 'Edited after the release')
+            await claimThenAutosave()
+            await expectLogic(logic).toDispatchActions(['claimedByUpload']).toFinishAllListeners()
+
+            await expectLogic(logic).toMatchValues({
+                isCodeManaged: true,
+                refusedEdits: expect.objectContaining({
+                    name: 'Welcome, edited here',
+                    description: 'Edited after the release',
+                }),
+            })
+        })
+
+        it('asks before a navigation drops the refused edits', async () => {
+            const confirmSpy = jest.spyOn(window, 'confirm').mockReturnValue(false)
+            await refuse(claimThenAutosave)
+
+            router.actions.push('/workflows/library')
+
+            expect(confirmSpy).toHaveBeenCalledTimes(1)
+            confirmSpy.mockRestore()
+        })
+
+        it('duplicates the unsaved edits without its key, ownership, source or hash', async () => {
+            await refuse(claimThenAutosave)
+
+            await expectLogic(logic, () => {
+                logic.actions.duplicateWithMyChanges()
+            }).toFinishAllListeners()
+
+            expect(createBodies).toEqual([
+                {
+                    name: 'Welcome, edited here (copy)',
+                    description: 'Sent after signup',
+                    content: { ...draft, email: { ...draft.email, subject: 'Edited subject' } },
+                },
+            ])
+            await expectLogic(logic).toMatchValues({ refusedEdits: null })
+        })
+    })
+
     describe('make transactional', () => {
         test.each([
             ['an edit made while it runs', true],
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
index f32d1d25a109..7062145d3a55 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
@@ -8,6 +8,7 @@ import posthog from 'posthog-js'
 import { LemonDialog } from '@posthog/lemon-ui'
 
 import api from 'lib/api'
+import { ApiError } from 'lib/api-error'
 import { dayjs } from 'lib/dayjs'
 import { integrationsLogic } from 'lib/integrations/integrationsLogic'
 import { lemonToast } from 'lib/lemon-ui/LemonToast'
@@ -21,7 +22,10 @@ import {
     messagingTemplatesMakeTransactionalCreate,
     messagingTemplatesPartialUpdate,
 } from 'products/messaging/frontend/generated/api'
-import type { MessageTemplateContentApi } from 'products/messaging/frontend/generated/api.schemas'
+import type {
+    MessageTemplateContentApi,
+    TemplateManagedByEnumApi,
+} from 'products/messaging/frontend/generated/api.schemas'
 import { resourceEditedLogic } from 'products/notifications/frontend/resourceEditedLogic'
 
 import {
@@ -33,9 +37,11 @@ import type { EmailTemplate } from '../../../../frontend/src/scenes/hog-function
 import type { HogFunctionType, ResourceEditedEvent, UserBasicType } from '../../../../frontend/src/types'
 import type { IntegrationType } from '../../../../frontend/src/types'
 import { workflowLogic } from '../Workflows/workflowLogic'
+import { TemplateSource, isCodeManagedTemplate, templateSource, withoutServerOwnedFields } from './codeManagedTemplate'
 import { NEW_TEMPLATE } from './constants'
 import { newTemplateAgentLogic } from './newTemplateAgentLogic'
 import { omitNullDesign } from './omitNullDesign'
+import { templateCopy } from './templateCopy'
 import { TemplateSection, templateLibraryUrl, templateSectionFor, templateUrlInSection } from './templateSection'
 import { MessageTemplate } from './types'
 
@@ -43,6 +49,10 @@ export type TransactionalTemplateTab = 'design' | 'metrics' | 'sends' | 'version
 
 type TemplateContent = MessageTemplate['content']
 
+function isClaimedByUpload(error: unknown): boolean {
+    return error instanceof ApiError && error.code === 'immutable'
+}
+
 /** The form edits the draft when there is one. The draft field stays off the form value, so a publish never sends it. */
 function splitDraft(template: MessageTemplate): {
     form: MessageTemplate
@@ -70,7 +80,9 @@ export interface messageTemplateLogicValues {
     externallyEdited: boolean
     hasDraft: boolean
     hasUnsavedChanges: boolean
+    isCodeManaged: boolean
     isDiscardingDraft: boolean
+    isDuplicating: boolean
     isMakingTransactional: boolean
     isSavingDraft: boolean
     isSavingSensitive: boolean
@@ -84,6 +96,7 @@ export interface messageTemplateLogicValues {
     messageLoading: boolean
     originalTemplate: MessageTemplate
     publishedContent: TemplateContent | null
+    refusedEdits: MessageTemplate | null
     savedDraft: TemplateContent | null
     section: TemplateSection
     showTemplateErrors: boolean
@@ -101,8 +114,13 @@ export interface messageTemplateLogicValues {
             description: string
             draft_content?: MessageTemplateContentApi | null | undefined
             id: string
+            key?: string | null | undefined
+            managed_by?: TemplateManagedByEnumApi | null | undefined
             name: string
             sensitive?: boolean | undefined
+            source_path?: string | null | undefined
+            source_ref?: string | null | undefined
+            source_repository?: string | null | undefined
             tags?: string[] | undefined
             transactional_hog_flow_id?: string | null | undefined
             updated_at: string | null
@@ -113,6 +131,7 @@ export interface messageTemplateLogicValues {
     templateLoading: boolean
     templateManualErrors: Record<string, any>
     templatePickerOpen: boolean
+    templateSource: TemplateSource | null
     templateTouched: boolean
     templateTouches: Record<string, boolean>
     templateValidationErrors: DeepPartialMap<
@@ -126,8 +145,13 @@ export interface messageTemplateLogicValues {
             description: string
             draft_content?: MessageTemplateContentApi | null | undefined
             id: string
+            key?: string | null | undefined
+            managed_by?: TemplateManagedByEnumApi | null | undefined
             name: string
             sensitive?: boolean | undefined
+            source_path?: string | null | undefined
+            source_ref?: string | null | undefined
+            source_repository?: string | null | undefined
             tags?: string[] | undefined
             transactional_hog_flow_id?: string | null | undefined
             updated_at: string | null
@@ -146,6 +170,9 @@ export interface messageTemplateLogicActions {
     autoSaveDraft: () => {
         value: true
     }
+    claimedByUpload: (keepEdits: boolean) => {
+        keepEdits: boolean
+    }
     confirmDiscardDraft: () => {
         value: true
     }
@@ -161,6 +188,12 @@ export interface messageTemplateLogicActions {
     duplicateTemplate: () => {
         value: true
     }
+    duplicateTemplateDone: () => {
+        value: true
+    }
+    duplicateWithMyChanges: () => {
+        value: true
+    }
     keepMyTemplateVersion: () => {
         value: true
     }
@@ -200,6 +233,21 @@ export interface messageTemplateLogicActions {
     makeTransactionalDone: (hogFlowId: string | null) => {
         hogFlowId: string | null
     }
+    releaseTemplate: () => any
+    releaseTemplateFailure: (
+        error: string,
+        errorObject?: any
+    ) => {
+        error: string
+        errorObject?: any
+    }
+    releaseTemplateSuccess: (
+        template: MessageTemplate,
+        payload?: any
+    ) => {
+        template: MessageTemplate
+        payload?: any
+    }
     replayDeferredExternalEdit: () => {
         value: true
     }
@@ -213,8 +261,13 @@ export interface messageTemplateLogicActions {
         description: string
         draft_content?: MessageTemplateContentApi | null | undefined
         id: string
+        key?: string | null | undefined
+        managed_by?: TemplateManagedByEnumApi | null | undefined
         name: string
         sensitive?: boolean | undefined
+        source_path?: string | null | undefined
+        source_ref?: string | null | undefined
+        source_repository?: string | null | undefined
         tags?: string[] | undefined
         transactional_hog_flow_id?: string | null | undefined
         updated_at: string | null
@@ -229,8 +282,13 @@ export interface messageTemplateLogicActions {
             description: string
             draft_content?: MessageTemplateContentApi | null | undefined
             id: string
+            key?: string | null | undefined
+            managed_by?: TemplateManagedByEnumApi | null | undefined
             name: string
             sensitive?: boolean | undefined
+            source_path?: string | null | undefined
+            source_ref?: string | null | undefined
+            source_repository?: string | null | undefined
             tags?: string[] | undefined
             transactional_hog_flow_id?: string | null | undefined
             updated_at: string | null
@@ -292,6 +350,9 @@ export interface messageTemplateLogicActions {
     setOriginalTemplate: (template: MessageTemplate) => {
         template: MessageTemplate
     }
+    setRefusedEdits: (edits: MessageTemplate | null) => {
+        edits: MessageTemplate | null
+    }
     setSensitive: (sensitive: boolean) => {
         sensitive: boolean
     }
@@ -328,8 +389,13 @@ export interface messageTemplateLogicActions {
             description: string
             draft_content?: MessageTemplateContentApi | null | undefined
             id: string
+            key?: string | null | undefined
+            managed_by?: TemplateManagedByEnumApi | null | undefined
             name: string
             sensitive?: boolean | undefined
+            source_path?: string | null | undefined
+            source_ref?: string | null | undefined
+            source_repository?: string | null | undefined
             tags?: string[] | undefined
             transactional_hog_flow_id?: string | null | undefined
             updated_at: string | null
@@ -345,8 +411,13 @@ export interface messageTemplateLogicActions {
             description: string
             draft_content?: MessageTemplateContentApi | null | undefined
             id: string
+            key?: string | null | undefined
+            managed_by?: TemplateManagedByEnumApi | null | undefined
             name: string
             sensitive?: boolean | undefined
+            source_path?: string | null | undefined
+            source_ref?: string | null | undefined
+            source_repository?: string | null | undefined
             tags?: string[] | undefined
             transactional_hog_flow_id?: string | null | undefined
             updated_at: string | null
@@ -375,8 +446,13 @@ export interface messageTemplateLogicActions {
         description: string
         draft_content?: MessageTemplateContentApi | null | undefined
         id: string
+        key?: string | null | undefined
+        managed_by?: TemplateManagedByEnumApi | null | undefined
         name: string
         sensitive?: boolean | undefined
+        source_path?: string | null | undefined
+        source_ref?: string | null | undefined
+        source_repository?: string | null | undefined
         tags?: string[] | undefined
         transactional_hog_flow_id?: string | null | undefined
         updated_at: string | null
@@ -391,8 +467,13 @@ export interface messageTemplateLogicActions {
             description: string
             draft_content?: MessageTemplateContentApi | null | undefined
             id: string
+            key?: string | null | undefined
+            managed_by?: TemplateManagedByEnumApi | null | undefined
             name: string
             sensitive?: boolean | undefined
+            source_path?: string | null | undefined
+            source_ref?: string | null | undefined
+            source_repository?: string | null | undefined
             tags?: string[] | undefined
             transactional_hog_flow_id?: string | null | undefined
             updated_at: string | null
@@ -408,8 +489,13 @@ export interface messageTemplateLogicActions {
         description: string
         draft_content?: MessageTemplateContentApi | null | undefined
         id: string
+        key?: string | null | undefined
+        managed_by?: TemplateManagedByEnumApi | null | undefined
         name: string
         sensitive?: boolean | undefined
+        source_path?: string | null | undefined
+        source_ref?: string | null | undefined
+        source_repository?: string | null | undefined
         tags?: string[] | undefined
         transactional_hog_flow_id?: string | null | undefined
         updated_at: string | null
@@ -424,8 +510,13 @@ export interface messageTemplateLogicActions {
             description: string
             draft_content?: MessageTemplateContentApi | null | undefined
             id: string
+            key?: string | null | undefined
+            managed_by?: TemplateManagedByEnumApi | null | undefined
             name: string
             sensitive?: boolean | undefined
+            source_path?: string | null | undefined
+            source_ref?: string | null | undefined
+            source_repository?: string | null | undefined
             tags?: string[] | undefined
             transactional_hog_flow_id?: string | null | undefined
             updated_at: string | null
@@ -476,6 +567,8 @@ export interface messageTemplateLogicMeta {
             originalTemplate: MessageTemplate,
             draftOutOfDate: boolean
         ) => boolean
+        isCodeManaged: (originalTemplate: MessageTemplate) => boolean
+        templateSource: (originalTemplate: MessageTemplate) => TemplateSource | null
     }
 }
 
@@ -486,6 +579,17 @@ export type messageTemplateLogicType = MakeLogicType<
     messageTemplateLogicMeta
 >
 
+async function createCopyOf(source: MessageTemplate): Promise<MessageTemplate | null> {
+    try {
+        const copy = await api.messaging.createTemplate(templateCopy(source))
+        lemonToast.success('Template duplicated successfully')
+        return copy
+    } catch (error: any) {
+        lemonToast.error(error?.detail || 'Failed to duplicate template')
+        return null
+    }
+}
+
 export const messageTemplateLogic = kea<messageTemplateLogicType>([
     path(['products', 'workflows', 'frontend', 'messageTemplateLogic']),
     props({} as MessageTemplateLogicProps),
@@ -505,6 +609,10 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
         setTemplate: (template: MessageTemplate) => ({ template }),
         setOriginalTemplate: (template: MessageTemplate) => ({ template }),
         duplicateTemplate: true,
+        duplicateTemplateDone: true,
+        setRefusedEdits: (edits: MessageTemplate | null) => ({ edits }),
+        claimedByUpload: (keepEdits: boolean) => ({ keepEdits }),
+        duplicateWithMyChanges: true,
         deleteTemplate: true,
         setTemplatePickerOpen: (open: boolean) => ({ open }),
         saveTags: (tags: string[]) => ({ tags }),
@@ -556,7 +664,9 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                 },
             }),
             submit: async (template) => {
-                actions.saveTemplate(template)
+                if (!values.isCodeManaged) {
+                    actions.saveTemplate(template)
+                }
             },
         },
     })),
@@ -619,6 +729,20 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                 discardDraftDone: () => false,
             },
         ],
+        isDuplicating: [
+            false,
+            {
+                duplicateTemplate: () => true,
+                duplicateWithMyChanges: () => true,
+                duplicateTemplateDone: () => false,
+            },
+        ],
+        refusedEdits: [
+            null as MessageTemplate | null,
+            {
+                setRefusedEdits: (_, { edits }) => edits,
+            },
+        ],
         transactionalTab: [
             'design' as TransactionalTemplateTab,
             {
@@ -719,6 +843,14 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                       draftOutOfDate
                     : templateChanged,
         ],
+        isCodeManaged: [
+            (s) => [s.originalTemplate],
+            (originalTemplate: MessageTemplate): boolean => isCodeManagedTemplate(originalTemplate),
+        ],
+        templateSource: [
+            (s) => [s.originalTemplate],
+            (originalTemplate: MessageTemplate): TemplateSource | null => templateSource(originalTemplate),
+        ],
     }),
     loaders(({ props, actions }) => ({
         template: {
@@ -737,9 +869,14 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                 // Saving the content publishes it, and the server clears the draft. The sensitive setting
                 // and the tags each save on their own, so a publish never sends them and can't undo a
                 // change made in another tab since this one loaded the template.
-                const payload = template.content?.email
-                    ? { ...template, content: { ...template.content, email: omitNullDesign(template.content.email) } }
-                    : template
+                const payload = withoutServerOwnedFields(
+                    template.content?.email
+                        ? {
+                              ...template,
+                              content: { ...template.content, email: omitNullDesign(template.content.email) },
+                          }
+                        : template
+                )
                 const { sensitive: _sensitive, tags: _tags, ...content } = payload
                 const saved =
                     template.id === 'new'
@@ -749,6 +886,7 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                 actions.setDraftState(draft, published)
                 return form
             },
+            releaseTemplate: () => api.messaging.updateTemplate(props.id, { managed_by: 'gui' }),
         },
         message: {
             loadMessage: async () => {
@@ -803,7 +941,10 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
             actions.setExternallyEdited(false)
             actions.autoSaveDraft()
         },
-        setTemplateValue: () => actions.autoSaveDraft(),
+        setTemplateValue: () =>
+            values.isCodeManaged ? actions.resetTemplate(values.originalTemplate) : actions.autoSaveDraft(),
+        setTemplateValues: () =>
+            values.isCodeManaged ? actions.resetTemplate(values.originalTemplate) : actions.autoSaveDraft(),
         saveTags: async ({ tags }, breakpoint) => {
             // An unsaved template has no row yet, so its tags ride the create.
             if (!props.id || props.id === 'new') {
@@ -829,7 +970,6 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
             actions.setTemplate({ ...values.template, tags: updated.tags })
             actions.setOriginalTemplate({ ...values.originalTemplate, tags: updated.tags })
         },
-        setTemplateValues: () => actions.autoSaveDraft(),
         autoSaveDraft: async (_, breakpoint) => {
             if (!values.draftsEnabled) {
                 return
@@ -856,9 +996,13 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                     draft_content: content as MessageTemplateContentApi,
                 })
                 actions.saveDraftDone(content, updated.updated_at)
-            } catch {
+            } catch (error) {
                 actions.saveDraftFailed()
-                lemonToast.error("Couldn't save your draft. Your changes are still in the editor.")
+                if (isClaimedByUpload(error)) {
+                    actions.claimedByUpload(true)
+                } else {
+                    lemonToast.error("Couldn't save your draft. Your changes are still in the editor.")
+                }
             }
         },
         saveDraftDone: ({ updatedAt }) => {
@@ -899,12 +1043,31 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                     updated_at: updated.updated_at,
                 })
                 actions.resetTemplate({ ...values.template, content: published, updated_at: updated.updated_at })
-            } catch {
-                lemonToast.error("Couldn't discard your draft. Try again.")
+            } catch (error) {
+                if (isClaimedByUpload(error)) {
+                    actions.claimedByUpload(false)
+                } else {
+                    lemonToast.error("Couldn't discard your draft. Try again.")
+                }
             }
             actions.discardDraftDone()
             actions.replayDeferredExternalEdit()
         },
+        releaseTemplateSuccess: ({ template }) => {
+            actions.resetTemplate(template)
+            actions.setOriginalTemplate(template)
+            const edits = values.refusedEdits
+            if (edits) {
+                actions.setRefusedEdits(null)
+                actions.setTemplateValues({ name: edits.name, description: edits.description, content: edits.content })
+            }
+            lemonToast.success('This template is no longer managed by code. You can edit it here.')
+            actions.replayDeferredExternalEdit()
+        },
+        releaseTemplateFailure: ({ errorObject }) => {
+            lemonToast.error(errorObject?.detail ?? 'Could not stop managing this template in code. Please try again.')
+            actions.replayDeferredExternalEdit()
+        },
         makeTransactional: async () => {
             try {
                 const updated = await messagingTemplatesMakeTransactionalCreate(
@@ -992,7 +1155,23 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                 lemonToast.error(errors.content.email.from.email)
             }
         },
+        claimedByUpload: ({ keepEdits }) => {
+            const published = values.publishedContent ?? values.originalTemplate.content
+            const claimed = { ...values.originalTemplate, content: published, managed_by: 'code' as const }
+            if (keepEdits && !values.refusedEdits) {
+                actions.setRefusedEdits(values.template)
+            }
+            actions.setExternallyEdited(false)
+            actions.setDraftState(null, published)
+            actions.setOriginalTemplate(claimed)
+            actions.resetTemplate(claimed)
+            actions.loadTemplate()
+        },
         saveTemplateFailure: ({ errorObject }) => {
+            if (isClaimedByUpload(errorObject)) {
+                actions.claimedByUpload(true)
+                return
+            }
             actions.replayDeferredExternalEdit()
             // A 404 means the template no longer resolves for this environment - it was soft-deleted,
             // or it belongs to a different environment than the one currently selected.
@@ -1038,22 +1217,27 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
                 },
             })
         },
-        duplicateTemplate: async () => {
+        duplicateTemplate: async (_, breakpoint) => {
             if (values.hasUnsavedChanges) {
                 lemonToast.error('Please save your changes before duplicating')
+                actions.duplicateTemplateDone()
                 return
             }
-            const template = values.template
-            try {
-                const duplicatedTemplate = await api.messaging.createTemplate({
-                    name: `${template.name} (copy)`,
-                    description: template.description,
-                    content: template.content,
-                })
-                lemonToast.success('Template duplicated successfully')
-                router.actions.push(templateUrlInSection(duplicatedTemplate.id, values.section))
-            } catch {
-                lemonToast.error('Failed to duplicate template')
+            const copy = await createCopyOf(values.template)
+            breakpoint()
+            actions.duplicateTemplateDone()
+            if (copy) {
+                router.actions.push(templateUrlInSection(copy.id, values.section))
+            }
+        },
+        duplicateWithMyChanges: async (_, breakpoint) => {
+            const edits = values.refusedEdits
+            const copy = edits && (await createCopyOf(edits))
+            breakpoint()
+            actions.duplicateTemplateDone()
+            if (copy) {
+                actions.setRefusedEdits(null)
+                router.actions.push(templateUrlInSection(copy.id, values.section))
             }
         },
         deleteTemplate: async () => {
@@ -1105,7 +1289,7 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
         // Guards both new and existing templates - a brand-new template only exists in form
         // state until "Create" is pressed, so leaving without saving would discard it entirely.
         enabled: (newLocation) => {
-            if (!values.hasUnsavedChanges) {
+            if (!values.hasUnsavedChanges && !values.refusedEdits) {
                 return false
             }
             // Allow same-path changes (e.g. query params) through without warning.
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplatesLogic.ts b/products/workflows/frontend/TemplateLibrary/messageTemplatesLogic.ts
index e1d69eb29f7f..b98f320dcc85 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplatesLogic.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplatesLogic.ts
@@ -9,6 +9,7 @@ import { teamLogic } from 'scenes/teamLogic'
 import { tagsModel } from '~/models/tagsModel'
 
 import { filterMessageTemplates } from './filterMessageTemplates'
+import { templateCopy } from './templateCopy'
 import { MessageTemplate } from './types'
 
 export type { MessageTemplate }
@@ -240,11 +241,7 @@ export const messageTemplatesLogic = kea<messageTemplatesLogicType>([
                 },
                 duplicateTemplate: async (template: MessageTemplate) => {
                     try {
-                        const duplicatedTemplate = await api.messaging.createTemplate({
-                            name: `${template.name} (copy)`,
-                            description: template.description,
-                            content: template.content,
-                        })
+                        const duplicatedTemplate = await api.messaging.createTemplate(templateCopy(template))
                         lemonToast.success('Template duplicated successfully')
                         return [...values.templates, duplicatedTemplate]
                     } catch {
diff --git a/products/workflows/frontend/TemplateLibrary/releaseTemplateDialog.ts b/products/workflows/frontend/TemplateLibrary/releaseTemplateDialog.ts
new file mode 100644
index 000000000000..d4535a774522
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/releaseTemplateDialog.ts
@@ -0,0 +1,17 @@
+import { LemonDialog } from '@posthog/lemon-ui'
+
+import { MessageTemplate } from './types'
+
+export function openReleaseTemplateDialog(template: MessageTemplate, onRelease: () => void): void {
+    const nextUpload = template.source_path ? `The next upload of ${template.source_path}` : 'The next upload from code'
+    LemonDialog.open({
+        title: 'Stop managing this template in code?',
+        description: `You can edit this template here again. ${nextUpload} makes it managed by code again and replaces changes made here.`,
+        primaryButton: {
+            children: 'Stop managing in code',
+            'data-attr': 'message-template-release-confirm',
+            onClick: onRelease,
+        },
+        secondaryButton: { children: 'Cancel' },
+    })
+}
diff --git a/products/workflows/frontend/TemplateLibrary/templateCopy.ts b/products/workflows/frontend/TemplateLibrary/templateCopy.ts
new file mode 100644
index 000000000000..8bf457ae9ba1
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/templateCopy.ts
@@ -0,0 +1,9 @@
+import { MessageTemplate } from './types'
+
+export function templateCopy(template: MessageTemplate): Partial<MessageTemplate> {
+    return {
+        name: `${template.name} (copy)`,
+        description: template.description,
+        content: template.content,
+    }
+}
diff --git a/products/workflows/frontend/TemplateLibrary/types.ts b/products/workflows/frontend/TemplateLibrary/types.ts
index c55a39f5e7a9..dbedb4239f85 100644
--- a/products/workflows/frontend/TemplateLibrary/types.ts
+++ b/products/workflows/frontend/TemplateLibrary/types.ts
@@ -19,4 +19,9 @@ export interface MessageTemplate {
     draft_content?: MessageTemplateApi['draft_content']
     sensitive?: MessageTemplateApi['sensitive']
     tags?: MessageTemplateApi['tags']
+    key?: MessageTemplateApi['key']
+    managed_by?: MessageTemplateApi['managed_by']
+    source_repository?: MessageTemplateApi['source_repository']
+    source_path?: MessageTemplateApi['source_path']
+    source_ref?: MessageTemplateApi['source_ref']
 }

From d161fa7ff1510d0de9e0f3c4916511402c94551f Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 25 Oct 2026 07:33:53 +0000
Subject: [PATCH 08/42] feat(workflows): show the sender on a read-only email
 template

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../email-templater/EmailSenderDetails.tsx    | 38 ++++++++++++
 .../email-templater/EmailSenderSummary.tsx    | 22 +++----
 .../ReadOnlyTemplatePreview.stories.tsx       | 22 ++++++-
 .../ReadOnlyTemplatePreview.test.tsx          | 62 +++++++++++++++++++
 .../ReadOnlyTemplatePreview.tsx               | 19 ++++++
 5 files changed, 147 insertions(+), 16 deletions(-)
 create mode 100644 frontend/src/scenes/hog-functions/email-templater/EmailSenderDetails.tsx
 create mode 100644 products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx

diff --git a/frontend/src/scenes/hog-functions/email-templater/EmailSenderDetails.tsx b/frontend/src/scenes/hog-functions/email-templater/EmailSenderDetails.tsx
new file mode 100644
index 000000000000..b31cb0ceaf9d
--- /dev/null
+++ b/frontend/src/scenes/hog-functions/email-templater/EmailSenderDetails.tsx
@@ -0,0 +1,38 @@
+import { cn } from 'lib/utils/css-classes'
+
+import { EmailSender, senderAddressError, senderFrom, senderIntegrationFor } from './emailSenderFields'
+import { EmailTemplate } from './types'
+
+export function EmailSenderDetails({
+    email,
+    senders,
+    placeholder,
+    className,
+}: {
+    email: Partial<EmailTemplate>
+    senders: EmailSender[]
+    placeholder: string
+    className?: string
+}): JSX.Element {
+    const from = senderFrom(email)
+    const sender = senderIntegrationFor(email, senders)
+    const name = from.name || sender?.config?.name
+    const address = from.email || sender?.config?.email
+    const replyTo = email.replyTo || sender?.config?.reply_to
+    const addressError = senderAddressError(from.email, sender)
+
+    return (
+        <div className={cn('min-w-0', className)}>
+            {sender ? (
+                <div className="truncate">
+                    {name ? <span className="font-semibold">{name}</span> : null}
+                    <span className="text-secondary">{name ? ` <${address}>` : address}</span>
+                </div>
+            ) : (
+                <div className="text-secondary">{placeholder}</div>
+            )}
+            {replyTo ? <div className="text-xs text-secondary truncate">{`Replies go to ${replyTo}`}</div> : null}
+            {addressError ? <div className="text-xs text-danger">{addressError}</div> : null}
+        </div>
+    )
+}
diff --git a/frontend/src/scenes/hog-functions/email-templater/EmailSenderSummary.tsx b/frontend/src/scenes/hog-functions/email-templater/EmailSenderSummary.tsx
index a59fe39c9031..a79491c2119e 100644
--- a/frontend/src/scenes/hog-functions/email-templater/EmailSenderSummary.tsx
+++ b/frontend/src/scenes/hog-functions/email-templater/EmailSenderSummary.tsx
@@ -6,6 +6,7 @@ import { LemonButton, LemonDropdown, LemonLabel } from '@posthog/lemon-ui'
 
 import { integrationsLogic } from 'lib/integrations/integrationsLogic'
 
+import { EmailSenderDetails } from './EmailSenderDetails'
 import { senderAddressError, senderFrom, senderIntegrationFor } from './emailSenderFields'
 import { EmailSenderForm } from './EmailSenderForm'
 import { emailTemplaterLogic } from './emailTemplaterLogic'
@@ -19,26 +20,17 @@ export function EmailSenderSummary(): JSX.Element {
     const senders = (integrations ?? []).filter((integration) => integration.kind === 'email')
     const from = senderFrom(emailTemplate)
     const sender = senderIntegrationFor(emailTemplate, senders)
-    const name = from.name || sender?.config?.name
-    const address = from.email || sender?.config?.email
-    const replyTo = emailTemplate.replyTo || sender?.config?.reply_to
     const addressError = senderAddressError(from.email, sender)
 
     return (
         <div className="flex gap-2 items-center pl-2 pr-1 py-1 border-b shrink-0 min-w-0">
             <LemonLabel className="shrink-0">From</LemonLabel>
-            <div className="flex-1 min-w-0 px-2">
-                {sender ? (
-                    <div className="truncate">
-                        {name ? <span className="font-semibold">{name}</span> : null}
-                        <span className="text-secondary">{name ? ` <${address}>` : address}</span>
-                    </div>
-                ) : (
-                    <div className="text-secondary">Choose who this email comes from</div>
-                )}
-                {replyTo ? <div className="text-xs text-secondary truncate">{`Replies go to ${replyTo}`}</div> : null}
-                {addressError ? <div className="text-xs text-danger">{addressError}</div> : null}
-            </div>
+            <EmailSenderDetails
+                email={emailTemplate}
+                senders={senders}
+                placeholder="Choose who this email comes from"
+                className="flex-1 px-2"
+            />
             <LemonDropdown
                 visible={isEditing}
                 onVisibilityChange={setIsEditing}
diff --git a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx
index e903d57076e1..bebde7e673a1 100644
--- a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx
+++ b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.stories.tsx
@@ -1,10 +1,29 @@
 import { Meta, StoryFn } from '@storybook/react'
 
+import { mswDecorator } from '~/mocks/browser'
+
 import { ReadOnlyTemplatePreview } from './ReadOnlyTemplatePreview'
 
 const meta: Meta<typeof ReadOnlyTemplatePreview> = {
     title: 'Products/Workflows/Template library/Read-only template preview',
     component: ReadOnlyTemplatePreview,
+    decorators: [
+        mswDecorator({
+            get: {
+                '/api/projects/:team_id/integrations/': {
+                    count: 1,
+                    results: [
+                        {
+                            id: 5,
+                            kind: 'email',
+                            display_name: 'Hedgebox',
+                            config: { email: 'hello@example.com', name: 'Hedgebox', reply_to: 'support@example.com' },
+                        },
+                    ],
+                },
+            },
+        }),
+    ],
 }
 export default meta
 
@@ -16,7 +35,8 @@ export const UploadedFromCode: StoryFn<typeof ReadOnlyTemplatePreview> = () => (
             html: '<div style="font-family: sans-serif; padding: 24px"><h1>Welcome, {{ variables.first_name }}</h1><p>Your Hedgebox account is ready.</p><a href="https://example.com/start">Get started</a></div>',
             text: 'Welcome, {{ variables.first_name }}\n\nYour Hedgebox account is ready.\n\nGet started: https://example.com/start',
             design: null,
-            from: '',
+            from: { integrationId: 5, email: 'welcome@example.com', name: 'Hedgebox team' },
+            replyTo: 'help@example.com',
             to: '',
         }}
     />
diff --git a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx
new file mode 100644
index 000000000000..30f14a80ecd2
--- /dev/null
+++ b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx
@@ -0,0 +1,62 @@
+import '@testing-library/jest-dom'
+
+import { cleanup, render, screen } from '@testing-library/react'
+
+import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'
+
+import { useMocks } from '~/mocks/jest'
+import { initKeaTests } from '~/test/init'
+
+import { ReadOnlyTemplatePreview } from './ReadOnlyTemplatePreview'
+
+const SENDER = {
+    id: 5,
+    kind: 'email',
+    display_name: 'Hedgebox',
+    config: { email: 'hello@example.com', name: 'Hedgebox', reply_to: 'support@example.com' },
+}
+
+function email(overrides: Partial<EmailTemplate>): EmailTemplate {
+    return { subject: 'Welcome', html: '<p>Hi</p>', text: 'Hi', design: null, from: '', to: '', ...overrides }
+}
+
+describe('ReadOnlyTemplatePreview', () => {
+    beforeEach(() => {
+        useMocks({ get: { '/api/projects/:team_id/integrations/': { count: 1, results: [SENDER] } } })
+        initKeaTests()
+    })
+
+    afterEach(() => cleanup())
+
+    it.each([
+        {
+            description: "the template's own name, address and reply-to",
+            template: email({
+                from: { integrationId: 5, email: 'billing@example.com', name: 'Billing' },
+                replyTo: 'help@example.com',
+            }),
+            name: 'Billing',
+            address: '<billing@example.com>',
+            replyTo: 'Replies go to help@example.com',
+        },
+        {
+            description: "the sender's defaults when the template sets none",
+            template: email({ from: { integrationId: 5 } }),
+            name: 'Hedgebox',
+            address: '<hello@example.com>',
+            replyTo: 'Replies go to support@example.com',
+        },
+    ])('shows who the email comes from with $description', async ({ template, name, address, replyTo }) => {
+        render(<ReadOnlyTemplatePreview email={template} />)
+
+        expect(await screen.findByText(name)).toBeInTheDocument()
+        expect(screen.getByText(address)).toBeInTheDocument()
+        expect(screen.getByText(replyTo)).toBeInTheDocument()
+    })
+
+    it('says when the template has no sender', async () => {
+        render(<ReadOnlyTemplatePreview email={email({ from: '' })} />)
+
+        expect(await screen.findByText('No sender set')).toBeInTheDocument()
+    })
+})
diff --git a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
index 0b89182a886e..ea100c91f9ea 100644
--- a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
+++ b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
@@ -1,12 +1,31 @@
+import { useValues } from 'kea'
+
+import { LemonSkeleton } from '@posthog/lemon-ui'
+
+import { integrationsLogic } from 'lib/integrations/integrationsLogic'
 import { LemonField } from 'lib/lemon-ui/LemonField'
+import { EmailSenderDetails } from 'scenes/hog-functions/email-templater/EmailSenderDetails'
 import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'
 
 import { EmailHtmlFrame } from './EmailHtmlFrame'
 
+function ReadOnlySender({ email }: { email: EmailTemplate }): JSX.Element {
+    const { integrations } = useValues(integrationsLogic)
+
+    if (!integrations) {
+        return <LemonSkeleton className="h-4 w-48" />
+    }
+    const senders = integrations.filter((integration) => integration.kind === 'email')
+    return <EmailSenderDetails email={email} senders={senders} placeholder="No sender set" />
+}
+
 export function ReadOnlyTemplatePreview({ email }: { email: EmailTemplate }): JSX.Element {
     return (
         <div className="flex flex-col flex-1 gap-4 min-h-0" data-attr="message-template-read-only-preview">
             <div className="flex flex-col gap-3 rounded border bg-surface-primary p-3">
+                <LemonField.Pure label="From" className="gap-1 min-w-0">
+                    <ReadOnlySender email={email} />
+                </LemonField.Pure>
                 <LemonField.Pure label="Subject" className="gap-1 min-w-0">
                     <span className="break-words">{email.subject}</span>
                 </LemonField.Pure>

From 30b4ac875258a07fe9f7652e0767c3b59f7718b9 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 11:55:13 +0000
Subject: [PATCH 09/42] feat(messaging): send an uploaded email template by its
 key

`POST /api/projects/:id/messaging/send/email/` now takes
`template: {key, hash?}` for a template uploaded from code. A send by key
may set `from`, `reply_to` and `capture_engagement`; a send by
`template.id` still refuses them. With `template.hash`, a hash PostHog
doesn't hold answers `409 template_outdated` and sends nothing, and a
superseded hash sends the current content with a `template_superseded`
warning. An unknown key answers `404 template_not_found`, or
`409 template_outdated` when the send carries a hash. A code-managed
template without text sends the text its html holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/facade/contracts.py     |  11 ++
 .../messaging/backend/facade/templates.py     |  17 ++
 .../backend/facade/transactional_email.py     |   4 +
 .../presentation/views/message_templates.py   | 159 +++++++++++++++--
 .../messaging/backend/services/html_text.py   |   2 +-
 .../backend/services/transactional_email.py   |  28 ++-
 .../backend/tests/api/test_template_upload.py |  63 ++++++-
 .../tests/api/test_transactional_email.py     | 165 +++++++++++++++++-
 .../messaging/backend/tests/test_html_text.py |   5 +
 .../frontend/generated/api.schemas.ts         |  39 ++++-
 products/messaging/frontend/generated/api.ts  |   7 +-
 .../messaging/frontend/generated/api.zod.ts   |  30 +++-
 products/workflows/mcp/email_templates.yaml   |   4 +-
 .../schema/generated-tool-definitions.json    |   2 +-
 services/mcp/schema/tool-definitions-all.json |   2 +-
 services/mcp/src/api/generated.ts             |  37 +++-
 .../mcp/src/generated/email_templates/api.ts  |   4 +-
 .../workflows-upload-email-template.json      |   2 +-
 18 files changed, 539 insertions(+), 42 deletions(-)

diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 625b908e1636..3be898299ac5 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -103,6 +103,10 @@ class SenderNotVerified(TransactionalEmailError):
     code = "sender_not_verified"
 
 
+class TemplateOutdated(TransactionalEmailError):
+    code = "template_outdated"
+
+
 @frozen
 class CodeEmail:
     key: str
@@ -114,6 +118,13 @@ class CodeEmail:
     capture_engagement: bool
 
 
+@frozen
+class TemplateSendOptions:
+    sender: str | None
+    reply_to: tuple[str, ...]
+    capture_engagement: bool
+
+
 class DeliveryUnavailable(Exception):
     """The email pipeline did not accept the send. Safe to retry."""
 
diff --git a/products/messaging/backend/facade/templates.py b/products/messaging/backend/facade/templates.py
index eb3190b3e1bc..3bce9b7630fb 100644
--- a/products/messaging/backend/facade/templates.py
+++ b/products/messaging/backend/facade/templates.py
@@ -11,6 +11,7 @@
 from posthog.dataclasses import frozen
 
 from products.messaging.backend.facade.contracts import (
+    ContentHashState,
     TemplateManagedBy,
     TemplateUpload,
     TemplateUploadResult,
@@ -24,6 +25,7 @@
     template_saves,
     template_uploads,
 )
+from products.messaging.backend.services.content_hash import sent_hash_state
 from products.messaging.backend.services.lazy_list import LazyList
 
 
@@ -66,6 +68,12 @@ class UploadedTemplate:
     template: MessageTemplateRow
 
 
+@frozen
+class TemplateToSend:
+    template: MessageTemplateRow
+    hash_state: ContentHashState
+
+
 def _to_contract(row: MessageTemplate) -> MessageTemplateRow:
     return MessageTemplateRow(
         id=row.id,
@@ -103,6 +111,15 @@ def get_template(team_id: int, template_id: UUID | str) -> MessageTemplateRow:
         raise MessageTemplateMissing() from e
 
 
+def find_template_to_send(team_id: int, key: str, sent_hash: str | None) -> TemplateToSend:
+    try:
+        template = templates_service.team_template_with_key(team_id, key)
+    except MessageTemplate.DoesNotExist as e:
+        raise MessageTemplateMissing() from e
+    hash_state = sent_hash_state(sent_hash, template.content_hash, template.superseded_content_hashes or [])
+    return TemplateToSend(template=_to_contract(template), hash_state=hash_state)
+
+
 def team_category_id(team_id: int, category_id: Any) -> UUID:
     """The id of the team's category with that pk, deleted or not.
 
diff --git a/products/messaging/backend/facade/transactional_email.py b/products/messaging/backend/facade/transactional_email.py
index 4aca0e3faa71..3672c5a41f69 100644
--- a/products/messaging/backend/facade/transactional_email.py
+++ b/products/messaging/backend/facade/transactional_email.py
@@ -6,6 +6,8 @@
     EmailDeliveryStatus,
     EmailStatus,
     QueuedEmail,
+    TemplateOutdated,
+    TemplateSendOptions,
     TransactionalEmailError,
 )
 from products.messaging.backend.services.transactional_email import (
@@ -31,6 +33,8 @@
     "EmailDeliveryStatus",
     "EmailStatus",
     "QueuedEmail",
+    "TemplateOutdated",
+    "TemplateSendOptions",
     "TransactionalEmailError",
     "TransactionalEmailStage",
     "get_email_status",
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 049c848b485a..0c24a4e1b799 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -49,6 +49,7 @@
 )
 from products.messaging.backend.facade.contracts import (
     TEMPLATE_KEY_MAX_LENGTH,
+    ContentHashState,
     TemplateManagedBy,
     TemplateManagedByCode,
     TemplateReleasedTo,
@@ -67,6 +68,7 @@
     check_template_key_write,
     check_template_write,
     create_template,
+    find_template_to_send,
     get_template,
     is_adoption,
     is_release,
@@ -85,6 +87,8 @@
     CodeEmail,
     DeliveryUnavailable,
     QueuedEmail,
+    TemplateOutdated,
+    TemplateSendOptions,
     TransactionalEmailError,
     TransactionalEmailStage,
     make_transactional,
@@ -505,11 +509,31 @@ class SendTransactionalEmailSerializer(serializers.Serializer):
 
 class SendEmailTemplateSerializer(serializers.Serializer):
     id = serializers.UUIDField(
-        help_text="ID of the email template to send. The template must be made transactional first."
+        required=False,
+        help_text="ID of the email template to send. The template must be made transactional first. Give either "
+        "`id` or `key`.",
+    )
+    key = serializers.RegexField(
+        r"^[a-zA-Z0-9_-]+$",
+        max_length=TEMPLATE_KEY_MAX_LENGTH,
+        required=False,
+        help_text="Key of the email template to send, as uploaded with `PUT "
+        "/api/projects/@current/messaging_templates/by_key/{key}/`. Give either `id` or `key`.",
+    )
+    hash = serializers.RegexField(
+        r"^v1:[0-9a-f]{64}$",
+        required=False,
+        error_messages={
+            "invalid": "Send the hash as `v1:` and 64 lowercase hex characters, as an upload's `content_hash`."
+        },
+        help_text="Content hash of the template you hold, as an upload's `content_hash`. When PostHog doesn't hold "
+        "that content as the current content or one of the last 100 contents it replaced, the send answers `409 "
+        "template_outdated` and sends nothing. Only with `key`.",
     )
 
 
 CODE_SEND_FIELDS = ("template_key", "subject", "html", "text", "from", "reply_to", "capture_engagement")
+RENDERED_CONTENT_FIELDS = ("subject", "html", "text")
 
 
 class SendEmailSerializer(SendTransactionalEmailSerializer):
@@ -582,8 +606,7 @@ def validate(self, data: dict[str, Any]) -> dict[str, Any]:
         if ("template" in data) == ("template_key" in data):
             raise serializers.ValidationError({"template": "Send either `template` or `template_key`."})
         if "template" in data:
-            if code_field := next((field for field in CODE_SEND_FIELDS if field in sent), None):
-                raise serializers.ValidationError({code_field: "Only a send with `template_key` takes this field."})
+            self._validate_template(data["template"], sent)
             return data
         if unknown := next((field for field in sorted(sent) if field not in self.fields), None):
             raise serializers.ValidationError(
@@ -599,6 +622,16 @@ def validate(self, data: dict[str, Any]) -> dict[str, Any]:
             raise serializers.ValidationError({"html": "A send with `template_key` needs `html`, `text` or both."})
         return data
 
+    @staticmethod
+    def _validate_template(template: Mapping[str, Any], sent: set[str]) -> None:
+        if ("id" in template) == ("key" in template) or ("hash" in template and "id" in template):
+            raise serializers.ValidationError(
+                {"template": "Name the template with either `key`, and an optional `hash`, or `id`."}
+            )
+        refused = CODE_SEND_FIELDS if "id" in template else RENDERED_CONTENT_FIELDS
+        if code_field := next((field for field in refused if field in sent), None):
+            raise serializers.ValidationError({code_field: "Only a send with `template_key` takes this field."})
+
 
 def _is_sender_address(address: str) -> bool:
     if len(address) > SENDER_ADDRESS_MAX_LENGTH or not SENDER_ADDRESS_PATTERN.match(address):
@@ -629,8 +662,35 @@ class SendTransactionalEmailResponseSerializer(serializers.Serializer):
     )
 
 
+class SendEmailWarningSerializer(serializers.Serializer):
+    code = serializers.CharField(help_text="Stable code of the warning, such as `template_superseded`.")
+    detail = serializers.CharField(help_text="What happened.")
+    fix = serializers.CharField(help_text="What you can change, if the warning isn't what you want.")
+
+
+class SendEmailResponseSerializer(SendTransactionalEmailResponseSerializer):
+    warnings = SendEmailWarningSerializer(
+        many=True, required=False, help_text="Things to know about the queued email. Left out when there are none."
+    )
+
+
+TEMPLATE_SUPERSEDED_WARNING = {
+    "code": "template_superseded",
+    "detail": "The email went out with the template's current content, because newer content replaced the content "
+    "you hold.",
+    "fix": "Deploy the newer file, or upload yours to publish it again.",
+}
+
+
+class TemplateKeyNotFound(exceptions.NotFound):
+    default_detail = "No template in this project has this key, so nothing was sent. Upload the template, then send "
+    "again."
+    default_code = "template_not_found"
+
+
 class TransactionalEmailRejected(exceptions.APIException):
     STATUS_BY_CODE = {
+        "template_outdated": 409,
         "quota_limited": 429,
         "idempotency_key_in_flight": 409,
         "idempotency_key_reused": 422,
@@ -742,7 +802,10 @@ def transactional_email_throttles() -> list[BaseThrottle]:
         "verified, the recipient can't be used, or the Idempotency-Key is invalid"
     ),
     404: OpenApiResponse(description="Template not found"),
-    409: OpenApiResponse(description="A request with the same Idempotency-Key is still in progress"),
+    409: OpenApiResponse(
+        description="A request with the same Idempotency-Key is still in progress, or PostHog doesn't hold the "
+        "content `template.hash` describes"
+    ),
     422: OpenApiResponse(
         description="The email can't go out: the recipient is suppressed or can't receive email, sending is "
         "suspended for the project or paused for this transactional email, or the Idempotency-Key was already "
@@ -833,6 +896,7 @@ def _queue_send(
         route: str,
         addressed: dict[str, str],
         unavailable: type[TransactionalEmailUnavailable] = TransactionalEmailUnavailable,
+        warnings: Sequence[dict[str, str]] = (),
     ) -> Response:
         idempotency_key = request.headers.get("Idempotency-Key")
         outcome: dict[str, Any] = {
@@ -852,10 +916,8 @@ def _queue_send(
         finally:
             with transactional_email_stage("usage_event"):
                 self._report_transactional_email_send(request, {**addressed, **outcome})
-        return Response(
-            SendTransactionalEmailResponseSerializer(queued).data,
-            status=status.HTTP_202_ACCEPTED,
-        )
+        data = SendTransactionalEmailResponseSerializer(queued).data
+        return Response({**data, "warnings": list(warnings)} if warnings else data, status=status.HTTP_202_ACCEPTED)
 
     def _require_workflow_editor(self, hog_flow_id: Any) -> None:
         # The template's own access rules don't cover the workflow it sends through, which can carry its own.
@@ -956,7 +1018,8 @@ class UploadTemplateSerializer(serializers.Serializer):
         required=False,
         default=False,
         help_text="Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the "
-        "file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. "
+        "file, or an upload after a send answered `template_outdated`. When newer content already replaced this content, "
+        "the upload changes nothing and answers `superseded`. "
         "The check covers the last 100 different contents the template replaced. Content outside those 100 "
         "publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.",
     )
@@ -982,8 +1045,9 @@ class UploadTemplateResponseSerializer(serializers.Serializer):
         "set `if_not_superseded` and newer content already replaced this content, so nothing was published.",
     )
     content_hash = serializers.CharField(
-        help_text="Hash of the published content, as `v1:` and 64 hex characters. After `superseded` it is the hash "
-        "of the newer content."
+        help_text="Hash of the published content, as `v1:` and 64 hex characters. Send it with an email as "
+        "`template.hash` to check PostHog holds the content you hold. After `superseded` it is the hash of the newer "
+        "content."
     )
     managed_by = serializers.ChoiceField(
         choices=TemplateManagedBy.choices,
@@ -1471,11 +1535,15 @@ def get_throttles(self):
 
     @validated_request(
         SendEmailSerializer,
-        responses=SEND_RESPONSES,
+        responses={
+            **SEND_RESPONSES,
+            202: OpenApiResponse(response=SendEmailResponseSerializer, description="Email queued"),
+        },
         summary="Send a transactional email",
         description=(
-            "Send one transactional email to one recipient. Name a template made transactional in `template.id`, "
-            "and `message_data` fills its `{{ variables.* }}` placeholders. Or send content your code rendered with "
+            "Send one transactional email to one recipient. Name a template made transactional in `template.id`, or "
+            "one uploaded from code in `template.key`, and `message_data` fills its `{{ variables.* }}` placeholders. "
+            "Or send content your code rendered with "
             "a `template_key`, a `subject` and `html` or `text`: PostHog sends it as is, and its metrics and run "
             "history group under the key. Transactional emails skip opt-outs and frequency caps. Send an "
             "`Idempotency-Key` header to retry safely without sending the email twice."
@@ -1487,6 +1555,8 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
         self._end_request_validation()
         if "template_key" in request.validated_data:
             return self._send_code_email(request)
+        if "key" in request.validated_data["template"]:
+            return self._send_template_by_key(request)
         with transactional_email_stage("feature_flag"):
             self._require_transactional_email_flag()
         with transactional_email_stage("template_lookup"):
@@ -1497,6 +1567,50 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
             self.check_object_permissions(request, template)
         return self._queue_transactional_email(request, template, route="send_email")
 
+    def _send_template_by_key(self, request: Any) -> Response:
+        with transactional_email_stage("feature_flag"):
+            require_email_from_code(self.team)
+        data = request.validated_data
+        reference = data["template"]
+        with transactional_email_stage("template_lookup"):
+            try:
+                found = find_template_to_send(self.team_id, reference["key"], reference.get("hash"))
+            except MessageTemplateMissing:
+                if "hash" in reference:
+                    raise TransactionalEmailRejected(TemplateOutdated(TEMPLATE_OUTDATED_DETAIL)) from None
+                raise TemplateKeyNotFound() from None
+            self.check_object_permissions(request, found.template)
+        template = found.template
+        with transactional_email_stage("workflow_access"):
+            if template.transactional_hog_flow_id:
+                self._require_workflow_editor(template.transactional_hog_flow_id)
+        options = _template_send_options(request.data, data)
+
+        def send(idempotency_key: str | None) -> QueuedEmail:
+            if found.hash_state == ContentHashState.OUTDATED:
+                raise TemplateOutdated(TEMPLATE_OUTDATED_DETAIL)
+            return send_transactional_email(
+                self.team,
+                template.id,
+                to=data["to"],
+                distinct_id=_distinct_id(data),
+                message_data=data["message_data"],
+                idempotency_key=idempotency_key,
+                options=options,
+            )
+
+        return self._queue_send(
+            request,
+            send,
+            route="send_email",
+            addressed={
+                "addressed_by": "template_key",
+                "template_id": str(template.id),
+                "hash_state": str(found.hash_state),
+            },
+            warnings=[TEMPLATE_SUPERSEDED_WARNING] if found.hash_state == ContentHashState.SUPERSEDED else [],
+        )
+
     def _send_code_email(self, request: Any) -> Response:
         with transactional_email_stage("feature_flag"):
             require_email_from_code(self.team)
@@ -1533,5 +1647,22 @@ def _send_code_email(self, request: Any) -> Response:
         )
 
 
+TEMPLATE_OUTDATED_DETAIL = (
+    "PostHog doesn't hold the content `template.hash` describes, so nothing was sent. Upload the template, then send "
+    "again."
+)
+TEMPLATE_SEND_OPTION_FIELDS = ("from", "reply_to", "capture_engagement")
+
+
+def _template_send_options(sent: Any, data: Mapping[str, Any]) -> TemplateSendOptions | None:
+    if not isinstance(sent, Mapping) or not any(field in sent for field in TEMPLATE_SEND_OPTION_FIELDS):
+        return None
+    return TemplateSendOptions(
+        sender=data.get("from"),
+        reply_to=tuple(data.get("reply_to", ())),
+        capture_engagement=data.get("capture_engagement", True),
+    )
+
+
 def _distinct_id(data: Mapping[str, Any]) -> str | None:
     return data.get("distinct_id") or (data.get("identifiers") or {}).get("distinct_id") or None
diff --git a/products/messaging/backend/services/html_text.py b/products/messaging/backend/services/html_text.py
index 8934a600f3d8..a769db1d7633 100644
--- a/products/messaging/backend/services/html_text.py
+++ b/products/messaging/backend/services/html_text.py
@@ -5,7 +5,7 @@
 PARAGRAPH_TAGS = frozenset({"p", "h1", "h2", "h3", "h4", "h5", "h6", "ul", "ol", "table", "blockquote", "pre", "hr"})
 LINE_TAGS = frozenset({"div", "li", "tr", "section", "article", "header", "footer", "dd", "dt"})
 HIDDEN_TAGS = frozenset({"head", "title", "style", "script", "template"})
-LINK_SCHEMES = ("http://", "https://", "mailto:")
+LINK_SCHEMES = ("http://", "https://", "mailto:", "{{")
 BLANK_LINES = re.compile(r"\n{3,}")
 WHITESPACE = re.compile(r"\s+")
 
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index 29d22169a525..8ad558513b03 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -39,8 +39,10 @@
     SenderUnavailable,
     SendingPaused,
     SendingSuspended,
+    TemplateManagedBy,
     TemplateNotSendable,
     TemplateNotTransactional,
+    TemplateSendOptions,
     TransactionalEmailError,
     TransactionalEmailPaused,
 )
@@ -230,7 +232,7 @@ def _content(template: MessageTemplate) -> TransactionalEmailContent:
         subject=email["subject"],
         preheader=email.get("preheader") or "",
         html=email.get("html") or "",
-        text=email.get("text") or "",
+        text=_sent_text(template, email),
         # Templates made transactional before they stored a sender keep their workflow's sender.
         from_integration_id=sender.get("integrationId"),
         message_category_id=template.message_category_id,
@@ -241,6 +243,13 @@ def _content(template: MessageTemplate) -> TransactionalEmailContent:
     )
 
 
+def _sent_text(template: MessageTemplate, email: dict[str, Any]) -> str:
+    text = email.get("text") or ""
+    if text or template.managed_by != TemplateManagedBy.CODE:
+        return text
+    return text_from_html(email.get("html") or "")
+
+
 def make_transactional(
     team_id: int, template_id: UUID, *, user_id: int | None, from_integration_id: int | None
 ) -> UUID:
@@ -432,12 +441,18 @@ def send_transactional_email(
     message_data: dict[str, Any],
     idempotency_key: str | None = None,
     timeout: float = 10,
+    options: TemplateSendOptions | None = None,
 ) -> QueuedEmail:
     _check_send_request(to, idempotency_key)
     with transactional_email_stage("workflow_lookup"):
         hog_flow_id = _transactional_workflow_id(team.id, template_id)
     payload = _send_payload(to, distinct_id, message_data, idempotency_key)
-    return _queue(team.id, hog_flow_id, payload, run_transactional_workflow, timeout=timeout)
+    if options is None:
+        return _queue(team.id, hog_flow_id, payload, run_transactional_workflow, timeout=timeout)
+    accepted_send = _accepted_template_send(team.id, options)
+    return _queue(
+        team.id, hog_flow_id, {**payload, "send": accepted_send}, send_accepted_transactional_email, timeout=timeout
+    )
 
 
 def send_code_email(
@@ -494,6 +509,15 @@ def _accepted_send(team_id: int, email: CodeEmail) -> dict[str, Any]:
     return accepted
 
 
+def _accepted_template_send(team_id: int, options: TemplateSendOptions) -> dict[str, Any]:
+    accepted: dict[str, Any] = {"tracking": {"captureEngagement": options.capture_engagement}}
+    if options.sender:
+        accepted["from"] = _without_empty(_code_send_sender(team_id, options.sender))
+    if options.reply_to:
+        accepted["replyTo"] = list(options.reply_to)
+    return accepted
+
+
 def _code_send_sender(team_id: int, address: str | None) -> dict[str, Any]:
     name, email = parseaddr(address) if address else ("", "")
     try:
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index e51a2245417b..d105cd2db3c4 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -117,6 +117,20 @@ def test_a_first_upload_creates_a_code_managed_transactional_template(self, _pos
             self.sender.id,
         )
 
+    @parameterized.expand(
+        [
+            ("html_only", {}, "Hi {{ variables.first_name }}"),
+            ("blank_text", {"text": ""}, "Hi {{ variables.first_name }}"),
+            ("single_image", {"html": "<img src='https://example.com/banner.png'>"}, ""),
+        ]
+    )
+    def test_an_upload_without_text_sends_the_text_its_html_holds(
+        self, _post, _flag, _capture, _name, fields, expected_text
+    ):
+        uploaded = self._upload({**WELCOME, **fields})
+
+        assert self._sent_email(uploaded["transactional_hog_flow_id"])["text"] == expected_text
+
     @parameterized.expand(
         [
             ("same_text", WELCOME, WELCOME, WELCOME_HASH),
@@ -145,14 +159,21 @@ def test_an_identical_upload_is_unchanged_and_writes_no_workflow_version(
             edited.call_args.kwargs["updated_at"] == MessageTemplate.objects.get(id=first["id"]).updated_at.isoformat()
         )
 
-    def test_an_upload_repairs_a_stored_hash_that_does_not_describe_the_content(self, _post, _flag, _capture):
+    def test_an_upload_repairs_a_stored_hash_that_does_not_describe_the_content(self, post, _flag, _capture):
+        post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
         first = self._upload(WELCOME)
         MessageTemplate.objects.filter(id=first["id"]).update(content_hash=GREETING_HASH)
 
         repaired = self._upload(WELCOME)
+        sent = self.psak.post(
+            f"/api/projects/{self.team.id}/messaging/send/email/",
+            {"template": {"key": "welcome", "hash": WELCOME_HASH}, "to": "user@example.com"},
+            format="json",
+        )
 
         assert (repaired["result"], repaired["content_hash"]) == ("updated", WELCOME_HASH)
-        assert self._template(first["id"])["content_hash"] == WELCOME_HASH
+        assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
+        assert "warnings" not in sent.json()
 
     @patch("products.messaging.backend.services.transactional_email.reload_hog_flows_on_workers")
     def test_a_changed_upload_is_what_the_next_send_delivers(self, _reload, post: MagicMock, _flag, _capture):
@@ -507,3 +528,41 @@ def test_an_upload_if_not_superseded_never_puts_replaced_content_back(
         assert uploaded["content_hash"] == template["content_hash"]
         assert (template["content"]["email"]["subject"], template["source_ref"]) == (expected_subject, expected_ref)
         assert self._workflow(newer["transactional_hog_flow_id"])["version"] == expected_version
+
+    @parameterized.expand(
+        [
+            ("current", None, status.HTTP_202_ACCEPTED, []),
+            ("superseded", WELCOME_HASH, status.HTTP_202_ACCEPTED, ["template_superseded"]),
+            ("outdated", f"v1:{'0' * 64}", status.HTTP_409_CONFLICT, None),
+        ]
+    )
+    @patch("products.messaging.backend.services.transactional_email.reload_hog_flows_on_workers")
+    def test_a_send_by_key_with_a_hash_only_ever_sends_the_published_content(
+        self, hash_state, sent_hash, expected_status, expected_warnings, _reload, post: MagicMock, _flag, capture
+    ):
+        post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
+        self._upload(WELCOME)
+        published = self._upload({**WELCOME, "subject": "Welcome aboard, {{ variables.first_name }}"})
+        hog_flow_id = published["transactional_hog_flow_id"]
+
+        response = self.psak.post(
+            f"/api/projects/{self.team.id}/messaging/send/email/",
+            {
+                "template": {"key": "welcome", "hash": sent_hash or published["content_hash"]},
+                "to": "jane@example.com",
+                "message_data": {"first_name": "Jane"},
+            },
+            format="json",
+        )
+
+        assert response.status_code == expected_status, response.json()
+        assert capture.call_args.kwargs["properties"]["hash_state"] == hash_state
+        if expected_warnings is None:
+            assert response.json()["code"] == "template_outdated"
+            post.assert_not_called()
+        else:
+            assert [warning["code"] for warning in response.json().get("warnings", [])] == expected_warnings
+            assert post.call_args.args[0].endswith(f"/hog_flows/{hog_flow_id}/transactional_email")
+        assert self._template(published["id"])["content_hash"] == published["content_hash"]
+        assert self._sent_email(hog_flow_id)["subject"] == "Welcome aboard, {{ variables.first_name }}"
+        assert self._workflow(hog_flow_id)["version"] == 2
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 4bf913551ce1..e8251c09284f 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -34,6 +34,7 @@
 from products.workflows.backend.models import HogFlow, TeamWorkflowsConfig
 
 PASSWORD_RESET_HASH = "v1:973d41bbe3fdca5c52bb951cd4b5fd7159ae630b56c8f3997cbb31afd1ea76fd"
+SUPERSEDED_HASH = f"v1:{'1' * 64}"
 
 
 def _stage_counts() -> dict[str, float]:
@@ -501,6 +502,156 @@ def test_refuses_code_fields_on_a_template_send(self, mock_post, _flag, _capture
         assert response.json()["attr"] == "subject"
         mock_post.assert_not_called()
 
+    def _keyed(self) -> dict[str, Any]:
+        MessageTemplate.objects.filter(id=self.template.id).update(
+            key="password-reset",
+            managed_by=TemplateManagedBy.CODE,
+            content_hash=PASSWORD_RESET_HASH,
+            superseded_content_hashes=[SUPERSEDED_HASH],
+        )
+        return {**self.body, "template": {"key": "password-reset"}}
+
+    @parameterized.expand(
+        [
+            ("without_a_hash", {}, "transactional_email", None, None),
+            ("with_the_current_hash", {"hash": PASSWORD_RESET_HASH}, "transactional_email", None, None),
+            (
+                "with_a_superseded_hash",
+                {"hash": SUPERSEDED_HASH},
+                "transactional_email",
+                None,
+                [
+                    {
+                        "code": "template_superseded",
+                        "detail": "The email went out with the template's current content, because newer content "
+                        "replaced the content you hold.",
+                        "fix": "Deploy the newer file, or upload yours to publish it again.",
+                    }
+                ],
+            ),
+            (
+                "with_a_sender_and_reply_to",
+                {"from": "Example <hello@example.com>", "reply_to": ["help@example.com"]},
+                "transactional_email/send",
+                {
+                    "from": {"email": "hello@example.com", "name": "Example"},
+                    "replyTo": ["help@example.com"],
+                    "tracking": {"captureEngagement": True},
+                },
+                None,
+            ),
+            (
+                "without_engagement_capture",
+                {"capture_engagement": False},
+                "transactional_email/send",
+                {"tracking": {"captureEngagement": False}},
+                None,
+            ),
+        ]
+    )
+    def test_a_send_by_template_key_runs_the_templates_workflow(
+        self, mock_post, _flag, capture, _name, fields, route, sent, warnings
+    ):
+        self._cdp_accepts(mock_post)
+        body = self._keyed()
+        reference = {"key": "password-reset", **({"hash": fields["hash"]} if "hash" in fields else {})}
+        body = {**body, **{k: v for k, v in fields.items() if k != "hash"}, "template": reference}
+
+        response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, body, format="json")
+
+        assert response.status_code == status.HTTP_202_ACCEPTED, response.json()
+        expected = {"message_id": "invocation-1", "replayed": False, **({"warnings": warnings} if warnings else {})}
+        assert response.json() == expected
+        assert mock_post.call_args.args[0].endswith(f"/hog_flows/{self.hog_flow_id}/{route}")
+        posted = mock_post.call_args.kwargs["json"]
+        assert (posted["to"], posted["distinct_id"], posted["variables"]) == (
+            "user@example.com",
+            "user-1",
+            self.body["message_data"],
+        )
+        if sent is not None:
+            assert {
+                **posted["send"],
+                "from": {k: v for k, v in posted["send"].get("from", {}).items() if k != "integrationId"},
+            } == {"from": {}, **sent}
+        else:
+            assert "send" not in posted
+        reported = capture.call_args.kwargs["properties"]
+        assert (reported["addressed_by"], reported["template_id"]) == ("template_key", str(self.template.id))
+
+    @parameterized.expand(
+        [
+            ("unknown_key", {"template": {"key": "welcome"}}, status.HTTP_404_NOT_FOUND, "template_not_found", None),
+            (
+                "unknown_key_with_a_hash",
+                {"template": {"key": "welcome", "hash": PASSWORD_RESET_HASH}},
+                status.HTTP_409_CONFLICT,
+                "template_outdated",
+                None,
+            ),
+            (
+                "hash_posthog_does_not_hold",
+                {"template": {"key": "password-reset", "hash": f"v1:{'0' * 64}"}},
+                status.HTTP_409_CONFLICT,
+                "template_outdated",
+                None,
+            ),
+            (
+                "hash_in_upper_case_hex",
+                {"template": {"key": "password-reset", "hash": f"v1:{'A' * 64}"}},
+                status.HTTP_400_BAD_REQUEST,
+                "invalid_input",
+                "template__hash",
+            ),
+            (
+                "key_and_id",
+                {"template": {"key": "password-reset", "id": str(uuid4())}},
+                status.HTTP_400_BAD_REQUEST,
+                "invalid_input",
+                "template",
+            ),
+            ("neither_key_nor_id", {"template": {}}, status.HTTP_400_BAD_REQUEST, "invalid_input", "template"),
+            (
+                "hash_with_id",
+                {"template": {"id": str(uuid4()), "hash": PASSWORD_RESET_HASH}},
+                status.HTTP_400_BAD_REQUEST,
+                "invalid_input",
+                "template",
+            ),
+            (
+                "invalid_key",
+                {"template": {"key": "password reset"}},
+                status.HTTP_400_BAD_REQUEST,
+                "invalid_input",
+                "template__key",
+            ),
+            (
+                "subject_with_a_template_key",
+                {"template": {"key": "password-reset"}, "subject": "Hi"},
+                status.HTTP_400_BAD_REQUEST,
+                "invalid_input",
+                "subject",
+            ),
+            (
+                "unverified_sender",
+                {"template": {"key": "password-reset"}, "from": "security@example.org"},
+                status.HTTP_400_BAD_REQUEST,
+                "sender_not_verified",
+                None,
+            ),
+        ]
+    )
+    def test_refuses_a_send_by_template_key_it_cannot_make(
+        self, mock_post, _flag, _capture, _name, fields, expected_status, expected_code, expected_attr
+    ):
+        body = {**self._keyed(), **fields}
+
+        response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, body, format="json")
+
+        assert response.status_code == expected_status, response.json()
+        assert (response.json()["code"], response.json()["attr"]) == (expected_code, expected_attr)
+        mock_post.assert_not_called()
+
     def test_refuses_a_code_send_from_an_unverified_domain(self, mock_post, _flag, capture):
         response = self._psak_client(["hog_flow:write"]).post(
             self.send_email_url, self._code_send(**{"from": "security@example.org"}), format="json"
@@ -577,6 +728,13 @@ def misses_the_winner_once(team_id: int, key: str) -> TransactionalEmailKey | No
             ("code_send_with_only_its_flag", "code", {EMAIL_FROM_CODE_FLAG}, status.HTTP_202_ACCEPTED),
             ("code_send_without_its_flag", "code", {TRANSACTIONAL_EMAIL_API_FLAG}, status.HTTP_404_NOT_FOUND),
             ("template_send_without_its_flag", "template", {EMAIL_FROM_CODE_FLAG}, status.HTTP_404_NOT_FOUND),
+            ("template_key_send_with_only_the_code_flag", "key", {EMAIL_FROM_CODE_FLAG}, status.HTTP_202_ACCEPTED),
+            (
+                "template_key_send_without_the_code_flag",
+                "key",
+                {TRANSACTIONAL_EMAIL_API_FLAG},
+                status.HTTP_404_NOT_FOUND,
+            ),
         ]
     )
     def test_each_form_of_a_send_answers_only_while_its_flag_is_on(
@@ -584,7 +742,12 @@ def test_each_form_of_a_send_answers_only_while_its_flag_is_on(
     ):
         self._cdp_accepts(mock_post)
         flag.side_effect = lambda key, *_args, **_kwargs: key in enabled_flags
-        body = self._code_send() if form == "code" else {**self.body, "template": {"id": str(self.template.id)}}
+        bodies = {
+            "code": self._code_send,
+            "template": lambda: {**self.body, "template": {"id": str(self.template.id)}},
+            "key": self._keyed,
+        }
+        body = bodies[form]()
 
         response = self.client.post(self.send_email_url, body, format="json")
 
diff --git a/products/messaging/backend/tests/test_html_text.py b/products/messaging/backend/tests/test_html_text.py
index 77c452dbb070..e1feeb450eab 100644
--- a/products/messaging/backend/tests/test_html_text.py
+++ b/products/messaging/backend/tests/test_html_text.py
@@ -19,6 +19,11 @@ class TestTextFromHtml(SimpleTestCase):
                 '<p><a href="https://example.com/reset?t=1">Reset password</a></p>',
                 "Reset password (https://example.com/reset?t=1)",
             ),
+            (
+                "template_link_keeps_its_placeholder",
+                "<a href='{{ variables.link }}'>Reset</a>",
+                "Reset ({{ variables.link }})",
+            ),
             (
                 "link_that_shows_its_address",
                 '<a href="https://example.com">https://example.com</a>',
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index 85181fbe2cbf..98c1c3d1d93e 100644
--- a/products/messaging/frontend/generated/api.schemas.ts
+++ b/products/messaging/frontend/generated/api.schemas.ts
@@ -64,8 +64,19 @@ export interface TransactionalEmailIdentifiersApi {
 }
 
 export interface SendEmailTemplateApi {
-    /** ID of the email template to send. The template must be made transactional first. */
-    id: string
+    /** ID of the email template to send. The template must be made transactional first. Give either `id` or `key`. */
+    id?: string
+    /**
+     * Key of the email template to send, as uploaded with `PUT /api/projects/@current/messaging_templates/by_key/{key}/`. Give either `id` or `key`.
+     * @maxLength 400
+     * @pattern ^[a-zA-Z0-9_-]+$
+     */
+    key?: string
+    /**
+     * Content hash of the template you hold, as an upload's `content_hash`. When PostHog doesn't hold that content as the current content or one of the last 100 contents it replaced, the send answers `409 template_outdated` and sends nothing. Only with `key`.
+     * @pattern ^v1:[0-9a-f]{64}$
+     */
+    hash?: string
 }
 
 export interface SendEmailApi {
@@ -105,11 +116,22 @@ export interface SendEmailApi {
     from?: string
 }
 
-export interface SendTransactionalEmailResponseApi {
+export interface SendEmailWarningApi {
+    /** Stable code of the warning, such as `template_superseded`. */
+    code: string
+    /** What happened. */
+    detail: string
+    /** What you can change, if the warning isn't what you want. */
+    fix: string
+}
+
+export interface SendEmailResponseApi {
     /** ID of the queued send. Delivery and engagement are reported against the template asynchronously. */
     message_id: string
     /** True when an earlier request with the same `Idempotency-Key` already queued this email. No new email was sent, and `message_id` is the earlier send's ID. */
     replayed: boolean
+    /** Things to know about the queued email. Left out when there are none. */
+    warnings?: SendEmailWarningApi[]
 }
 
 /**
@@ -1031,6 +1053,13 @@ export interface SendTransactionalEmailApi {
     message_data?: SendTransactionalEmailApiMessageData
 }
 
+export interface SendTransactionalEmailResponseApi {
+    /** ID of the queued send. Delivery and engagement are reported against the template asynchronously. */
+    message_id: string
+    /** True when an earlier request with the same `Idempotency-Key` already queued this email. No new email was sent, and `message_id` is the earlier send's ID. */
+    replayed: boolean
+}
+
 export interface TemplateSourceApi {
     /**
      * Host and path of the repository the file is in, such as `github.com/example/app`.
@@ -1066,7 +1095,7 @@ export interface UploadTemplateApi {
     text?: string
     /** Inbox preview text shown after the subject. Leaving it out removes the stored one. */
     preheader?: string
-    /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
+    /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file, or an upload after a send answered `template_outdated`. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
     if_not_superseded?: boolean
     /** Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored. */
     source?: TemplateSourceApi
@@ -1099,7 +1128,7 @@ export interface UploadTemplateResponseApi {
      * * `unchanged` - Unchanged
      * * `superseded` - Superseded */
     result: TemplateUploadResultEnumApi
-    /** Hash of the published content, as `v1:` and 64 hex characters. After `superseded` it is the hash of the newer content. */
+    /** Hash of the published content, as `v1:` and 64 hex characters. Send it with an email as `template.hash` to check PostHog holds the content you hold. After `superseded` it is the hash of the newer content. */
     content_hash: string
     /** `code` after every upload except `superseded`, which changes nothing. After `superseded` it is what the template had, which is null for a template made in PostHog that no upload claimed yet.
      *
diff --git a/products/messaging/frontend/generated/api.ts b/products/messaging/frontend/generated/api.ts
index 041612f8d153..ca1277a6bbde 100644
--- a/products/messaging/frontend/generated/api.ts
+++ b/products/messaging/frontend/generated/api.ts
@@ -38,6 +38,7 @@ import type {
     ProviderImportRunApi,
     RemoveOptOutRequestApi,
     SendEmailApi,
+    SendEmailResponseApi,
     SendTransactionalEmailApi,
     SendTransactionalEmailResponseApi,
     StartProviderImportApi,
@@ -88,15 +89,15 @@ export const getMessagingSendEmailCreateUrl = (projectId: string) => {
 }
 
 /**
- * Send one transactional email to one recipient. Name a template made transactional in `template.id`, and `message_data` fills its `{{ variables.* }}` placeholders. Or send content your code rendered with a `template_key`, a `subject` and `html` or `text`: PostHog sends it as is, and its metrics and run history group under the key. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice.
+ * Send one transactional email to one recipient. Name a template made transactional in `template.id`, or one uploaded from code in `template.key`, and `message_data` fills its `{{ variables.* }}` placeholders. Or send content your code rendered with a `template_key`, a `subject` and `html` or `text`: PostHog sends it as is, and its metrics and run history group under the key. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice.
  * @summary Send a transactional email
  */
 export const messagingSendEmailCreate = async (
     projectId: string,
     sendEmailApi: SendEmailApi,
     options?: RequestInit
-): Promise<SendTransactionalEmailResponseApi> => {
-    return apiMutator<SendTransactionalEmailResponseApi>(getMessagingSendEmailCreateUrl(projectId), {
+): Promise<SendEmailResponseApi> => {
+    return apiMutator<SendEmailResponseApi>(getMessagingSendEmailCreateUrl(projectId), {
         ...options,
         method: 'POST',
         headers: { 'Content-Type': 'application/json', ...options?.headers },
diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.ts
index fb381da48dfb..09a746ad7318 100644
--- a/products/messaging/frontend/generated/api.zod.ts
+++ b/products/messaging/frontend/generated/api.zod.ts
@@ -10,11 +10,15 @@
 import * as zod from 'zod'
 
 /**
- * Send one transactional email to one recipient. Name a template made transactional in `template.id`, and `message_data` fills its `{{ variables.* }}` placeholders. Or send content your code rendered with a `template_key`, a `subject` and `html` or `text`: PostHog sends it as is, and its metrics and run history group under the key. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice.
+ * Send one transactional email to one recipient. Name a template made transactional in `template.id`, or one uploaded from code in `template.key`, and `message_data` fills its `{{ variables.* }}` placeholders. Or send content your code rendered with a `template_key`, a `subject` and `html` or `text`: PostHog sends it as is, and its metrics and run history group under the key. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice.
  * @summary Send a transactional email
  */
 export const messagingSendEmailCreateBodyIdentifiersOneDistinctIdMax = 400
 
+export const messagingSendEmailCreateBodyTemplateOneKeyMax = 400
+
+export const messagingSendEmailCreateBodyTemplateOneKeyRegExp = new RegExp('^[a-zA-Z0-9_-]+$')
+export const messagingSendEmailCreateBodyTemplateOneHashRegExp = new RegExp('^v1:[0-9a-f]{64}$')
 export const messagingSendEmailCreateBodyTemplateKeyMax = 400
 
 export const messagingSendEmailCreateBodyTemplateKeyRegExp = new RegExp('^[a-zA-Z0-9_-]+$')
@@ -44,7 +48,27 @@ export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({
         ),
     template: zod
         .object({
-            id: zod.uuid().describe('ID of the email template to send. The template must be made transactional first.'),
+            id: zod
+                .uuid()
+                .optional()
+                .describe(
+                    'ID of the email template to send. The template must be made transactional first. Give either `id` or `key`.'
+                ),
+            key: zod
+                .string()
+                .max(messagingSendEmailCreateBodyTemplateOneKeyMax)
+                .regex(messagingSendEmailCreateBodyTemplateOneKeyRegExp)
+                .optional()
+                .describe(
+                    'Key of the email template to send, as uploaded with `PUT \/api\/projects\/@current\/messaging_templates\/by_key\/{key}\/`. Give either `id` or `key`.'
+                ),
+            hash: zod
+                .string()
+                .regex(messagingSendEmailCreateBodyTemplateOneHashRegExp)
+                .optional()
+                .describe(
+                    "Content hash of the template you hold, as an upload's `content_hash`. When PostHog doesn't hold that content as the current content or one of the last 100 contents it replaced, the send answers `409 template_outdated` and sends nothing. Only with `key`."
+                ),
         })
         .optional()
         .describe('The transactional email template to send. Send either `template` or `template_key`.'),
@@ -1450,7 +1474,7 @@ export const MessagingTemplatesByKeyUpdateBody = /* @__PURE__ */ zod.object({
         .boolean()
         .default(messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault)
         .describe(
-            'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
+            'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file, or an upload after a send answered `template_outdated`. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
         ),
     source: zod
         .object({
diff --git a/products/workflows/mcp/email_templates.yaml b/products/workflows/mcp/email_templates.yaml
index a6a82e4318b1..0488a21eabdb 100644
--- a/products/workflows/mcp/email_templates.yaml
+++ b/products/workflows/mcp/email_templates.yaml
@@ -205,8 +205,8 @@ tools:
             can't read person properties. The first upload creates the template and makes it sendable over the
             transactional email API with the project's default verified sender, so verify a sender first. Later uploads
             publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made
-            in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content: an
-            answer of superseded means newer content is already published and nothing changed. The check covers the
+            in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content, such as
+            when you upload only because a send answered template_outdated: an answer of superseded means newer content is already published and nothing changed. The check covers the
             last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish
             this content even when newer content replaced it, such as to roll back. A 404 with code not_found means
             sending email from code is not enabled for this project, or the project does not exist: stop and tell
diff --git a/services/mcp/schema/generated-tool-definitions.json b/services/mcp/schema/generated-tool-definitions.json
index 29cda664aa7d..2235d50905f9 100644
--- a/services/mcp/schema/generated-tool-definitions.json
+++ b/services/mcp/schema/generated-tool-definitions.json
@@ -17361,7 +17361,7 @@
         }
     },
     "workflows-upload-email-template": {
-        "description": "Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or password-reset). Use this for templates that live in code; use workflows-create-email-template for templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates can't read person properties. The first upload creates the template and makes it sendable over the transactional email API with the project's default verified sender, so verify a sender first. Later uploads publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content: an answer of superseded means newer content is already published and nothing changed. The check covers the last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish this content even when newer content replaced it, such as to roll back. A 404 with code not_found means sending email from code is not enabled for this project, or the project does not exist: stop and tell the user.",
+        "description": "Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or password-reset). Use this for templates that live in code; use workflows-create-email-template for templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates can't read person properties. The first upload creates the template and makes it sendable over the transactional email API with the project's default verified sender, so verify a sender first. Later uploads publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content, such as when you upload only because a send answered template_outdated: an answer of superseded means newer content is already published and nothing changed. The check covers the last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish this content even when newer content replaced it, such as to roll back. A 404 with code not_found means sending email from code is not enabled for this project, or the project does not exist: stop and tell the user.",
         "category": "Workflows",
         "feature": "workflows",
         "summary": "Upload email template by key",
diff --git a/services/mcp/schema/tool-definitions-all.json b/services/mcp/schema/tool-definitions-all.json
index 38069b6b34be..0a654f37fb79 100644
--- a/services/mcp/schema/tool-definitions-all.json
+++ b/services/mcp/schema/tool-definitions-all.json
@@ -18208,7 +18208,7 @@
         }
     },
     "workflows-upload-email-template": {
-        "description": "Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or password-reset). Use this for templates that live in code; use workflows-create-email-template for templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates can't read person properties. The first upload creates the template and makes it sendable over the transactional email API with the project's default verified sender, so verify a sender first. Later uploads publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content: an answer of superseded means newer content is already published and nothing changed. The check covers the last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish this content even when newer content replaced it, such as to roll back. A 404 with code not_found means sending email from code is not enabled for this project, or the project does not exist: stop and tell the user.",
+        "description": "Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or password-reset). Use this for templates that live in code; use workflows-create-email-template for templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates can't read person properties. The first upload creates the template and makes it sendable over the transactional email API with the project's default verified sender, so verify a sender first. Later uploads publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content, such as when you upload only because a send answered template_outdated: an answer of superseded means newer content is already published and nothing changed. The check covers the last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish this content even when newer content replaced it, such as to roll back. A 404 with code not_found means sending email from code is not enabled for this project, or the project does not exist: stop and tell the user.",
         "category": "Workflows",
         "feature": "workflows",
         "summary": "Upload email template by key",
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 396391c2c738..29271093798b 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -110976,8 +110976,19 @@ export namespace Schemas {
     }
 
     export interface SendEmailTemplate {
-      /** ID of the email template to send. The template must be made transactional first. */
-      id: string;
+      /** ID of the email template to send. The template must be made transactional first. Give either `id` or `key`. */
+      id?: string;
+      /**
+         * Key of the email template to send, as uploaded with `PUT /api/projects/@current/messaging_templates/by_key/{key}/`. Give either `id` or `key`.
+         * @maxLength 400
+         * @pattern ^[a-zA-Z0-9_-]+$
+         */
+      key?: string;
+      /**
+         * Content hash of the template you hold, as an upload's `content_hash`. When PostHog doesn't hold that content as the current content or one of the last 100 contents it replaced, the send answers `409 template_outdated` and sends nothing. Only with `key`.
+         * @pattern ^v1:[0-9a-f]{64}$
+         */
+      hash?: string;
     }
 
     export interface SendEmail {
@@ -111017,6 +111028,24 @@ export namespace Schemas {
       from?: string;
     }
 
+    export interface SendEmailWarning {
+      /** Stable code of the warning, such as `template_superseded`. */
+      code: string;
+      /** What happened. */
+      detail: string;
+      /** What you can change, if the warning isn't what you want. */
+      fix: string;
+    }
+
+    export interface SendEmailResponse {
+      /** ID of the queued send. Delivery and engagement are reported against the template asynchronously. */
+      message_id: string;
+      /** True when an earlier request with the same `Idempotency-Key` already queued this email. No new email was sent, and `message_id` is the earlier send's ID. */
+      replayed: boolean;
+      /** Things to know about the queued email. Left out when there are none. */
+      warnings?: SendEmailWarning[];
+    }
+
     /**
      * Data for the template's Liquid placeholders, available as `variables`. For example `{"reset_link": "https://..."}` fills `{{ variables.reset_link }}`.
      */
@@ -123550,7 +123579,7 @@ export namespace Schemas {
       text?: string;
       /** Inbox preview text shown after the subject. Leaving it out removes the stored one. */
       preheader?: string;
-      /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
+      /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file, or an upload after a send answered `template_outdated`. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
       if_not_superseded?: boolean;
       /** Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored. */
       source?: TemplateSource;
@@ -123568,7 +123597,7 @@ export namespace Schemas {
        * * `unchanged` - Unchanged
        * * `superseded` - Superseded */
       result: TemplateUploadResultEnum;
-      /** Hash of the published content, as `v1:` and 64 hex characters. After `superseded` it is the hash of the newer content. */
+      /** Hash of the published content, as `v1:` and 64 hex characters. Send it with an email as `template.hash` to check PostHog holds the content you hold. After `superseded` it is the hash of the newer content. */
       content_hash: string;
       /** `code` after every upload except `superseded`, which changes nothing. After `superseded` it is what the template had, which is null for a template made in PostHog that no upload claimed yet.
        *
diff --git a/services/mcp/src/generated/email_templates/api.ts b/services/mcp/src/generated/email_templates/api.ts
index 055c10fd8f33..9699c19b670b 100644
--- a/services/mcp/src/generated/email_templates/api.ts
+++ b/services/mcp/src/generated/email_templates/api.ts
@@ -9,7 +9,7 @@
 import * as zod from 'zod'
 
 /**
- * Send one transactional email to one recipient. Name a template made transactional in `template.id`, and `message_data` fills its `{{ variables.* }}` placeholders. Or send content your code rendered with a `template_key`, a `subject` and `html` or `text`: PostHog sends it as is, and its metrics and run history group under the key. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice.
+ * Send one transactional email to one recipient. Name a template made transactional in `template.id`, or one uploaded from code in `template.key`, and `message_data` fills its `{{ variables.* }}` placeholders. Or send content your code rendered with a `template_key`, a `subject` and `html` or `text`: PostHog sends it as is, and its metrics and run history group under the key. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice.
  * @summary Send a transactional email
  */
 export const MessagingSendEmailCreateParams = () => zod.object({
@@ -545,7 +545,7 @@ export const MessagingTemplatesByKeyUpdateBody = () => zod.object({
         .boolean()
         .default(messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault)
         .describe(
-            'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
+            'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file, or an upload after a send answered `template_outdated`. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
         ),
     source: zod
         .object({
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
index 61be523f4553..b7ce9f3a090a 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
@@ -7,7 +7,7 @@
         },
         "if_not_superseded": {
             "default": false,
-            "description": "Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.",
+            "description": "Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file, or an upload after a send answered `template_outdated`. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.",
             "type": "boolean"
         },
         "key": {

From faade6170f0e70a6eccab8d73ea43c55de665fde Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:36:45 +0000
Subject: [PATCH 10/42] fix(workflows): say when a read-only template's sender
 could not load

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../TemplateLibrary/ReadOnlyTemplatePreview.test.tsx      | 8 ++++++++
 .../frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx  | 8 ++++++--
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx
index 30f14a80ecd2..f42a3ccf814c 100644
--- a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx
+++ b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.test.tsx
@@ -59,4 +59,12 @@ describe('ReadOnlyTemplatePreview', () => {
 
         expect(await screen.findByText('No sender set')).toBeInTheDocument()
     })
+
+    it('says the sender could not load when the integrations request fails', async () => {
+        useMocks({ get: { '/api/projects/:team_id/integrations/': [500, { detail: 'Server error' }] } })
+
+        render(<ReadOnlyTemplatePreview email={email({ from: { integrationId: 5 } })} />)
+
+        expect(await screen.findByText("Couldn't load the sender. Refresh the page to try again.")).toBeInTheDocument()
+    })
 })
diff --git a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
index ea100c91f9ea..e527c4469a51 100644
--- a/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
+++ b/products/workflows/frontend/TemplateLibrary/ReadOnlyTemplatePreview.tsx
@@ -10,10 +10,14 @@ import type { EmailTemplate } from 'scenes/hog-functions/email-templater/types'
 import { EmailHtmlFrame } from './EmailHtmlFrame'
 
 function ReadOnlySender({ email }: { email: EmailTemplate }): JSX.Element {
-    const { integrations } = useValues(integrationsLogic)
+    const { integrations, integrationsLoading } = useValues(integrationsLogic)
 
     if (!integrations) {
-        return <LemonSkeleton className="h-4 w-48" />
+        return integrationsLoading ? (
+            <LemonSkeleton className="h-4 w-48" />
+        ) : (
+            <span className="text-secondary">Couldn't load the sender. Refresh the page to try again.</span>
+        )
     }
     const senders = integrations.filter((integration) => integration.kind === 'email')
     return <EmailSenderDetails email={email} senders={senders} placeholder="No sender set" />

From be7252c68a9c0a5cd7a15faa972e6c93cfb2f741 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 12:28:30 +0000
Subject: [PATCH 11/42] fix(messaging): refuse unknown fields on a send by
 template key

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../presentation/views/message_templates.py   | 21 ++++++++++++++-----
 .../tests/api/test_transactional_email.py     | 14 +++++++++++++
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 0c24a4e1b799..15a6f71eb814 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -1,5 +1,5 @@
 import time
-from collections.abc import Callable, Mapping, Sequence
+from collections.abc import Callable, Iterable, Mapping, Sequence
 from contextlib import AbstractContextManager, nullcontext
 from dataclasses import fields as dataclass_fields
 from email.utils import parseaddr
@@ -531,6 +531,18 @@ class SendEmailTemplateSerializer(serializers.Serializer):
         "template_outdated` and sends nothing. Only with `key`.",
     )
 
+    def to_internal_value(self, data: Any) -> dict[str, Any]:
+        if isinstance(data, Mapping) and "key" in data:
+            refuse_unknown_fields(data, self.fields)
+        return super().to_internal_value(data)
+
+
+def refuse_unknown_fields(sent: Iterable[str], known: Mapping[str, Any]) -> None:
+    if unknown := next((field for field in sorted(sent) if field not in known), None):
+        raise serializers.ValidationError(
+            {unknown: "PostHog doesn't take this field, so it doesn't send the email without it."}
+        )
+
 
 CODE_SEND_FIELDS = ("template_key", "subject", "html", "text", "from", "reply_to", "capture_engagement")
 RENDERED_CONTENT_FIELDS = ("subject", "html", "text")
@@ -606,12 +618,11 @@ def validate(self, data: dict[str, Any]) -> dict[str, Any]:
         if ("template" in data) == ("template_key" in data):
             raise serializers.ValidationError({"template": "Send either `template` or `template_key`."})
         if "template" in data:
+            if "key" in data["template"]:
+                refuse_unknown_fields(sent, self.fields)
             self._validate_template(data["template"], sent)
             return data
-        if unknown := next((field for field in sorted(sent) if field not in self.fields), None):
-            raise serializers.ValidationError(
-                {unknown: "PostHog doesn't take this field, so it doesn't send the email without it."}
-            )
+        refuse_unknown_fields(sent, self.fields)
         if "message_data" in sent:
             raise serializers.ValidationError(
                 {"message_data": "A send with `template_key` carries content your code rendered, not `message_data`."}
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index e8251c09284f..e2090dc395c8 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -632,6 +632,20 @@ def test_a_send_by_template_key_runs_the_templates_workflow(
                 "invalid_input",
                 "subject",
             ),
+            (
+                "misspelled_field",
+                {"template": {"key": "password-reset"}, "capture_engagment": False},
+                status.HTTP_400_BAD_REQUEST,
+                "invalid_input",
+                "capture_engagment",
+            ),
+            (
+                "misspelled_template_field",
+                {"template": {"key": "password-reset", "haash": PASSWORD_RESET_HASH}},
+                status.HTTP_400_BAD_REQUEST,
+                "invalid_input",
+                "template__haash",
+            ),
             (
                 "unverified_sender",
                 {"template": {"key": "password-reset"}, "from": "security@example.org"},

From a1d56b38e2d56703b2c6b9129790c7fd422ff803 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:38:11 +0000
Subject: [PATCH 12/42] fix(workflows): take a released template's content as
 published

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messageTemplateLogic.test.ts              | 24 +++++++++++++++++++
 .../TemplateLibrary/messageTemplateLogic.ts   |  6 +++--
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
index eade5c5004be..34b08c4baec3 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
@@ -591,6 +591,30 @@ describe('messageTemplateLogic', () => {
             ].filter((field) => field in patchBodies[1])
             expect(serverOwnedFieldsSent).toEqual([])
         })
+
+        it('takes content an upload published during the release as the published content', async () => {
+            const uploaded = {
+                ...CODE_MANAGED.content,
+                email: { ...CODE_MANAGED.content.email, subject: 'Uploaded during the release' },
+            }
+            useMocks({
+                patch: {
+                    '/api/environments/:team_id/messaging_templates/:id/': () => [
+                        200,
+                        { ...CODE_MANAGED, managed_by: 'gui', transactional_hog_flow_id: 'flow-id', content: uploaded },
+                    ],
+                },
+            })
+
+            await expectLogic(logic, () => {
+                logic.actions.releaseTemplate()
+            })
+                .toDispatchActions(['releaseTemplateSuccess'])
+                .toFinishAllListeners()
+
+            expect(logic.values.template.content).toEqual(uploaded)
+            await expectLogic(logic).toMatchValues({ draftsEnabled: true, hasDraft: false, hasUnsavedChanges: false })
+        })
     })
 
     describe('claimed back by an upload while editing', () => {
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
index 7062145d3a55..9e03e97a649d 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.ts
@@ -1054,8 +1054,10 @@ export const messageTemplateLogic = kea<messageTemplateLogicType>([
             actions.replayDeferredExternalEdit()
         },
         releaseTemplateSuccess: ({ template }) => {
-            actions.resetTemplate(template)
-            actions.setOriginalTemplate(template)
+            const { form, draft, published } = splitDraft(template)
+            actions.setDraftState(draft, published)
+            actions.resetTemplate(form)
+            actions.setOriginalTemplate(form)
             const edits = values.refusedEdits
             if (edits) {
                 actions.setRefusedEdits(null)

From 83f56a3497c22b7a57962f80a527e507c3a8e21b Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:39:36 +0000
Subject: [PATCH 13/42] fix(workflows): treat only a full commit hash as a
 commit in a template source

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 frontend/src/lib/components/Git/gitMetadataParser.ts     | 2 +-
 .../TemplateLibrary/messageTemplateLogic.test.ts         | 9 +++++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/frontend/src/lib/components/Git/gitMetadataParser.ts b/frontend/src/lib/components/Git/gitMetadataParser.ts
index 5c1382fb92dc..cdbd3a869e4d 100644
--- a/frontend/src/lib/components/Git/gitMetadataParser.ts
+++ b/frontend/src/lib/components/Git/gitMetadataParser.ts
@@ -9,7 +9,7 @@ export type ParsedRemoteUrl = {
 }
 
 const GITHUB_SLUG_PATTERN = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/
-const COMMIT_SHA_PATTERN = /^[0-9a-f]{7,40}$/i
+const COMMIT_SHA_PATTERN = /^([0-9a-f]{40}|[0-9a-f]{64})$/i
 
 function encodePathSegments(value: string): string {
     return value.split('/').map(encodeURIComponent).join('/')
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
index 34b08c4baec3..885a50fcd0fa 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
@@ -482,6 +482,15 @@ describe('messageTemplateLogic', () => {
                     refUrl: 'https://github.com/example/app/tree/main',
                 }),
             },
+            {
+                description: 'a tag of hex digits keeps its name and links as a tag',
+                served: { ...CODE_MANAGED, source_ref: 'deadbeef' },
+                isCodeManaged: true,
+                templateSource: expect.objectContaining({
+                    ref: 'deadbeef',
+                    refUrl: 'https://github.com/example/app/tree/deadbeef',
+                }),
+            },
             {
                 description: 'an unknown host stays plain text',
                 served: { ...CODE_MANAGED, source_repository: 'git.example.com/team/app' },

From b6b440469e32ff057251c4a777aa34d663d7637d Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 25 Oct 2026 13:40:07 +0000
Subject: [PATCH 14/42] chore(workflows): serialize an email preview's doctype
 with XMLSerializer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../TemplateLibrary/EmailHtmlFrame.test.tsx     | 17 ++++++++++-------
 .../frontend/TemplateLibrary/EmailHtmlFrame.tsx |  8 +-------
 2 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx
index a1be44c16426..eb73947021f0 100644
--- a/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx
+++ b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.test.tsx
@@ -27,14 +27,17 @@ describe('EmailHtmlFrame', () => {
         expect(link?.textContent).toEqual('Go')
     })
 
-    it('keeps the doctype, so the email renders in the same mode', () => {
-        const html =
-            '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><body><p>Hi</p></body></html>'
-        const { container } = render(<EmailHtmlFrame html={html} />)
+    it.each([
+        [
+            'a public and a system id',
+            '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">',
+        ],
+        ['a system id only', '<!DOCTYPE html SYSTEM "about:legacy-compat">'],
+        ['no ids', '<!DOCTYPE html>'],
+    ])('keeps a doctype with %s, so the email renders in the same mode', (_case, doctype) => {
+        const { container } = render(<EmailHtmlFrame html={`${doctype}<html><body><p>Hi</p></body></html>`} />)
 
-        expect(container.querySelector('iframe')?.getAttribute('srcdoc')).toMatch(
-            /^<!DOCTYPE html PUBLIC "-\/\/W3C\/\/DTD XHTML 1\.0 Transitional\/\/EN" "http:\/\/www\.w3\.org\/TR\/xhtml1\/DTD\/xhtml1-transitional\.dtd">/
-        )
+        expect(container.querySelector('iframe')?.getAttribute('srcdoc')?.startsWith(`${doctype}<html>`)).toBe(true)
     })
 
     it('lets links open a new tab but never runs scripts', () => {
diff --git a/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx
index 9361fb86293b..23c52d0ddebb 100644
--- a/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx
+++ b/products/workflows/frontend/TemplateLibrary/EmailHtmlFrame.tsx
@@ -3,13 +3,7 @@ import { useMemo } from 'react'
 import { cn } from 'lib/utils/css-classes'
 
 function doctypeOf(parsed: Document): string {
-    const doctype = parsed.doctype
-    if (!doctype) {
-        return ''
-    }
-    const publicId = doctype.publicId ? ` PUBLIC "${doctype.publicId}"` : ''
-    const systemId = doctype.systemId ? `${doctype.publicId ? '' : ' SYSTEM'} "${doctype.systemId}"` : ''
-    return `<!DOCTYPE ${doctype.name}${publicId}${systemId}>`
+    return parsed.doctype ? new XMLSerializer().serializeToString(parsed.doctype) : ''
 }
 
 function withLinksInNewTab(html: string): string {

From c94a372dabb26c1bcec95f2a1edcc0ec555eccd4 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 26 Oct 2026 04:09:49 +0000
Subject: [PATCH 15/42] fix(messaging): show only the banner when an upload
 refuses a template edit

A publish refused because an upload took the template back over already
shows the warning banner with "Duplicate with my changes". The global
loader toast also showed the server message, so the user saw two errors.
messageTemplateLogic now owns the `immutable` refusal of saveTemplate.
Every other saveTemplate failure keeps the toast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 frontend/src/initKea.ts                        | 10 +++++++++-
 .../messageTemplateLogic.test.ts               | 18 ++++++++++++++----
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/frontend/src/initKea.ts b/frontend/src/initKea.ts
index 97c0e599b9f2..cbfc6972ca59 100644
--- a/frontend/src/initKea.ts
+++ b/frontend/src/initKea.ts
@@ -199,6 +199,10 @@ const FIELD_ERROR_SELF_HANDLED: Record<string, Set<string>> = {
 
 const HAS_DEPENDENTS_SELF_HANDLED = new Set(['deleteDataWarehouseSavedQuery'])
 
+const CODE_MANAGED_REFUSAL_SELF_HANDLED_BY_LOGIC_PATH: Record<string, string> = {
+    saveTemplate: 'products.workflows.frontend.messageTemplateLogic',
+}
+
 /*
 Write actions whose owning logic toasts the server message of a validation 400. The 400 is a
 response to user input, such as a malformed CSV, so it is not reported as an exception.
@@ -329,6 +333,9 @@ export function initKea({
                         error.code === 'has_dependents' && HAS_DEPENDENTS_SELF_HANDLED.has(String(actionKey))
                     const isSelfHandledFieldError =
                         error.status === 400 && !!FIELD_ERROR_SELF_HANDLED[String(actionKey)]?.has(error.attr)
+                    const isSelfHandledCodeManagedRefusal =
+                        error.code === 'immutable' &&
+                        isOwnedByLogic(CODE_MANAGED_REFUSAL_SELF_HANDLED_BY_LOGIC_PATH, actionKey, logic.pathString)
 
                     if (!errorMessage && error.status === 404) {
                         errorMessage = 'URL not found'
@@ -349,7 +356,8 @@ export function initKea({
                         isFeatureFlagDuplicateKey ||
                         isHasDependentsError ||
                         isSelfHandledFieldError ||
-                        isSelfHandledValidationError
+                        isSelfHandledValidationError ||
+                        isSelfHandledCodeManagedRefusal
                     ) {
                         // These are handled by their own dedicated toasts elsewhere.
                         errorMessage = null
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
index 885a50fcd0fa..f0d41a5e7411 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
@@ -12,14 +12,16 @@ import { resourceEditedLogic } from 'products/notifications/frontend/resourceEdi
 
 import { messageTemplateLogic } from './messageTemplateLogic'
 
-jest.mock('lib/lemon-ui/LemonToast', () => ({
+jest.mock('lib/lemon-ui/LemonToast/LemonToast', () => ({
+    ...jest.requireActual('lib/lemon-ui/LemonToast/LemonToast'),
     lemonToast: {
         success: jest.fn(),
         error: jest.fn(),
     },
 }))
+jest.mock('lib/lemon-ui/LemonToast', () => jest.requireMock('lib/lemon-ui/LemonToast/LemonToast'))
 
-const mockToast = require('lib/lemon-ui/LemonToast').lemonToast
+const mockToast = require('lib/lemon-ui/LemonToast/LemonToast').lemonToast
 
 describe('messageTemplateLogic', () => {
     let logic: ReturnType<typeof messageTemplateLogic.build>
@@ -112,10 +114,17 @@ describe('messageTemplateLogic', () => {
                 toast: 'Failed to save template. Please try again.',
                 withButton: false,
             },
-        ])('$description', async ({ status, toast, withButton }) => {
+            {
+                description: 'a refusal other than an upload claiming the template still shows the server message',
+                status: 403,
+                code: 'permission_denied',
+                toast: 'Save template failed: nope',
+                withButton: false,
+            },
+        ])('$description', async ({ status, code, toast, withButton }) => {
             useMocks({
                 patch: {
-                    '/api/environments/:team_id/messaging_templates/:id/': () => [status, { detail: 'nope' }],
+                    '/api/environments/:team_id/messaging_templates/:id/': () => [status, { code, detail: 'nope' }],
                 },
             })
 
@@ -725,6 +734,7 @@ describe('messageTemplateLogic', () => {
                 reloadStatus = status
                 await refuse(refusal)
 
+                expect(mockToast.error).not.toHaveBeenCalledWith(expect.stringContaining('managed by code'))
                 await expectLogic(logic).toMatchValues({
                     isCodeManaged: true,
                     hasDraft: false,

From 1390333a0ccdb160c0363549bd3f487be5fa50f2 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:00:31 +0000
Subject: [PATCH 16/42] fix(workflows): drop an empty design from a template
 copy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messageTemplateLogic.test.ts              | 22 +++++++++++++++----
 .../frontend/TemplateLibrary/templateCopy.ts  |  4 +++-
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
index f0d41a5e7411..5b342b9aa932 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
@@ -551,7 +551,11 @@ describe('messageTemplateLogic', () => {
                 },
                 post: {
                     '/api/environments/:team_id/messaging_templates/': async ({ request }: { request: Request }) => {
-                        createBodies.push(await request.json())
+                        const body = await request.json()
+                        if (body.content?.email?.design === null) {
+                            return [400, { type: 'validation_error', code: 'null', attr: 'content__email__design' }]
+                        }
+                        createBodies.push(body)
                         return [201, { id: 'copy-id' }]
                     },
                 },
@@ -578,8 +582,13 @@ describe('messageTemplateLogic', () => {
                 logic.actions.duplicateTemplate()
             }).toFinishAllListeners()
 
+            const { design: _design, ...emailWithoutDesign } = CODE_MANAGED.content.email
             expect(createBodies).toEqual([
-                { name: 'Welcome (copy)', description: 'Sent after signup', content: CODE_MANAGED.content },
+                {
+                    name: 'Welcome (copy)',
+                    description: 'Sent after signup',
+                    content: { ...CODE_MANAGED.content, email: emailWithoutDesign },
+                },
             ])
         })
 
@@ -705,7 +714,11 @@ describe('messageTemplateLogic', () => {
                 },
                 post: {
                     '/api/environments/:team_id/messaging_templates/': async ({ request }: { request: Request }) => {
-                        createBodies.push(await request.json())
+                        const body = await request.json()
+                        if (body.content?.email?.design === null) {
+                            return [400, { type: 'validation_error', code: 'null', attr: 'content__email__design' }]
+                        }
+                        createBodies.push(body)
                         return [201, { id: 'copy-id' }]
                     },
                 },
@@ -801,6 +814,7 @@ describe('messageTemplateLogic', () => {
 
         it('duplicates the unsaved edits without its key, ownership, source or hash', async () => {
             await refuse(claimThenAutosave)
+            const { design: _design, ...emailWithoutDesign } = draft.email
 
             await expectLogic(logic, () => {
                 logic.actions.duplicateWithMyChanges()
@@ -810,7 +824,7 @@ describe('messageTemplateLogic', () => {
                 {
                     name: 'Welcome, edited here (copy)',
                     description: 'Sent after signup',
-                    content: { ...draft, email: { ...draft.email, subject: 'Edited subject' } },
+                    content: { ...draft, email: { ...emailWithoutDesign, subject: 'Edited subject' } },
                 },
             ])
             await expectLogic(logic).toMatchValues({ refusedEdits: null })
diff --git a/products/workflows/frontend/TemplateLibrary/templateCopy.ts b/products/workflows/frontend/TemplateLibrary/templateCopy.ts
index 8bf457ae9ba1..71978ee7dac0 100644
--- a/products/workflows/frontend/TemplateLibrary/templateCopy.ts
+++ b/products/workflows/frontend/TemplateLibrary/templateCopy.ts
@@ -1,9 +1,11 @@
+import { omitNullDesign } from './omitNullDesign'
 import { MessageTemplate } from './types'
 
 export function templateCopy(template: MessageTemplate): Partial<MessageTemplate> {
+    const email = template.content?.email
     return {
         name: `${template.name} (copy)`,
         description: template.description,
-        content: template.content,
+        content: email ? { ...template.content, email: omitNullDesign(email) } : template.content,
     }
 }

From 1c8455d44badf920877e4777f9b9630f5cdf4279 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 12:04:23 +0000
Subject: [PATCH 17/42] feat(messaging): point a sender refusal at the from a
 send names

A code send, or a send by `template.key`, that names a `from` on no
verified domain now answers `sender_not_verified` with `attr: "from"`, so
an SDK can show which field to fix. A send without `from` whose project
has no verified default sender still names no field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 products/messaging/backend/facade/contracts.py      |  5 +++++
 .../backend/presentation/views/message_templates.py |  8 +++++++-
 .../backend/services/transactional_email.py         |  3 ++-
 .../backend/tests/api/test_transactional_email.py   | 13 +++++++++++--
 4 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 3be898299ac5..b363945482fe 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -39,6 +39,7 @@ class TransactionalEmailError(Exception):
     """A send the caller has to fix before retrying. `code` is stable for API clients."""
 
     code = "invalid"
+    attr: str | None = None
 
 
 class TemplateNotSendable(TransactionalEmailError):
@@ -103,6 +104,10 @@ class SenderNotVerified(TransactionalEmailError):
     code = "sender_not_verified"
 
 
+class NamedSenderNotVerified(SenderNotVerified):
+    attr = "from"
+
+
 class TemplateOutdated(TransactionalEmailError):
     code = "template_outdated"
 
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 15a6f71eb814..40eb78ce7958 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -718,6 +718,12 @@ def __init__(self, error: TransactionalEmailError) -> None:
         super().__init__(detail=str(error), code=error.code)
 
 
+def _rejection(error: TransactionalEmailError) -> exceptions.APIException:
+    if error.attr:
+        return exceptions.ValidationError({error.attr: [str(error)]}, code=error.code)
+    return TransactionalEmailRejected(error)
+
+
 class TransactionalEmailUnavailable(exceptions.APIException):
     status_code = status.HTTP_503_SERVICE_UNAVAILABLE
     default_detail = "The email pipeline is unavailable. Try again shortly."
@@ -920,7 +926,7 @@ def _queue_send(
             outcome["outcome"] = "replayed" if queued.replayed else "queued"
         except TransactionalEmailError as e:
             outcome.update({"outcome": "rejected", "error_code": e.code})
-            raise TransactionalEmailRejected(e)
+            raise _rejection(e)
         except DeliveryUnavailable:
             outcome["outcome"] = "unavailable"
             raise unavailable() from None
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index 8ad558513b03..f1c732bb9a2d 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -31,6 +31,7 @@
     InvalidIdempotencyKey,
     InvalidRecipient,
     MarketingTemplate,
+    NamedSenderNotVerified,
     QueuedEmail,
     QuotaLimited,
     RecipientSuppressed,
@@ -524,7 +525,7 @@ def _code_send_sender(team_id: int, address: str | None) -> dict[str, Any]:
         sender = code_send_sender(team_id=team_id, email=email or None, name=name or None)
     except TransactionalEmailSenderUnavailable as e:
         if address:
-            raise SenderNotVerified(f"No verified sender in this project can send from `{email}`.") from e
+            raise NamedSenderNotVerified(f"No verified sender in this project can send from `{email}`.") from e
         raise SenderNotVerified("The project has no verified default email sender.") from e
     return {"integrationId": sender.integration_id, "email": sender.email, "name": sender.name}
 
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index e2090dc395c8..255121657582 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -651,7 +651,7 @@ def test_a_send_by_template_key_runs_the_templates_workflow(
                 {"template": {"key": "password-reset"}, "from": "security@example.org"},
                 status.HTTP_400_BAD_REQUEST,
                 "sender_not_verified",
-                None,
+                "from",
             ),
         ]
     )
@@ -672,11 +672,20 @@ def test_refuses_a_code_send_from_an_unverified_domain(self, mock_post, _flag, c
         )
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
-        assert response.json()["code"] == "sender_not_verified"
+        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", "from")
         assert not TransactionalEmailKey.objects.for_team(self.team.id).exists()
         assert capture.call_args.kwargs["properties"]["error_code"] == "sender_not_verified"
         mock_post.assert_not_called()
 
+    def test_a_code_send_without_from_names_no_field_when_the_project_has_no_sender(self, mock_post, _flag, _capture):
+        TeamWorkflowsConfig.objects.filter(team_id=self.team.id).update(default_email_integration_id=None)
+
+        response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, self._code_send(), format="json")
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", None)
+        mock_post.assert_not_called()
+
     def test_a_code_send_the_pipeline_does_not_confirm_warns_it_may_still_go_out(self, mock_post, _flag, _capture):
         mock_post.side_effect = requests.ReadTimeout()
 

From ad25625b364cee1a96ce0c82125fdac8038c6c48 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:08:33 +0000
Subject: [PATCH 18/42] fix(messaging): say what a null managed_by means on a
 template

Null marks a template made in PostHog that no upload ever claimed. The
help text said it meant gui, which a later check could read as released
from code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../migrations/0015_messagetemplate_code_managed_fields.py    | 2 +-
 products/messaging/backend/models/message_template.py         | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py b/products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py
index f671e9c6eb5d..8a09596914a3 100644
--- a/products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py
+++ b/products/messaging/backend/migrations/0015_messagetemplate_code_managed_fields.py
@@ -24,7 +24,7 @@ class Migration(migrations.Migration):
             field=models.CharField(
                 blank=True,
                 choices=[("gui", "GUI"), ("code", "Code")],
-                help_text="Who owns the template content: `gui` for the PostHog app, `code` for uploads from a repository. Empty means `gui`.",
+                help_text="Who owns the template content: `code` for uploads from a repository, `gui` for a template released from code to the PostHog app. Null for a template made in PostHog and never uploaded.",
                 max_length=400,
                 null=True,
             ),
diff --git a/products/messaging/backend/models/message_template.py b/products/messaging/backend/models/message_template.py
index 91119380e3d7..444f5b5d8eab 100644
--- a/products/messaging/backend/models/message_template.py
+++ b/products/messaging/backend/models/message_template.py
@@ -45,8 +45,8 @@ class MessageTemplate(Taggable, UUIDTModel):
         choices=TemplateManagedBy.choices,
         null=True,
         blank=True,
-        help_text="Who owns the template content: `gui` for the PostHog app, `code` for uploads from a repository. "
-        "Empty means `gui`.",
+        help_text="Who owns the template content: `code` for uploads from a repository, `gui` for a template released "
+        "from code to the PostHog app. Null for a template made in PostHog and never uploaded.",
     )
     source_repository = models.CharField(
         max_length=400,

From 979d1e0419e55f0dc2b8503cc6d02bf8e42d5d53 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:14:33 +0000
Subject: [PATCH 19/42] fix(messaging): repair a drifted workflow on upload and
 keep paused code sends paused

An upload counts as unchanged only when the template's workflow still sends
the uploaded content, so a re-upload repairs a workflow edited elsewhere.
A first upload under a key whose code sends are paused is refused, because
taking the key over would start those sends again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../backend/services/template_uploads.py      | 25 +++++++--
 .../backend/tests/api/test_template_upload.py | 54 ++++++++++++++++---
 .../backend/facade/transactional_emails.py    |  4 ++
 .../services/transactional_email_workflows.py | 20 ++++++-
 4 files changed, 92 insertions(+), 11 deletions(-)

diff --git a/products/messaging/backend/services/template_uploads.py b/products/messaging/backend/services/template_uploads.py
index 4ad56332ad4f..def8a524bf82 100644
--- a/products/messaging/backend/services/template_uploads.py
+++ b/products/messaging/backend/services/template_uploads.py
@@ -12,6 +12,7 @@
     TemplateSource,
     TemplateUpload,
     TemplateUploadResult,
+    TransactionalEmailPaused,
 )
 from products.messaging.backend.models import MessageTemplate
 from products.messaging.backend.models.message_template import KEY_CONSTRAINT
@@ -19,6 +20,7 @@
 from products.messaging.backend.services.message_templates import record_content_hash
 from products.messaging.backend.services.template_saves import WorkflowEditorCheck, save_locked_template
 from products.messaging.backend.services.transactional_email import is_transactional, known_key, make_transactional
+from products.workflows.backend.facade.transactional_emails import code_sends_paused, transactional_email_workflow_email
 
 SOURCE_PARTS = ("repository", "path", "ref")
 
@@ -71,7 +73,7 @@ def _upload(
 ) -> Uploaded:
     template = locked_template_with_key(team_id, upload.key)
     if template is None or template.managed_by is None:
-        _require_editor_of_the_key_workflow(team_id, upload.key, require_workflow_editor)
+        _require_the_key_workflow_can_be_taken_over(team_id, upload.key, require_workflow_editor)
     if template is None:
         require_workflow_create()
         return Uploaded(result=TemplateUploadResult.CREATED, template=_create(team_id, upload, user_id=user_id))
@@ -95,10 +97,18 @@ def _upload(
     return Uploaded(result=TemplateUploadResult.UPDATED, template=template)
 
 
-def _require_editor_of_the_key_workflow(team_id: int, key: str, require_workflow_editor: WorkflowEditorCheck) -> None:
+def _require_the_key_workflow_can_be_taken_over(
+    team_id: int, key: str, require_workflow_editor: WorkflowEditorCheck
+) -> None:
     key_workflow = known_key(team_id, key)
-    if key_workflow is not None:
-        require_workflow_editor(key_workflow.hog_flow_id)
+    if key_workflow is None:
+        return
+    require_workflow_editor(key_workflow.hog_flow_id)
+    if code_sends_paused(team_id, key_workflow.hog_flow_id):
+        raise TransactionalEmailPaused(
+            "Code sends under this key are paused, so an upload can't take them over. Resume them in Workflows, "
+            "then upload again."
+        )
 
 
 def locked_template_with_key(team_id: int, key: str) -> MessageTemplate | None:
@@ -169,9 +179,16 @@ def _is_unchanged(template: MessageTemplate, upload: TemplateUpload) -> bool:
         and template.content_hash == uploaded_hash
         and template.managed_by == TemplateManagedBy.CODE
         and is_transactional(template)
+        and email_content_hash(_sent_email(template)) == uploaded_hash
     )
 
 
+def _sent_email(template: MessageTemplate) -> dict[str, Any]:
+    if template.transactional_hog_flow_id is None:
+        return {}
+    return transactional_email_workflow_email(template.team_id, template.transactional_hog_flow_id)
+
+
 def _is_superseded(template: MessageTemplate, upload: TemplateUpload) -> bool:
     uploaded_hash = email_content_hash(_email(upload))
     state = sent_hash_state(uploaded_hash, template.content_hash, template.superseded_content_hashes or [])
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index fff1fc79e2e7..acf77f9cfb09 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -3,6 +3,8 @@
 from posthog.test.base import APIBaseTest
 from unittest.mock import MagicMock, patch
 
+from django.utils import timezone
+
 from parameterized import parameterized
 from rest_framework import status
 from rest_framework.test import APIClient
@@ -22,6 +24,7 @@
 )
 from products.messaging.backend.services import template_uploads
 from products.workflows.backend.facade.api import set_default_email_sender_if_unset
+from products.workflows.backend.models import HogFlow
 
 WELCOME: dict[str, Any] = {
     "name": "Welcome",
@@ -144,14 +147,32 @@ def test_an_identical_upload_is_unchanged_and_writes_no_workflow_version(
             edited.call_args.kwargs["updated_at"] == MessageTemplate.objects.get(id=first["id"]).updated_at.isoformat()
         )
 
-    def test_an_upload_repairs_a_stored_hash_that_does_not_describe_the_content(self, _post, _flag, _capture):
+    def _edit_the_workflow_outside_the_template(self, hog_flow_id: str) -> None:
+        workflow = HogFlow.objects.get(team=self.team, id=hog_flow_id)
+        workflow.actions[1]["config"]["inputs"]["email"]["value"]["html"] = "<p>Edited in the workflow</p>"
+        HogFlow.objects.filter(team=self.team, id=hog_flow_id).update(actions=workflow.actions)
+
+    @parameterized.expand(
+        [
+            (
+                "stored_hash",
+                lambda test, upload: MessageTemplate.objects.filter(id=upload["id"]).update(content_hash=GREETING_HASH),
+            ),
+            (
+                "workflow_edited_outside_the_template",
+                lambda test, upload: test._edit_the_workflow_outside_the_template(upload["transactional_hog_flow_id"]),
+            ),
+        ]
+    )
+    def test_an_upload_repairs_what_no_longer_matches_the_uploaded_content(self, _post, _flag, _capture, _name, drift):
         first = self._upload(WELCOME)
-        MessageTemplate.objects.filter(id=first["id"]).update(content_hash=GREETING_HASH)
+        drift(self, first)
 
         repaired = self._upload(WELCOME)
 
         assert (repaired["result"], repaired["content_hash"]) == ("updated", WELCOME_HASH)
         assert self._template(first["id"])["content_hash"] == WELCOME_HASH
+        assert self._sent_email(first["transactional_hog_flow_id"])["html"] == WELCOME["html"]
 
     @patch("products.messaging.backend.services.transactional_email.reload_hog_flows_on_workers")
     def test_a_changed_upload_is_what_the_next_send_delivers(self, _reload, post: MagicMock, _flag, _capture):
@@ -302,9 +323,7 @@ def test_refuses_an_upload_it_does_not_allow(
         assert response.status_code == expected_status, response.json()
         assert not MessageTemplate.objects.exists()
 
-    def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edit(
-        self, post: MagicMock, _flag, _capture
-    ):
+    def _code_send_under_the_key(self, post: MagicMock) -> str:
         post.return_value = MagicMock(status_code=202, json=lambda: {"invocation_id": "invocation-1"})
         code_send = {
             "to": "user@example.com",
@@ -315,7 +334,30 @@ def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edi
         }
         sent = self.psak.post(f"/api/projects/{self.team.id}/messaging/send/email/", code_send, format="json")
         assert sent.status_code == status.HTTP_202_ACCEPTED, sent.json()
-        key_workflow_id = post.call_args.args[0].split("/hog_flows/")[1].split("/")[0]
+        return post.call_args.args[0].split("/hog_flows/")[1].split("/")[0]
+
+    @parameterized.expand(
+        [
+            ("email_sending_paused", lambda: {"email_sending_paused_at": timezone.now()}),
+            ("not_active", lambda: {"status": "draft"}),
+        ]
+    )
+    def test_refuses_a_first_upload_under_a_key_whose_code_sends_are_paused(
+        self, post: MagicMock, _flag, _capture, _name, pause
+    ):
+        key_workflow_id = self._code_send_under_the_key(post)
+        HogFlow.objects.filter(team=self.team, id=key_workflow_id).update(**pause())
+
+        response = self.psak.put(self.url, WELCOME, format="json")
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        assert response.json()["code"] == "transactional_email_paused"
+        assert not MessageTemplate.objects.exists()
+
+    def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edit(
+        self, post: MagicMock, _flag, _capture
+    ):
+        key_workflow_id = self._code_send_under_the_key(post)
         self.organization.available_product_features = [
             {"name": AvailableFeature.ACCESS_CONTROL, "key": AvailableFeature.ACCESS_CONTROL}
         ]
diff --git a/products/workflows/backend/facade/transactional_emails.py b/products/workflows/backend/facade/transactional_emails.py
index 649b298b1ac2..179db8560860 100644
--- a/products/workflows/backend/facade/transactional_emails.py
+++ b/products/workflows/backend/facade/transactional_emails.py
@@ -9,9 +9,11 @@
 )
 from products.workflows.backend.services.transactional_email_workflows import (
     code_send_sender,
+    code_sends_paused,
     create_code_email_workflow,
     create_transactional_email_workflow,
     resolve_transactional_email_sender,
+    transactional_email_workflow_email,
     update_transactional_email_workflow,
 )
 
@@ -22,8 +24,10 @@
     "TransactionalEmailSenderUnavailable",
     "WorkflowNotFound",
     "code_send_sender",
+    "code_sends_paused",
     "create_code_email_workflow",
     "create_transactional_email_workflow",
     "resolve_transactional_email_sender",
+    "transactional_email_workflow_email",
     "update_transactional_email_workflow",
 ]
diff --git a/products/workflows/backend/services/transactional_email_workflows.py b/products/workflows/backend/services/transactional_email_workflows.py
index 2e833141a771..c269e9071710 100644
--- a/products/workflows/backend/services/transactional_email_workflows.py
+++ b/products/workflows/backend/services/transactional_email_workflows.py
@@ -2,7 +2,7 @@
 and an exit. The message template it was made from owns the content, so each content change writes a new version
 of the workflow through the same write path as the workflows UI, with its revision history."""
 
-from typing import Optional
+from typing import Any, Optional
 from uuid import UUID
 
 from django.db import transaction
@@ -54,6 +54,24 @@ def transactional_email_actions(content: TransactionalEmailContent, from_integra
     )
 
 
+def code_sends_paused(team_id: int, hog_flow_id: UUID) -> bool:
+    flow = HogFlow.objects.filter(team_id=team_id, pk=hog_flow_id).only("status", "email_sending_paused_at").first()
+    return flow is not None and (flow.status != HogFlow.State.ACTIVE or flow.email_sending_paused_at is not None)
+
+
+def transactional_email_workflow_email(team_id: int, hog_flow_id: UUID) -> dict[str, Any]:
+    actions = HogFlow.objects.filter(team_id=team_id, pk=hog_flow_id).values_list("actions", flat=True).first()
+    email_step = next(
+        (
+            action
+            for action in actions or []
+            if isinstance(action, dict) and action.get("id") == TRANSACTIONAL_EMAIL_ACTION_ID
+        ),
+        {},
+    )
+    return ((email_step.get("config") or {}).get("inputs") or {}).get("email", {}).get("value") or {}
+
+
 def code_email_actions(key: str) -> list[dict]:
     return _actions(
         name=key,

From 8c9fa9fe61619d397727a6e1526a8e80b09108a5 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:14:35 +0000
Subject: [PATCH 20/42] chore(messaging): drop an unused key lookup and test an
 unclaimed key

A code send under the key of a template no upload claimed stays on the
key's own workflow, and a test now pins that.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../backend/services/message_templates.py       |  4 ----
 .../tests/api/test_transactional_email.py       | 17 +++++++++++++----
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/products/messaging/backend/services/message_templates.py b/products/messaging/backend/services/message_templates.py
index 61ec620c9dfb..f0cfb766c8c0 100644
--- a/products/messaging/backend/services/message_templates.py
+++ b/products/messaging/backend/services/message_templates.py
@@ -90,10 +90,6 @@ def team_template(team_id: int, template_id: UUID | str) -> MessageTemplate:
     return MessageTemplate.objects.get(team_id=team_id, deleted=False, pk=template_id)
 
 
-def team_template_with_key(team_id: int, key: str) -> MessageTemplate:
-    return MessageTemplate.objects.get(team_id=team_id, deleted=False, key=key)
-
-
 def category_id_for_team(team_id: int, category_id: Any) -> UUID:
     # Not filtered on deleted, as the related field this serves never was.
     return MessageCategory.objects.get(team_id=team_id, pk=category_id).pk
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 9d335e91041d..a45bcc6c91e8 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -387,11 +387,20 @@ def _code_send(self, **fields: Any) -> dict[str, Any]:
             **fields,
         }
 
-    @parameterized.expand([("new_key", "welcome"), ("key_of_an_uploaded_template", "password-reset")])
-    def test_a_code_send_goes_out_as_is_under_the_keys_workflow(self, mock_post, _flag, capture, _name, key):
+    @parameterized.expand(
+        [
+            ("new_key", "welcome", True),
+            ("key_of_an_uploaded_template", "password-reset", True),
+            ("key_of_a_template_no_upload_claimed", "password-reset", False),
+        ]
+    )
+    def test_a_code_send_goes_out_as_is_under_the_keys_workflow(
+        self, mock_post, _flag, capture, _name, key, template_claimed
+    ):
         MessageTemplate.objects.filter(id=self.template.id).update(key="password-reset")
         self._cdp_accepts(mock_post)
-        self._claim_by_upload(self.template)
+        if template_claimed:
+            self._claim_by_upload(self.template)
         templates_before = MessageTemplate.objects.filter(team=self.team).count()
         psak = self._psak_client(["hog_flow:write"])
 
@@ -405,7 +414,7 @@ def test_a_code_send_goes_out_as_is_under_the_keys_workflow(self, mock_post, _fl
         assert first_url == second_url
         assert first_url.endswith("/transactional_email/send")
         hog_flow_id = first_url.split("/hog_flows/")[1].split("/")[0]
-        if key == "password-reset":
+        if key == "password-reset" and template_claimed:
             assert hog_flow_id == str(self.hog_flow_id)
         else:
             assert TransactionalEmailKey.objects.for_team(self.team.id).get(key=key).hog_flow_id == UUID(hog_flow_id)

From 62c59f3a8a9cc91112bba4b2d7f1fa478b08944a Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:22:31 +0000
Subject: [PATCH 21/42] fix(messaging): check the key workflow's access on
 adoption and name a key change

Adopting a key now needs editor access to the workflow that already sends
under it, so a later upload can't move those sends to a template the member
controls. A new key on a code-managed template now answers key_already_set
instead of the lock's refusal, whose fix would not have helped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/facade/templates.py     |  1 +
 .../backend/services/template_keys.py         | 16 ++++++++++--
 .../api/test_code_managed_template_lock.py    |  9 +++++++
 .../tests/api/test_template_adoption.py       | 26 ++++++++++++++++++-
 4 files changed, 49 insertions(+), 3 deletions(-)

diff --git a/products/messaging/backend/facade/templates.py b/products/messaging/backend/facade/templates.py
index eb3190b3e1bc..b00730cd33af 100644
--- a/products/messaging/backend/facade/templates.py
+++ b/products/messaging/backend/facade/templates.py
@@ -189,6 +189,7 @@ def save_template_content(
 
 
 def check_template_write(template: MessageTemplateRow, intent: TemplateWriteIntent) -> None:
+    template_keys.check_key_kept(template, intent)
     template_ownership.check_write(template, intent)
 
 
diff --git a/products/messaging/backend/services/template_keys.py b/products/messaging/backend/services/template_keys.py
index 256ea32bd832..a0fd0d3264c4 100644
--- a/products/messaging/backend/services/template_keys.py
+++ b/products/messaging/backend/services/template_keys.py
@@ -8,6 +8,7 @@
 from products.messaging.backend.models.message_template import KEY_CONSTRAINT
 from products.messaging.backend.services.template_ownership import check_write, patches_only
 from products.messaging.backend.services.template_saves import WorkflowEditorCheck, lock_template
+from products.messaging.backend.services.transactional_email import known_key
 
 
 class KeyedTemplate(Protocol):
@@ -19,11 +20,15 @@ def is_adoption(intent: TemplateWriteIntent) -> bool:
     return patches_only(intent, "key")
 
 
+def check_key_kept(template: KeyedTemplate, intent: TemplateWriteIntent) -> None:
+    if template.key and "key" in intent.payload and intent.payload["key"] != template.key:
+        raise _key_already_set(template.key)
+
+
 def check_key_unchanged(template: KeyedTemplate, intent: TemplateWriteIntent) -> None:
+    check_key_kept(template, intent)
     if "key" not in intent.payload or intent.payload["key"] == template.key:
         return
-    if template.key:
-        raise _key_already_set(template.key)
     raise TemplateKeyRefused(
         code="invalid_request",
         detail="`key` can't be set together with other fields.",
@@ -48,6 +53,7 @@ def adopt_template(
                 require_workflow_editor(template.transactional_hog_flow_id)
             if template.key:
                 raise _key_already_set(template.key)
+            _require_editor_of_the_key_workflow(team_id, key, require_workflow_editor)
             template.key = key
             template.save(update_fields=["key", "updated_at"])
     except IntegrityError as error:
@@ -57,6 +63,12 @@ def adopt_template(
     return template
 
 
+def _require_editor_of_the_key_workflow(team_id: int, key: str, require_workflow_editor: WorkflowEditorCheck) -> None:
+    key_workflow = known_key(team_id, key)
+    if key_workflow is not None:
+        require_workflow_editor(key_workflow.hog_flow_id)
+
+
 def _key_already_set(key: str) -> TemplateKeyRefused:
     return TemplateKeyRefused(
         code="key_already_set",
diff --git a/products/messaging/backend/tests/api/test_code_managed_template_lock.py b/products/messaging/backend/tests/api/test_code_managed_template_lock.py
index 783822b8d34a..205b424ddb93 100644
--- a/products/messaging/backend/tests/api/test_code_managed_template_lock.py
+++ b/products/messaging/backend/tests/api/test_code_managed_template_lock.py
@@ -103,6 +103,15 @@ def test_refuses_an_edit_and_says_how_to_change_it_in_code(
         )
         assert self._workflow_version(uploaded["transactional_hog_flow_id"]) == 1
 
+    def test_a_new_key_for_a_code_managed_template_is_refused_as_a_key_change(self, _post, _flag, _capture):
+        uploaded = self._upload(WELCOME)
+
+        response = self.client.patch(self._url(uploaded["id"]), {"key": "other"}, format="json")
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        assert (response.json()["code"], response.json()["attr"]) == ("key_already_set", "key")
+        assert self._template(uploaded["id"])["key"] == "welcome"
+
     def test_an_mcp_update_gets_the_same_refusal(self, _post, _flag, _capture):
         uploaded = self._upload(WELCOME)
         token = generate_random_token_personal()
diff --git a/products/messaging/backend/tests/api/test_template_adoption.py b/products/messaging/backend/tests/api/test_template_adoption.py
index ce9a8b5f41db..295b4160befd 100644
--- a/products/messaging/backend/tests/api/test_template_adoption.py
+++ b/products/messaging/backend/tests/api/test_template_adoption.py
@@ -6,11 +6,15 @@
 from rest_framework import status
 from rest_framework.test import APIClient
 
-from posthog.models import ProjectSecretAPIKey
+from posthog.constants import AvailableFeature
+from posthog.models import OrganizationMembership, ProjectSecretAPIKey
 from posthog.models.personal_api_key import PersonalAPIKey, hash_key_value
 from posthog.models.utils import generate_random_token_personal, generate_random_token_secret
 
+from products.access_control.backend.models.access_control import AccessControl
 from products.messaging.backend.models.message_template import MessageTemplate
+from products.messaging.backend.models.transactional_email_key import TransactionalEmailKey
+from products.workflows.backend.models import HogFlow
 
 DOCS_URL = "https://posthog.com/docs/workflows/transactional-email-api"
 
@@ -72,6 +76,26 @@ def test_gives_a_template_without_a_key_its_key_and_keeps_its_content(self, _nam
         assert adopted["content"]["email"]["subject"] == "Hello"
         assert self._stored_key() == "welcome"
 
+    def test_refuses_a_key_whose_code_send_workflow_the_member_cannot_edit(self):
+        key_workflow = HogFlow.objects.create(team=self.team, name="welcome", status="active")
+        TransactionalEmailKey.objects.for_team(self.team.id).create(
+            team=self.team, key="welcome", hog_flow_id=key_workflow.id
+        )
+        self.organization.available_product_features = [
+            {"name": AvailableFeature.ACCESS_CONTROL, "key": AvailableFeature.ACCESS_CONTROL}
+        ]
+        self.organization.save()
+        self.organization_membership.level = OrganizationMembership.Level.MEMBER
+        self.organization_membership.save()
+        AccessControl.objects.create(
+            team=self.team, resource="hog_flow", resource_id=str(key_workflow.id), access_level="viewer"
+        )
+
+        response = self._adopt("welcome")
+
+        assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
+        assert self._stored_key() is None
+
     def test_a_project_secret_api_key_cannot_adopt(self):
         response = self._adopt("welcome", self._project_secret_api_key_client())
 

From dd818eff9595e34ca562ade3e2a90f41b6040daf Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:28:40 +0000
Subject: [PATCH 22/42] fix(messaging): compare a drifted workflow with the
 text a code template sends

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 products/messaging/backend/services/template_uploads.py  | 9 +++++++--
 .../messaging/backend/services/transactional_email.py    | 6 ++++++
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/products/messaging/backend/services/template_uploads.py b/products/messaging/backend/services/template_uploads.py
index def8a524bf82..060193832cab 100644
--- a/products/messaging/backend/services/template_uploads.py
+++ b/products/messaging/backend/services/template_uploads.py
@@ -19,7 +19,12 @@
 from products.messaging.backend.services.content_hash import email_content_hash, sent_hash_state
 from products.messaging.backend.services.message_templates import record_content_hash
 from products.messaging.backend.services.template_saves import WorkflowEditorCheck, save_locked_template
-from products.messaging.backend.services.transactional_email import is_transactional, known_key, make_transactional
+from products.messaging.backend.services.transactional_email import (
+    is_transactional,
+    known_key,
+    make_transactional,
+    sent_email_hash,
+)
 from products.workflows.backend.facade.transactional_emails import code_sends_paused, transactional_email_workflow_email
 
 SOURCE_PARTS = ("repository", "path", "ref")
@@ -179,7 +184,7 @@ def _is_unchanged(template: MessageTemplate, upload: TemplateUpload) -> bool:
         and template.content_hash == uploaded_hash
         and template.managed_by == TemplateManagedBy.CODE
         and is_transactional(template)
-        and email_content_hash(_sent_email(template)) == uploaded_hash
+        and email_content_hash(_sent_email(template)) == sent_email_hash(template)
     )
 
 
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index 8ad558513b03..088beec8b6dc 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -49,6 +49,7 @@
 from products.messaging.backend.models import MessageCategory, MessageTemplate, TransactionalEmailKey
 from products.messaging.backend.models.message_category import MessageCategoryType
 from products.messaging.backend.models.transactional_email_key import TRANSACTIONAL_EMAIL_KEY_CONSTRAINT
+from products.messaging.backend.services.content_hash import email_content_hash
 from products.messaging.backend.services.html_text import text_from_html
 from products.workflows.backend.facade.api import WorkflowNotFound, get_workflow_summary
 from products.workflows.backend.facade.transactional_emails import (
@@ -243,6 +244,11 @@ def _content(template: MessageTemplate) -> TransactionalEmailContent:
     )
 
 
+def sent_email_hash(template: MessageTemplate) -> str:
+    email = template.content["email"]
+    return email_content_hash({**email, "text": _sent_text(template, email)})
+
+
 def _sent_text(template: MessageTemplate, email: dict[str, Any]) -> str:
     text = email.get("text") or ""
     if text or template.managed_by != TemplateManagedBy.CODE:

From 723e264337f9ce33e2ae13e5ecfad9777e21627b Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:38:43 +0000
Subject: [PATCH 23/42] fix(messaging): take capture_engagement on a send by
 template id and answer an unconfirmed key send

A send by template.key now answers an unconfirmed send like a code send and
reports a distinct addressed_by. A send by template.id takes capture_engagement
and points from and reply_to to template.key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../presentation/views/message_templates.py   | 43 ++++++++-----
 .../tests/api/test_transactional_email.py     | 60 ++++++++++++++++---
 .../frontend/generated/api.schemas.ts         |  6 +-
 .../messaging/frontend/generated/api.zod.ts   |  6 +-
 services/mcp/src/api/generated.ts             |  6 +-
 .../mcp/src/generated/email_templates/api.ts  |  6 +-
 .../tool-schemas/workflows-send-email.json    |  6 +-
 7 files changed, 96 insertions(+), 37 deletions(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index d424f56d8c9e..c26669b95e73 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -544,8 +544,8 @@ def refuse_unknown_fields(sent: Iterable[str], known: Mapping[str, Any]) -> None
         )
 
 
-CODE_SEND_FIELDS = ("template_key", "subject", "html", "text", "from", "reply_to", "capture_engagement")
 RENDERED_CONTENT_FIELDS = ("subject", "html", "text")
+TEMPLATE_ID_REFUSED_FIELDS = ("template_key", *RENDERED_CONTENT_FIELDS, "from", "reply_to")
 
 
 class SendEmailSerializer(SendTransactionalEmailSerializer):
@@ -584,22 +584,22 @@ class SendEmailSerializer(SendTransactionalEmailSerializer):
     )
     from_address = serializers.CharField(
         required=False,
-        help_text="Sender of the email your code rendered, as `security@example.com` or "
-        "`Example <security@example.com>`, on a verified domain of the project. Without it, the email goes out from "
-        "the project's default sender.",
+        help_text="Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified "
+        "domain of the project. Without it, a send with `template_key` goes out from the project's default sender, "
+        "and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it.",
     )
     reply_to = serializers.ListField(
         child=serializers.EmailField(),
         required=False,
         allow_empty=False,
         max_length=10,
-        help_text="Addresses replies to the email your code rendered go to.",
+        help_text="Addresses replies to the email go to. A send by `template.id` doesn't take it.",
     )
     capture_engagement = serializers.BooleanField(
         required=False,
-        help_text="Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email your code "
-        "rendered are captured as analytics events of the recipient. Defaults to true. A project whose admin turned "
-        "engagement capture off captures nothing, whatever the send says.",
+        help_text="Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are "
+        "captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement "
+        "capture off captures nothing, whatever the send says.",
     )
 
     def get_fields(self) -> dict[str, serializers.Field]:
@@ -639,9 +639,18 @@ def _validate_template(template: Mapping[str, Any], sent: set[str]) -> None:
             raise serializers.ValidationError(
                 {"template": "Name the template with either `key`, and an optional `hash`, or `id`."}
             )
-        refused = CODE_SEND_FIELDS if "id" in template else RENDERED_CONTENT_FIELDS
-        if code_field := next((field for field in refused if field in sent), None):
-            raise serializers.ValidationError({code_field: "Only a send with `template_key` takes this field."})
+        refused = TEMPLATE_ID_REFUSED_FIELDS if "id" in template else RENDERED_CONTENT_FIELDS
+        if field := next((field for field in refused if field in sent), None):
+            raise serializers.ValidationError({field: _refusal_on_a_template_send(field)})
+
+
+def _refusal_on_a_template_send(field: str) -> str:
+    if field in ("from", "reply_to"):
+        return (
+            "A template made in PostHog sends with its own settings. Send by `template.key` to set this field on a "
+            "template uploaded from code."
+        )
+    return "Only a send with `template_key` takes this field."
 
 
 def _is_sender_address(address: str) -> bool:
@@ -881,7 +890,9 @@ def _end_request_validation(self) -> None:
     def _require_transactional_email_flag(self) -> None:
         require_transactional_email_api(self.team)
 
-    def _queue_transactional_email(self, request: Any, template: MessageTemplateRow, *, route: str) -> Response:
+    def _queue_transactional_email(
+        self, request: Any, template: MessageTemplateRow, *, route: str, options: TemplateSendOptions | None = None
+    ) -> Response:
         with transactional_email_stage("workflow_access"):
             if template.transactional_hog_flow_id:
                 self._require_workflow_editor(template.transactional_hog_flow_id)
@@ -895,6 +906,7 @@ def _queue_transactional_email(self, request: Any, template: MessageTemplateRow,
                 distinct_id=_distinct_id(data),
                 message_data=data["message_data"],
                 idempotency_key=idempotency_key,
+                options=options,
             ),
             route=route,
             addressed={"template_id": str(template.id)},
@@ -1577,7 +1589,9 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
             except MessageTemplateMissing:
                 raise NotFound()
             self.check_object_permissions(request, template)
-        return self._queue_transactional_email(request, template, route="send_email")
+        return self._queue_transactional_email(
+            request, template, route="send_email", options=_template_send_options(request.data, request.validated_data)
+        )
 
     def _send_template_by_key(self, request: Any) -> Response:
         with transactional_email_stage("feature_flag"):
@@ -1616,10 +1630,11 @@ def send(idempotency_key: str | None) -> QueuedEmail:
             send,
             route="send_email",
             addressed={
-                "addressed_by": "template_key",
+                "addressed_by": "template.key",
                 "template_id": str(template.id),
                 "hash_state": str(found.hash_state),
             },
+            unavailable=UnconfirmedEmailSend,
             warnings=[TEMPLATE_SUPERSEDED_WARNING] if found.hash_state == ContentHashState.SUPERSEDED else [],
         )
 
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 7ead3caa3c42..4d5512192ec4 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -24,8 +24,8 @@
 from products.messaging.backend.models.message_template import MessageTemplate
 from products.messaging.backend.models.transactional_email_key import TransactionalEmailKey
 from products.messaging.backend.presentation.views.message_templates import (
-    CODE_SEND_FIELDS,
     EMAIL_FROM_CODE_FLAG,
+    TEMPLATE_ID_REFUSED_FIELDS,
     TRANSACTIONAL_EMAIL_API_FLAG,
 )
 from products.messaging.backend.services import transactional_email
@@ -518,13 +518,45 @@ def test_refuses_a_code_send_with_an_invalid_field(self, mock_post, _flag, _capt
         assert response.json()["attr"] == attr
         mock_post.assert_not_called()
 
-    def test_refuses_code_fields_on_a_template_send(self, mock_post, _flag, _capture):
-        response = self._send(self._psak_client(["hog_flow:write"]), "send_email", {**self.body, "subject": "Hi"})
+    @parameterized.expand(
+        [
+            ("subject", {"subject": "Hi"}, "template_key"),
+            ("sender", {"from": "hello@example.com"}, "template.key"),
+            ("reply_to", {"reply_to": ["help@example.com"]}, "template.key"),
+        ]
+    )
+    def test_refuses_on_a_send_by_template_id_what_its_template_sets(
+        self, mock_post, _flag, _capture, _name, fields, form_that_takes_it
+    ):
+        response = self._send(self._psak_client(["hog_flow:write"]), "send_email", {**self.body, **fields})
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
-        assert response.json()["attr"] == "subject"
+        assert response.json()["attr"] == next(iter(fields))
+        assert f"`{form_that_takes_it}`" in response.json()["detail"]
         mock_post.assert_not_called()
 
+    @parameterized.expand(
+        [
+            ("by_default", {}, "transactional_email", None),
+            (
+                "without_engagement_capture",
+                {"capture_engagement": False},
+                "transactional_email/send",
+                {"tracking": {"captureEngagement": False}},
+            ),
+        ]
+    )
+    def test_a_send_by_template_id_carries_its_engagement_capture(
+        self, mock_post, _flag, _capture, _name, fields, route, sent
+    ):
+        self._cdp_accepts(mock_post)
+
+        response = self._send(self._psak_client(["hog_flow:write"]), "send_email", {**self.body, **fields})
+
+        assert response.status_code == status.HTTP_202_ACCEPTED, response.json()
+        assert mock_post.call_args.args[0].endswith(f"/hog_flows/{self.hog_flow_id}/{route}")
+        assert mock_post.call_args.kwargs["json"].get("send") == sent
+
     def _keyed(self) -> dict[str, Any]:
         MessageTemplate.objects.filter(id=self.template.id).update(
             key="password-reset",
@@ -600,7 +632,7 @@ def test_a_send_by_template_key_runs_the_templates_workflow(
         else:
             assert "send" not in posted
         reported = capture.call_args.kwargs["properties"]
-        assert (reported["addressed_by"], reported["template_id"]) == ("template_key", str(self.template.id))
+        assert (reported["addressed_by"], reported["template_id"]) == ("template.key", str(self.template.id))
 
     @parameterized.expand(
         [
@@ -700,10 +732,18 @@ def test_refuses_a_code_send_from_an_unverified_domain(self, mock_post, _flag, c
         assert capture.call_args.kwargs["properties"]["error_code"] == "sender_not_verified"
         mock_post.assert_not_called()
 
-    def test_a_code_send_the_pipeline_does_not_confirm_warns_it_may_still_go_out(self, mock_post, _flag, _capture):
+    @parameterized.expand(
+        [
+            ("code_send", lambda test: test._code_send()),
+            ("send_by_template_key", lambda test: test._keyed()),
+        ]
+    )
+    def test_a_send_from_code_the_pipeline_does_not_confirm_warns_it_may_still_go_out(
+        self, mock_post, _flag, _capture, _name, body
+    ):
         mock_post.side_effect = requests.ReadTimeout()
 
-        response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, self._code_send(), format="json")
+        response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, body(self), format="json")
 
         assert response.status_code == status.HTTP_503_SERVICE_UNAVAILABLE
         assert response.json()["code"] == "delivery_unavailable"
@@ -716,7 +756,11 @@ def test_the_send_schema_gives_a_template_send_no_code_only_field(self, _mock_po
         send_email = schema["paths"]["/api/projects/{project_id}/messaging/send/email/"]["post"]
         reference = send_email["requestBody"]["content"]["application/json"]["schema"]["$ref"]
         fields = schema["components"]["schemas"][reference.rsplit("/", 1)[-1]]["properties"]
-        assert {name: fields[name]["default"] for name in CODE_SEND_FIELDS if "default" in fields[name]} == {}
+        assert {
+            name: fields[name]["default"]
+            for name in (*TEMPLATE_ID_REFUSED_FIELDS, "capture_engagement")
+            if "default" in fields[name]
+        } == {}
 
     @parameterized.expand(
         [
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index 1b5392eb15c9..df28b81701da 100644
--- a/products/messaging/frontend/generated/api.schemas.ts
+++ b/products/messaging/frontend/generated/api.schemas.ts
@@ -106,13 +106,13 @@ export interface SendEmailApi {
     /** Plain text body of the email your code rendered. Without it, PostHog derives the text from `html`. */
     text?: string
     /**
-     * Addresses replies to the email your code rendered go to.
+     * Addresses replies to the email go to. A send by `template.id` doesn't take it.
      * @maxItems 10
      */
     reply_to?: string[]
-    /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email your code rendered are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. */
+    /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. */
     capture_engagement?: boolean
-    /** Sender of the email your code rendered, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, the email goes out from the project's default sender. */
+    /** Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, a send with `template_key` goes out from the project's default sender, and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it. */
     from?: string
 }
 
diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.ts
index 6a90551fc2c5..c6e26dcd73f6 100644
--- a/products/messaging/frontend/generated/api.zod.ts
+++ b/products/messaging/frontend/generated/api.zod.ts
@@ -97,18 +97,18 @@ export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({
         .array(zod.email())
         .max(messagingSendEmailCreateBodyReplyToMax)
         .optional()
-        .describe('Addresses replies to the email your code rendered go to.'),
+        .describe("Addresses replies to the email go to. A send by `template.id` doesn't take it."),
     capture_engagement: zod
         .boolean()
         .optional()
         .describe(
-            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email your code rendered are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.'
+            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.'
         ),
     from: zod
         .string()
         .optional()
         .describe(
-            "Sender of the email your code rendered, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, the email goes out from the project's default sender."
+            "Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, a send with `template_key` goes out from the project's default sender, and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it."
         ),
 })
 
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index ccf9f741a478..35ef36bfa878 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -111018,13 +111018,13 @@ export namespace Schemas {
       /** Plain text body of the email your code rendered. Without it, PostHog derives the text from `html`. */
       text?: string;
       /**
-         * Addresses replies to the email your code rendered go to.
+         * Addresses replies to the email go to. A send by `template.id` doesn't take it.
          * @maxItems 10
          */
       reply_to?: string[];
-      /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email your code rendered are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. */
+      /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. */
       capture_engagement?: boolean;
-      /** Sender of the email your code rendered, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, the email goes out from the project's default sender. */
+      /** Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, a send with `template_key` goes out from the project's default sender, and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it. */
       from?: string;
     }
 
diff --git a/services/mcp/src/generated/email_templates/api.ts b/services/mcp/src/generated/email_templates/api.ts
index 159855b6c767..dc218d975565 100644
--- a/services/mcp/src/generated/email_templates/api.ts
+++ b/services/mcp/src/generated/email_templates/api.ts
@@ -63,18 +63,18 @@ export const MessagingSendEmailCreateBody = () => zod.object({
         .array(zod.email())
         .max(messagingSendEmailCreateBodyReplyToMax)
         .optional()
-        .describe('Addresses replies to the email your code rendered go to.'),
+        .describe("Addresses replies to the email go to. A send by `template.id` doesn't take it."),
     capture_engagement: zod
         .boolean()
         .optional()
         .describe(
-            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email your code rendered are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.'
+            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.'
         ),
     from: zod
         .string()
         .optional()
         .describe(
-            "Sender of the email your code rendered, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, the email goes out from the project's default sender."
+            "Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, a send with `template_key` goes out from the project's default sender, and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it."
         ),
 })
 
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
index 48054493e26f..7a7d82ee614a 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
@@ -2,7 +2,7 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "properties": {
         "capture_engagement": {
-            "description": "Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email your code rendered are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.",
+            "description": "Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.",
             "type": "boolean"
         },
         "distinct_id": {
@@ -11,7 +11,7 @@
             "type": "string"
         },
         "from": {
-            "description": "Sender of the email your code rendered, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, the email goes out from the project's default sender.",
+            "description": "Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, a send with `template_key` goes out from the project's default sender, and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it.",
             "type": "string"
         },
         "html": {
@@ -19,7 +19,7 @@
             "type": "string"
         },
         "reply_to": {
-            "description": "Addresses replies to the email your code rendered go to.",
+            "description": "Addresses replies to the email go to. A send by `template.id` doesn't take it.",
             "items": {
                 "format": "email",
                 "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",

From cb45a2575e7630bd352930c0e8b2dc38b953a324 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:42:12 +0000
Subject: [PATCH 24/42] fix(workflows): tell a failed template release once and
 keep refused edits until the person acts

A failed release toasts once, a publish an upload refused is no longer reported
as an exception, and the refused-edits banner has no close button that drops
the edits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 frontend/src/initKea.ts                       | 10 ++++---
 .../TemplateLibrary/RefusedEditsBanner.tsx    |  5 ++--
 .../messageTemplateLogic.test.ts              | 26 +++++++++++++++++++
 3 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/frontend/src/initKea.ts b/frontend/src/initKea.ts
index cbfc6972ca59..9e3fe0d94a21 100644
--- a/frontend/src/initKea.ts
+++ b/frontend/src/initKea.ts
@@ -144,6 +144,7 @@ const ERROR_FILTER_ALLOW_LIST_BY_LOGIC_PATH: Record<string, string> = {
     loadSummary: 'products.ai_observability.frontend.redesign.trace.traceSummaryLogic',
     requestSummary: 'products.ai_observability.frontend.redesign.trace.traceSummaryLogic',
     loadTracePullRequest: 'products.ai_observability.frontend.redesign.trace.traceGitPullRequestLogic', // The trace view's git chip stays plain when the read fails
+    releaseTemplate: 'products.workflows.frontend.messageTemplateLogic',
 }
 
 // A keyed logic's path ends with its key, so match the owner path as a prefix.
@@ -308,6 +309,9 @@ export function initKea({
                 const isSelfHandledValidationError =
                     error?.status === 400 &&
                     isOwnedByLogic(VALIDATION_ERROR_SELF_HANDLED_BY_LOGIC_PATH, actionKey, logic.pathString)
+                const isSelfHandledCodeManagedRefusal =
+                    error?.code === 'immutable' &&
+                    isOwnedByLogic(CODE_MANAGED_REFUSAL_SELF_HANDLED_BY_LOGIC_PATH, actionKey, logic.pathString)
                 if (
                     !ERROR_FILTER_ALLOW_LIST.includes(actionKey) &&
                     !isErrorSelfHandledByLogic(actionKey, logic.pathString) &&
@@ -333,9 +337,6 @@ export function initKea({
                         error.code === 'has_dependents' && HAS_DEPENDENTS_SELF_HANDLED.has(String(actionKey))
                     const isSelfHandledFieldError =
                         error.status === 400 && !!FIELD_ERROR_SELF_HANDLED[String(actionKey)]?.has(error.attr)
-                    const isSelfHandledCodeManagedRefusal =
-                        error.code === 'immutable' &&
-                        isOwnedByLogic(CODE_MANAGED_REFUSAL_SELF_HANDLED_BY_LOGIC_PATH, actionKey, logic.pathString)
 
                     if (!errorMessage && error.status === 404) {
                         errorMessage = 'URL not found'
@@ -387,7 +388,8 @@ export function initKea({
                     shouldReportApiFailure(error) &&
                     !isSelfHandledNotFound &&
                     !isSelfHandledExistingMember &&
-                    !isSelfHandledValidationError
+                    !isSelfHandledValidationError &&
+                    !isSelfHandledCodeManagedRefusal
                 ) {
                     posthog.captureException(error)
                 }
diff --git a/products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx b/products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx
index b08f293d449f..b6a076df45d6 100644
--- a/products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx
+++ b/products/workflows/frontend/TemplateLibrary/RefusedEditsBanner.tsx
@@ -9,7 +9,7 @@ export const DUPLICATE_REFUSED_EDITS_REASON = 'To keep your changes, use "Duplic
 export function RefusedEditsBanner(props: MessageTemplateLogicProps): JSX.Element | null {
     const logic = messageTemplateLogic(props)
     const { refusedEdits, isDuplicating } = useValues(logic)
-    const { duplicateWithMyChanges, setRefusedEdits } = useActions(logic)
+    const { duplicateWithMyChanges } = useActions(logic)
 
     if (!refusedEdits) {
         return null
@@ -19,7 +19,6 @@ export function RefusedEditsBanner(props: MessageTemplateLogicProps): JSX.Elemen
         <LemonBanner
             type="warning"
             className="shrink-0"
-            onClose={() => setRefusedEdits(null)}
             action={{
                 children: 'Duplicate with my changes',
                 onClick: duplicateWithMyChanges,
@@ -28,7 +27,7 @@ export function RefusedEditsBanner(props: MessageTemplateLogicProps): JSX.Elemen
             }}
         >
             Your changes weren't saved. While you were editing, an upload from code took this template back. To keep
-            your changes, duplicate the template with them. If you close this message, your changes are discarded.
+            your changes, duplicate the template with them.
         </LemonBanner>
     )
 }
diff --git a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
index 5b342b9aa932..25a49e00747c 100644
--- a/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
+++ b/products/workflows/frontend/TemplateLibrary/messageTemplateLogic.test.ts
@@ -1,5 +1,6 @@
 import { router } from 'kea-router'
 import { expectLogic } from 'kea-test-utils'
+import posthog from 'posthog-js'
 
 import { FEATURE_FLAGS } from 'lib/constants'
 import { featureFlagLogic } from 'lib/logic/featureFlagLogic'
@@ -592,6 +593,29 @@ describe('messageTemplateLogic', () => {
             ])
         })
 
+        it('tells the person once when the release fails', async () => {
+            useMocks({
+                patch: {
+                    '/api/environments/:team_id/messaging_templates/:id/': () => [
+                        403,
+                        {
+                            type: 'authentication_error',
+                            code: 'permission_denied',
+                            detail: 'You cannot edit its workflow.',
+                        },
+                    ],
+                },
+            })
+
+            await expectLogic(logic, () => {
+                logic.actions.releaseTemplate()
+            })
+                .toDispatchActions(['releaseTemplateFailure'])
+                .toFinishAllListeners()
+
+            expect(mockToast.error.mock.calls).toEqual([['You cannot edit its workflow.']])
+        })
+
         it('becomes editable once released', async () => {
             await expectLogic(logic, () => {
                 logic.actions.releaseTemplate()
@@ -745,9 +769,11 @@ describe('messageTemplateLogic', () => {
             'turns read-only when $refusal is refused and the reload $reload',
             async ({ refuse: refusal, status, edits }) => {
                 reloadStatus = status
+                const captureException = jest.spyOn(posthog, 'captureException').mockImplementation(() => undefined)
                 await refuse(refusal)
 
                 expect(mockToast.error).not.toHaveBeenCalledWith(expect.stringContaining('managed by code'))
+                expect(captureException).not.toHaveBeenCalledWith(expect.objectContaining({ code: 'immutable' }))
                 await expectLogic(logic).toMatchValues({
                     isCodeManaged: true,
                     hasDraft: false,

From 79554a83ac7a649e55a78fa52aec5058e341ec3b Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:49:00 +0000
Subject: [PATCH 25/42] fix(messaging): answer a refused named sender as
 invalid_request like every send refusal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../backend/presentation/views/message_templates.py  | 12 +++---------
 .../backend/tests/api/test_transactional_email.py    | 12 ++++++++++--
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 464a910ac0fe..3336ea94458f 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -708,7 +708,7 @@ class TemplateKeyNotFound(exceptions.NotFound):
     default_code = "template_not_found"
 
 
-class TransactionalEmailRejected(exceptions.APIException):
+class TransactionalEmailRejected(exceptions.ValidationError):
     STATUS_BY_CODE = {
         "template_outdated": 409,
         "quota_limited": 429,
@@ -724,13 +724,7 @@ class TransactionalEmailRejected(exceptions.APIException):
 
     def __init__(self, error: TransactionalEmailError) -> None:
         self.status_code = self.STATUS_BY_CODE.get(error.code, status.HTTP_400_BAD_REQUEST)
-        super().__init__(detail=str(error), code=error.code)
-
-
-def _rejection(error: TransactionalEmailError) -> exceptions.APIException:
-    if error.attr:
-        return exceptions.ValidationError({error.attr: [str(error)]}, code=error.code)
-    return TransactionalEmailRejected(error)
+        super().__init__(detail={error.attr: [str(error)]} if error.attr else str(error), code=error.code)
 
 
 class TransactionalEmailUnavailable(exceptions.APIException):
@@ -939,7 +933,7 @@ def _queue_send(
             outcome["outcome"] = "replayed" if queued.replayed else "queued"
         except TransactionalEmailError as e:
             outcome.update({"outcome": "rejected", "error_code": e.code})
-            raise _rejection(e)
+            raise TransactionalEmailRejected(e)
         except DeliveryUnavailable:
             outcome["outcome"] = "unavailable"
             raise unavailable() from None
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 838ef9b68ce5..a9aec7e808fc 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -727,7 +727,11 @@ def test_refuses_a_code_send_from_an_unverified_domain(self, mock_post, _flag, c
         )
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
-        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", "from")
+        assert (response.json()["type"], response.json()["code"], response.json()["attr"]) == (
+            "invalid_request",
+            "sender_not_verified",
+            "from",
+        )
         assert not TransactionalEmailKey.objects.for_team(self.team.id).exists()
         assert capture.call_args.kwargs["properties"]["error_code"] == "sender_not_verified"
         mock_post.assert_not_called()
@@ -738,7 +742,11 @@ def test_a_code_send_without_from_names_no_field_when_the_project_has_no_sender(
         response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, self._code_send(), format="json")
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
-        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", None)
+        assert (response.json()["type"], response.json()["code"], response.json()["attr"]) == (
+            "invalid_request",
+            "sender_not_verified",
+            None,
+        )
         mock_post.assert_not_called()
 
     @parameterized.expand(

From e852cd991b06d9e194644a3778f1bc5f110e31e9 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 18:16:56 +0000
Subject: [PATCH 26/42] fix(messaging): name the paused key workflow an upload
 asks to resume

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 products/messaging/backend/services/template_uploads.py      | 4 ++--
 products/messaging/backend/tests/api/test_template_upload.py | 1 +
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/products/messaging/backend/services/template_uploads.py b/products/messaging/backend/services/template_uploads.py
index def8a524bf82..488b34f5bc6b 100644
--- a/products/messaging/backend/services/template_uploads.py
+++ b/products/messaging/backend/services/template_uploads.py
@@ -106,8 +106,8 @@ def _require_the_key_workflow_can_be_taken_over(
     require_workflow_editor(key_workflow.hog_flow_id)
     if code_sends_paused(team_id, key_workflow.hog_flow_id):
         raise TransactionalEmailPaused(
-            "Code sends under this key are paused, so an upload can't take them over. Resume them in Workflows, "
-            "then upload again."
+            f"Code sends under this key are paused, so an upload can't take them over. Resume their workflow "
+            f"`{key_workflow.hog_flow_id}`, then upload again."
         )
 
 
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index acf77f9cfb09..3b811ab284bc 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -352,6 +352,7 @@ def test_refuses_a_first_upload_under_a_key_whose_code_sends_are_paused(
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
         assert response.json()["code"] == "transactional_email_paused"
+        assert f"`{key_workflow_id}`" in response.json()["detail"]
         assert not MessageTemplate.objects.exists()
 
     def test_refuses_a_first_upload_under_a_key_whose_workflow_the_member_cannot_edit(

From 2e23381af3f76522a83e2c700394053981894459 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 18:17:04 +0000
Subject: [PATCH 27/42] chore(messaging): say why send refusals keep the
 invalid_request type

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/presentation/views/message_templates.py   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 3336ea94458f..c5b35ec8cae1 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -719,7 +719,7 @@ class TransactionalEmailRejected(exceptions.ValidationError):
         "recipient_suppressed": 422,
         "recipient_unreachable": 422,
     }
-    # The caller has to change the request. Without this the error handler reports a server error.
+    # The caller has to change the request. Without this the error handler types it `validation_error`.
     default_type = "invalid_request"
 
     def __init__(self, error: TransactionalEmailError) -> None:

From df501520ad15f79b97537a1577d3ff79c549a5e7 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 18:23:15 +0000
Subject: [PATCH 28/42] fix(messaging): repair a workflow whose recipient
 changed on re-upload

An upload compared only the email's content with the workflow's, so a
workflow edited to send elsewhere still reported "unchanged". It now
compares the workflow's whole email step with the one the upload writes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../backend/services/template_uploads.py      | 22 ++++++++++++++-----
 .../backend/services/transactional_email.py   |  6 ++---
 .../backend/tests/api/test_template_upload.py | 13 +++++++++--
 .../backend/facade/transactional_emails.py    |  4 ++--
 .../services/transactional_email_workflows.py | 10 +++++++--
 5 files changed, 40 insertions(+), 15 deletions(-)

diff --git a/products/messaging/backend/services/template_uploads.py b/products/messaging/backend/services/template_uploads.py
index 488b34f5bc6b..b2b0e72cef2f 100644
--- a/products/messaging/backend/services/template_uploads.py
+++ b/products/messaging/backend/services/template_uploads.py
@@ -19,8 +19,16 @@
 from products.messaging.backend.services.content_hash import email_content_hash, sent_hash_state
 from products.messaging.backend.services.message_templates import record_content_hash
 from products.messaging.backend.services.template_saves import WorkflowEditorCheck, save_locked_template
-from products.messaging.backend.services.transactional_email import is_transactional, known_key, make_transactional
-from products.workflows.backend.facade.transactional_emails import code_sends_paused, transactional_email_workflow_email
+from products.messaging.backend.services.transactional_email import (
+    is_transactional,
+    known_key,
+    make_transactional,
+    transactional_email_content,
+)
+from products.workflows.backend.facade.transactional_emails import (
+    code_sends_paused,
+    transactional_email_workflow_matches,
+)
 
 SOURCE_PARTS = ("repository", "path", "ref")
 
@@ -179,14 +187,16 @@ def _is_unchanged(template: MessageTemplate, upload: TemplateUpload) -> bool:
         and template.content_hash == uploaded_hash
         and template.managed_by == TemplateManagedBy.CODE
         and is_transactional(template)
-        and email_content_hash(_sent_email(template)) == uploaded_hash
+        and _workflow_sends_the_template(template)
     )
 
 
-def _sent_email(template: MessageTemplate) -> dict[str, Any]:
+def _workflow_sends_the_template(template: MessageTemplate) -> bool:
     if template.transactional_hog_flow_id is None:
-        return {}
-    return transactional_email_workflow_email(template.team_id, template.transactional_hog_flow_id)
+        return False
+    return transactional_email_workflow_matches(
+        template.team_id, template.transactional_hog_flow_id, transactional_email_content(template)
+    )
 
 
 def _is_superseded(template: MessageTemplate, upload: TemplateUpload) -> bool:
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index 29d22169a525..91b57a3ee1ab 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -221,7 +221,7 @@ def _template_sender(email: dict[str, Any]) -> dict[str, Any]:
     return sender if isinstance(sender, dict) else {}
 
 
-def _content(template: MessageTemplate) -> TransactionalEmailContent:
+def transactional_email_content(template: MessageTemplate) -> TransactionalEmailContent:
     email = template.content["email"]
     sender = _template_sender(email)
     return TransactionalEmailContent(
@@ -269,7 +269,7 @@ def make_transactional(
                 raise TemplateNotSendable(address_error)
             template.content = {**template.content, "email": {**email, "from": sender}}
             hog_flow_id = create_transactional_email_workflow(
-                team_id=team_id, user_id=user_id, content=_content(template)
+                team_id=team_id, user_id=user_id, content=transactional_email_content(template)
             )
         except TransactionalEmailSenderUnavailable as e:
             raise SenderUnavailable(
@@ -329,7 +329,7 @@ def sync_transactional_workflow(team_id: int, template_id: UUID, *, user_id: int
             team_id=team_id,
             user_id=user_id,
             hog_flow_id=hog_flow_id,
-            content=_content(template),
+            content=transactional_email_content(template),
         )
         # The save already told the workers to reload, but before the caller's transaction committed, so a
         # worker can cache the old version. This reload runs once the new version is visible.
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index 3b811ab284bc..3a422ce447d1 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -147,9 +147,11 @@ def test_an_identical_upload_is_unchanged_and_writes_no_workflow_version(
             edited.call_args.kwargs["updated_at"] == MessageTemplate.objects.get(id=first["id"]).updated_at.isoformat()
         )
 
-    def _edit_the_workflow_outside_the_template(self, hog_flow_id: str) -> None:
+    def _edit_the_workflow_outside_the_template(
+        self, hog_flow_id: str, field: str = "html", value: Any = "<p>Edited in the workflow</p>"
+    ) -> None:
         workflow = HogFlow.objects.get(team=self.team, id=hog_flow_id)
-        workflow.actions[1]["config"]["inputs"]["email"]["value"]["html"] = "<p>Edited in the workflow</p>"
+        workflow.actions[1]["config"]["inputs"]["email"]["value"][field] = value
         HogFlow.objects.filter(team=self.team, id=hog_flow_id).update(actions=workflow.actions)
 
     @parameterized.expand(
@@ -162,6 +164,12 @@ def _edit_the_workflow_outside_the_template(self, hog_flow_id: str) -> None:
                 "workflow_edited_outside_the_template",
                 lambda test, upload: test._edit_the_workflow_outside_the_template(upload["transactional_hog_flow_id"]),
             ),
+            (
+                "recipient_edited_outside_the_template",
+                lambda test, upload: test._edit_the_workflow_outside_the_template(
+                    upload["transactional_hog_flow_id"], "to", {"email": "someone@example.com", "name": ""}
+                ),
+            ),
         ]
     )
     def test_an_upload_repairs_what_no_longer_matches_the_uploaded_content(self, _post, _flag, _capture, _name, drift):
@@ -173,6 +181,7 @@ def test_an_upload_repairs_what_no_longer_matches_the_uploaded_content(self, _po
         assert (repaired["result"], repaired["content_hash"]) == ("updated", WELCOME_HASH)
         assert self._template(first["id"])["content_hash"] == WELCOME_HASH
         assert self._sent_email(first["transactional_hog_flow_id"])["html"] == WELCOME["html"]
+        assert self._sent_email(first["transactional_hog_flow_id"])["to"]["email"] == "{{ event.properties.to | raw }}"
 
     @patch("products.messaging.backend.services.transactional_email.reload_hog_flows_on_workers")
     def test_a_changed_upload_is_what_the_next_send_delivers(self, _reload, post: MagicMock, _flag, _capture):
diff --git a/products/workflows/backend/facade/transactional_emails.py b/products/workflows/backend/facade/transactional_emails.py
index 179db8560860..64fd654bb1d4 100644
--- a/products/workflows/backend/facade/transactional_emails.py
+++ b/products/workflows/backend/facade/transactional_emails.py
@@ -13,7 +13,7 @@
     create_code_email_workflow,
     create_transactional_email_workflow,
     resolve_transactional_email_sender,
-    transactional_email_workflow_email,
+    transactional_email_workflow_matches,
     update_transactional_email_workflow,
 )
 
@@ -28,6 +28,6 @@
     "create_code_email_workflow",
     "create_transactional_email_workflow",
     "resolve_transactional_email_sender",
-    "transactional_email_workflow_email",
+    "transactional_email_workflow_matches",
     "update_transactional_email_workflow",
 ]
diff --git a/products/workflows/backend/services/transactional_email_workflows.py b/products/workflows/backend/services/transactional_email_workflows.py
index c269e9071710..61614f38e7fa 100644
--- a/products/workflows/backend/services/transactional_email_workflows.py
+++ b/products/workflows/backend/services/transactional_email_workflows.py
@@ -59,12 +59,18 @@ def code_sends_paused(team_id: int, hog_flow_id: UUID) -> bool:
     return flow is not None and (flow.status != HogFlow.State.ACTIVE or flow.email_sending_paused_at is not None)
 
 
-def transactional_email_workflow_email(team_id: int, hog_flow_id: UUID) -> dict[str, Any]:
+def transactional_email_workflow_matches(team_id: int, hog_flow_id: UUID, content: TransactionalEmailContent) -> bool:
     actions = HogFlow.objects.filter(team_id=team_id, pk=hog_flow_id).values_list("actions", flat=True).first()
+    sent_email = _email_value(actions or [])
+    sender_id = content.from_integration_id or (sent_email.get("from") or {}).get("integrationId")
+    return bool(sent_email) and sent_email == _email_value(transactional_email_actions(content, sender_id))
+
+
+def _email_value(actions: list) -> dict[str, Any]:
     email_step = next(
         (
             action
-            for action in actions or []
+            for action in actions
             if isinstance(action, dict) and action.get("id") == TRANSACTIONAL_EMAIL_ACTION_ID
         ),
         {},

From 9e0c2eae70b487c36854e2b3e97761c8845d1546 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 22:38:09 +0000
Subject: [PATCH 29/42] fix(messaging): accept a workflow with no stored sender
 when checking its content

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../workflows/backend/services/transactional_email_workflows.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/products/workflows/backend/services/transactional_email_workflows.py b/products/workflows/backend/services/transactional_email_workflows.py
index 61614f38e7fa..88c05d6ca355 100644
--- a/products/workflows/backend/services/transactional_email_workflows.py
+++ b/products/workflows/backend/services/transactional_email_workflows.py
@@ -35,7 +35,7 @@ def _template_provenance(content: TransactionalEmailContent) -> dict[str, str]:
     return {"template_uuid": str(content.message_template_id)}
 
 
-def transactional_email_actions(content: TransactionalEmailContent, from_integration_id: int) -> list[dict]:
+def transactional_email_actions(content: TransactionalEmailContent, from_integration_id: int | None) -> list[dict]:
     return _actions(
         name=content.name,
         step_config={

From 6d6c5a2bdef4e9b3027252532b4d661ccbaf8c67 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 2 Nov 2026 00:05:35 +0000
Subject: [PATCH 30/42] fix(messaging): keep a send by template id on master's
 route while email from code is off

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../presentation/views/message_templates.py   | 26 +++++++++++++------
 .../tests/api/test_transactional_email.py     | 18 ++++++++++---
 2 files changed, 33 insertions(+), 11 deletions(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index cc1a7e9b71f8..01bc4c4517ab 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -772,16 +772,22 @@ def require_email_from_code(team: Any) -> None:
 
 
 def _require_flag(team: Any, flag: str) -> None:
-    if not posthoganalytics.feature_enabled(
-        flag,
-        str(team.uuid),
-        groups={"organization": str(team.organization_id)},
-        group_properties={"organization": {"id": str(team.organization_id)}},
-        send_feature_flag_events=False,
-    ):
+    if not _flag_enabled(team, flag):
         raise NotFound()
 
 
+def _flag_enabled(team: Any, flag: str) -> bool:
+    return bool(
+        posthoganalytics.feature_enabled(
+            flag,
+            str(team.uuid),
+            groups={"organization": str(team.organization_id)},
+            group_properties={"organization": {"id": str(team.organization_id)}},
+            send_feature_flag_events=False,
+        )
+    )
+
+
 class TemplateUploadBurstThrottle(TransactionalEmailBurstThrottle):
     scope = "transactional_email_upload_burst"
 
@@ -1591,9 +1597,13 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
                 raise NotFound()
             self.check_object_permissions(request, template)
         return self._queue_transactional_email(
-            request, template, route="send_email", options=_template_send_options(request.data, request.validated_data)
+            request, template, route="send_email", options=self._id_send_options(request)
         )
 
+    def _id_send_options(self, request: Any) -> TemplateSendOptions | None:
+        options = _template_send_options(request.data, request.validated_data)
+        return options if options and _flag_enabled(self.team, EMAIL_FROM_CODE_FLAG) else None
+
     def _send_template_by_key(self, request: Any) -> Response:
         with transactional_email_stage("feature_flag"):
             require_email_from_code(self.team)
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 8bff6eec0651..116d3bf21f08 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -35,6 +35,7 @@
 
 PASSWORD_RESET_HASH = "v1:973d41bbe3fdca5c52bb951cd4b5fd7159ae630b56c8f3997cbb31afd1ea76fd"
 SUPERSEDED_HASH = f"v1:{'1' * 64}"
+BOTH_EMAIL_FLAGS = {TRANSACTIONAL_EMAIL_API_FLAG, EMAIL_FROM_CODE_FLAG}
 
 
 def _stage_counts() -> dict[str, float]:
@@ -537,25 +538,36 @@ def test_refuses_on_a_send_by_template_id_what_its_template_sets(
 
     @parameterized.expand(
         [
-            ("by_default", {}, "transactional_email", None),
+            ("by_default", {}, BOTH_EMAIL_FLAGS, "transactional_email", None),
             (
                 "without_engagement_capture",
                 {"capture_engagement": False},
+                BOTH_EMAIL_FLAGS,
                 "transactional_email/send",
                 {"tracking": {"captureEngagement": False}},
             ),
+            (
+                "without_engagement_capture_while_the_code_flag_is_off",
+                {"capture_engagement": False},
+                {TRANSACTIONAL_EMAIL_API_FLAG},
+                "transactional_email",
+                None,
+            ),
         ]
     )
     def test_a_send_by_template_id_carries_its_engagement_capture(
-        self, mock_post, _flag, _capture, _name, fields, route, sent
+        self, mock_post, flag, _capture, _name, fields, enabled_flags, route, sent
     ):
         self._cdp_accepts(mock_post)
+        flag.side_effect = lambda key, *_args, **_kwargs: key in enabled_flags
 
         response = self._send(self._psak_client(["hog_flow:write"]), "send_email", {**self.body, **fields})
 
         assert response.status_code == status.HTTP_202_ACCEPTED, response.json()
         assert mock_post.call_args.args[0].endswith(f"/hog_flows/{self.hog_flow_id}/{route}")
-        assert mock_post.call_args.kwargs["json"].get("send") == sent
+        payload = mock_post.call_args.kwargs["json"]
+        assert payload.get("send") == sent
+        assert ("send" in payload) == (sent is not None)
 
     def _keyed(self) -> dict[str, Any]:
         MessageTemplate.objects.filter(id=self.template.id).update(

From 30b7e404cfaab85480202be25634592152831d71 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 2 Nov 2026 01:10:45 +0000
Subject: [PATCH 31/42] fix(messaging): refuse capture_engagement on a send by
 template id outside the email from code beta

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../presentation/views/message_templates.py   | 16 ++++++++----
 .../tests/api/test_transactional_email.py     | 25 +++++++++++++------
 .../frontend/generated/api.schemas.ts         |  2 +-
 .../messaging/frontend/generated/api.zod.ts   |  2 +-
 services/mcp/src/api/generated.ts             |  2 +-
 .../mcp/src/generated/email_templates/api.ts  |  2 +-
 .../tool-schemas/workflows-send-email.json    |  2 +-
 7 files changed, 34 insertions(+), 17 deletions(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 01bc4c4517ab..949923e0b0c1 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -599,7 +599,8 @@ class SendEmailSerializer(SendTransactionalEmailSerializer):
         required=False,
         help_text="Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are "
         "captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement "
-        "capture off captures nothing, whatever the send says.",
+        "capture off captures nothing, whatever the send says. A send by `template.id` takes it only in the beta "
+        "for sending email from code.",
     )
 
     def get_fields(self) -> dict[str, serializers.Field]:
@@ -1590,6 +1591,7 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
             return self._send_template_by_key(request)
         with transactional_email_stage("feature_flag"):
             self._require_transactional_email_flag()
+            self._refuse_engagement_capture_outside_the_beta(request.validated_data)
         with transactional_email_stage("template_lookup"):
             try:
                 template = get_template(self.team_id, request.validated_data["template"]["id"])
@@ -1597,12 +1599,12 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
                 raise NotFound()
             self.check_object_permissions(request, template)
         return self._queue_transactional_email(
-            request, template, route="send_email", options=self._id_send_options(request)
+            request, template, route="send_email", options=_template_send_options(request.data, request.validated_data)
         )
 
-    def _id_send_options(self, request: Any) -> TemplateSendOptions | None:
-        options = _template_send_options(request.data, request.validated_data)
-        return options if options and _flag_enabled(self.team, EMAIL_FROM_CODE_FLAG) else None
+    def _refuse_engagement_capture_outside_the_beta(self, data: Mapping[str, Any]) -> None:
+        if "capture_engagement" in data and not _flag_enabled(self.team, EMAIL_FROM_CODE_FLAG):
+            raise serializers.ValidationError({"capture_engagement": ENGAGEMENT_CAPTURE_OUTSIDE_THE_BETA})
 
     def _send_template_by_key(self, request: Any) -> Response:
         with transactional_email_stage("feature_flag"):
@@ -1690,6 +1692,10 @@ def _send_code_email(self, request: Any) -> Response:
     "again."
 )
 TEMPLATE_SEND_OPTION_FIELDS = ("from", "reply_to", "capture_engagement")
+ENGAGEMENT_CAPTURE_OUTSIDE_THE_BETA = (
+    "A send by `template.id` takes this field only in the beta for sending email from code. Remove it to send the "
+    "email."
+)
 
 
 def _template_send_options(sent: Any, data: Mapping[str, Any]) -> TemplateSendOptions | None:
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 116d3bf21f08..0cab31cfa55f 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -546,13 +546,7 @@ def test_refuses_on_a_send_by_template_id_what_its_template_sets(
                 "transactional_email/send",
                 {"tracking": {"captureEngagement": False}},
             ),
-            (
-                "without_engagement_capture_while_the_code_flag_is_off",
-                {"capture_engagement": False},
-                {TRANSACTIONAL_EMAIL_API_FLAG},
-                "transactional_email",
-                None,
-            ),
+            ("by_default_while_the_code_flag_is_off", {}, {TRANSACTIONAL_EMAIL_API_FLAG}, "transactional_email", None),
         ]
     )
     def test_a_send_by_template_id_carries_its_engagement_capture(
@@ -569,6 +563,23 @@ def test_a_send_by_template_id_carries_its_engagement_capture(
         assert payload.get("send") == sent
         assert ("send" in payload) == (sent is not None)
 
+    @parameterized.expand([("without_capture", False), ("with_capture", True)])
+    def test_refuses_engagement_capture_on_a_send_by_template_id_while_email_from_code_is_off(
+        self, mock_post, flag, _capture, _name, capture_engagement
+    ):
+        flag.side_effect = lambda key, *_args, **_kwargs: key == TRANSACTIONAL_EMAIL_API_FLAG
+
+        response = self._send(
+            self._psak_client(["hog_flow:write"]),
+            "send_email",
+            {**self.body, "capture_engagement": capture_engagement},
+        )
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        assert response.json()["attr"] == "capture_engagement"
+        assert "beta" in response.json()["detail"]
+        mock_post.assert_not_called()
+
     def _keyed(self) -> dict[str, Any]:
         MessageTemplate.objects.filter(id=self.template.id).update(
             key="password-reset",
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index df28b81701da..6a40c78421e8 100644
--- a/products/messaging/frontend/generated/api.schemas.ts
+++ b/products/messaging/frontend/generated/api.schemas.ts
@@ -110,7 +110,7 @@ export interface SendEmailApi {
      * @maxItems 10
      */
     reply_to?: string[]
-    /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. */
+    /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. A send by `template.id` takes it only in the beta for sending email from code. */
     capture_engagement?: boolean
     /** Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, a send with `template_key` goes out from the project's default sender, and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it. */
     from?: string
diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.ts
index c6e26dcd73f6..9387bfad17ce 100644
--- a/products/messaging/frontend/generated/api.zod.ts
+++ b/products/messaging/frontend/generated/api.zod.ts
@@ -102,7 +102,7 @@ export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({
         .boolean()
         .optional()
         .describe(
-            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.'
+            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. A send by `template.id` takes it only in the beta for sending email from code.'
         ),
     from: zod
         .string()
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 35ef36bfa878..e16bf9907746 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -111022,7 +111022,7 @@ export namespace Schemas {
          * @maxItems 10
          */
       reply_to?: string[];
-      /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. */
+      /** Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. A send by `template.id` takes it only in the beta for sending email from code. */
       capture_engagement?: boolean;
       /** Sender of the email, as `security@example.com` or `Example <security@example.com>`, on a verified domain of the project. Without it, a send with `template_key` goes out from the project's default sender, and a send by `template.key` from its template's sender. A send by `template.id` doesn't take it. */
       from?: string;
diff --git a/services/mcp/src/generated/email_templates/api.ts b/services/mcp/src/generated/email_templates/api.ts
index dc218d975565..39ae09741821 100644
--- a/services/mcp/src/generated/email_templates/api.ts
+++ b/services/mcp/src/generated/email_templates/api.ts
@@ -68,7 +68,7 @@ export const MessagingSendEmailCreateBody = () => zod.object({
         .boolean()
         .optional()
         .describe(
-            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.'
+            'Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. A send by `template.id` takes it only in the beta for sending email from code.'
         ),
     from: zod
         .string()
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
index 7a7d82ee614a..8e209c7c1722 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-send-email.json
@@ -2,7 +2,7 @@
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "properties": {
         "capture_engagement": {
-            "description": "Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says.",
+            "description": "Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email are captured as analytics events of the recipient. Defaults to true. A project whose admin turned engagement capture off captures nothing, whatever the send says. A send by `template.id` takes it only in the beta for sending email from code.",
             "type": "boolean"
         },
         "distinct_id": {

From 0f27c1648bd67a68eb758b44e876cfd74b4594a1 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 2 Nov 2026 01:28:44 +0000
Subject: [PATCH 32/42] fix(messaging): refuse capture_engagement only when the
 send sets it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../presentation/views/message_templates.py    |  6 +++---
 .../tests/api/test_transactional_email.py      | 18 ++++++++++++++++++
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 949923e0b0c1..fbd63f84ba8b 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -1591,7 +1591,7 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
             return self._send_template_by_key(request)
         with transactional_email_stage("feature_flag"):
             self._require_transactional_email_flag()
-            self._refuse_engagement_capture_outside_the_beta(request.validated_data)
+            self._refuse_engagement_capture_outside_the_beta(request.data)
         with transactional_email_stage("template_lookup"):
             try:
                 template = get_template(self.team_id, request.validated_data["template"]["id"])
@@ -1602,8 +1602,8 @@ def email(self, request: Any, *args: Any, **kwargs: Any) -> Response:
             request, template, route="send_email", options=_template_send_options(request.data, request.validated_data)
         )
 
-    def _refuse_engagement_capture_outside_the_beta(self, data: Mapping[str, Any]) -> None:
-        if "capture_engagement" in data and not _flag_enabled(self.team, EMAIL_FROM_CODE_FLAG):
+    def _refuse_engagement_capture_outside_the_beta(self, sent: Mapping[str, Any]) -> None:
+        if "capture_engagement" in sent and not _flag_enabled(self.team, EMAIL_FROM_CODE_FLAG):
             raise serializers.ValidationError({"capture_engagement": ENGAGEMENT_CAPTURE_OUTSIDE_THE_BETA})
 
     def _send_template_by_key(self, request: Any) -> Response:
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 0cab31cfa55f..c3a251a3b234 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -580,6 +580,24 @@ def test_refuses_engagement_capture_on_a_send_by_template_id_while_email_from_co
         assert "beta" in response.json()["detail"]
         mock_post.assert_not_called()
 
+    @parameterized.expand(
+        [("while_email_from_code_is_off", {TRANSACTIONAL_EMAIL_API_FLAG}), ("with_both_flags", BOTH_EMAIL_FLAGS)]
+    )
+    def test_a_form_encoded_send_by_template_id_without_engagement_capture_keeps_masters_route(
+        self, mock_post, flag, _capture, _name, enabled_flags
+    ):
+        self._cdp_accepts(mock_post)
+        flag.side_effect = lambda key, *_args, **_kwargs: key in enabled_flags
+        client = self._psak_client(["hog_flow:write"])
+
+        response = client.post(
+            self.send_email_url, {"to": "user@example.com", "template.id": str(self.template.id)}, format="multipart"
+        )
+
+        assert response.status_code == status.HTTP_202_ACCEPTED, response.json()
+        assert mock_post.call_args.args[0].endswith(f"/hog_flows/{self.hog_flow_id}/transactional_email")
+        assert "send" not in mock_post.call_args.kwargs["json"]
+
     def _keyed(self) -> dict[str, Any]:
         MessageTemplate.objects.filter(id=self.template.id).update(
             key="password-reset",

From d090f43294f2368e1e4677e886ce8628e3b8e0d4 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 2 Nov 2026 06:09:00 +0000
Subject: [PATCH 33/42] fix(messaging): refuse an if_code_managed upload to a
 template edited in posthog

An upload that sets if_code_managed now answers 409 template_edited_in_posthog
when its key names a template that code does not manage, and changes nothing.
The check runs first, before if_not_superseded, because the SDK sends both
flags and a superseded answer would hide that people edit the template in
PostHog. An upload without the flag still takes the template over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/facade/contracts.py     |  5 ++
 .../presentation/views/message_templates.py   | 24 +++++++-
 .../presentation/views/template_refusals.py   | 11 ++++
 .../backend/services/template_uploads.py      |  3 +
 .../backend/tests/api/test_template_upload.py | 58 +++++++++++++++++++
 .../frontend/generated/api.schemas.ts         |  2 +
 products/messaging/frontend/generated/api.ts  |  2 +-
 .../messaging/frontend/generated/api.zod.ts   |  9 ++-
 services/mcp/src/api/generated.ts             |  2 +
 .../mcp/src/generated/email_templates/api.ts  |  9 ++-
 .../src/tools/generated/email_templates.ts    |  3 +
 .../workflows-upload-email-template.json      |  5 ++
 12 files changed, 128 insertions(+), 5 deletions(-)

diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 625b908e1636..3c254d9a4066 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -247,6 +247,10 @@ class TemplateKeyRefused(TemplateWriteRefused):
     pass
 
 
+class TemplateEditedInPostHog(Exception):
+    code = "template_edited_in_posthog"
+
+
 @frozen
 class TemplateSource:
     repository: str | None
@@ -265,3 +269,4 @@ class TemplateUpload:
     design: dict[str, Any]
     source: TemplateSource | None
     if_not_superseded: bool
+    if_code_managed: bool
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 23fc6dc3454d..7b909237251f 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -49,6 +49,7 @@
 )
 from products.messaging.backend.facade.contracts import (
     TEMPLATE_KEY_MAX_LENGTH,
+    TemplateEditedInPostHog,
     TemplateManagedBy,
     TemplateManagedByCode,
     TemplateReleasedTo,
@@ -101,6 +102,7 @@
     TemplateRefusal,
     invalid_request,
     invalid_template_key,
+    template_edited_in_posthog,
 )
 from products.notifications.backend.facade.api import publish_resource_edited
 from products.workflows.backend.facade.api import WorkflowAccessDenied, WorkflowNotFound
@@ -962,6 +964,14 @@ class UploadTemplateSerializer(serializers.Serializer):
         "The check covers the last 100 different contents the template replaced. Content outside those 100 "
         "publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.",
     )
+    if_code_managed = serializers.BooleanField(
+        required=False,
+        default=False,
+        help_text="Set it so the upload only updates a template that code manages. When the key names a template "
+        "edited in PostHog, the upload changes nothing and answers `409` with `template_edited_in_posthog`. A new "
+        "key, or a template managed by code, uploads as usual. Leave it out to take over a template edited in "
+        "PostHog, so code manages it from then on.",
+    )
 
     def get_fields(self) -> dict[str, serializers.Field]:
         return with_field_named_source_that_drf_reserves(
@@ -1332,6 +1342,11 @@ def send(self, request: Any, *args: Any, **kwargs: Any) -> Response:
                 "default sender",
             ),
             404: OpenApiResponse(description="Sending email from code is not enabled for this project"),
+            409: OpenApiResponse(
+                response=TemplateErrorSerializer,
+                description="The upload set `if_code_managed` and the template is edited in PostHog, so nothing "
+                "changed",
+            ),
             429: OpenApiResponse(description="Rate limited"),
         },
         summary="Upload a template by key",
@@ -1340,8 +1355,9 @@ def send(self, request: Any, *args: Any, **kwargs: Any) -> Response:
             "repository. The first upload creates the template and makes it transactional with the project's "
             "default verified sender. A later upload publishes changed content at once, and answers `unchanged` "
             "when the content is the same. With `if_not_superseded`, an upload of content that is one of the last "
-            "100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps "
-            "the template's sender and never turns a paused template back on."
+            "100 different contents the template replaced changes nothing and answers `superseded`. With "
+            "`if_code_managed`, an upload to a template edited in PostHog changes nothing and answers `409`. An "
+            "upload keeps the template's sender and never turns a paused template back on."
         ),
         parameters=[TEMPLATE_KEY_PARAMETER],
     )
@@ -1366,6 +1382,9 @@ def upload(self, request: Request, key: str, *args: Any, **kwargs: Any) -> Respo
                 require_workflow_editor=self._require_workflow_editor,
                 require_workflow_create=self._require_workflow_create,
             )
+        except TemplateEditedInPostHog as e:
+            self._report_template_upload(request, {"result": "rejected", "error_code": e.code})
+            return Response(TemplateErrorSerializer(template_edited_in_posthog()).data, status=status.HTTP_409_CONFLICT)
         except TransactionalEmailError as e:
             self._report_template_upload(request, {"result": "rejected", "error_code": e.code})
             raise TransactionalEmailRejected(e) from None
@@ -1397,6 +1416,7 @@ def _template_upload(key: str, data: dict[str, Any]) -> TemplateUpload:
             if source
             else None,
             if_not_superseded=data["if_not_superseded"],
+            if_code_managed=data["if_code_managed"],
         )
 
     @staticmethod
diff --git a/products/messaging/backend/presentation/views/template_refusals.py b/products/messaging/backend/presentation/views/template_refusals.py
index 037a4d24905b..f791cdb643a5 100644
--- a/products/messaging/backend/presentation/views/template_refusals.py
+++ b/products/messaging/backend/presentation/views/template_refusals.py
@@ -81,3 +81,14 @@ def first_field_error(errors: Any, path: tuple[str, ...] = ()) -> FieldError:
     if isinstance(errors, list) and errors and not isinstance(errors[0], str):
         return first_field_error(errors[0], path)
     return FieldError(attr="__".join(path) or None, message=str(errors[0] if isinstance(errors, list) else errors))
+
+
+def template_edited_in_posthog() -> TemplateRefusal:
+    return TemplateRefusal(
+        code="template_edited_in_posthog",
+        detail="This template is edited in PostHog, not managed by code, so the upload changed nothing.",
+        attr="if_code_managed",
+        why="An upload with `if_code_managed` never replaces a template that people edit in PostHog.",
+        fix="To manage the template in code again, upload the file without `if_code_managed`. That replaces the "
+        "content edited in PostHog and sets `managed_by` to `code`.",
+    )
diff --git a/products/messaging/backend/services/template_uploads.py b/products/messaging/backend/services/template_uploads.py
index b2b0e72cef2f..6a1bbff58aac 100644
--- a/products/messaging/backend/services/template_uploads.py
+++ b/products/messaging/backend/services/template_uploads.py
@@ -8,6 +8,7 @@
 from products.messaging.backend.facade.contracts import (
     ContentHashState,
     SenderUnavailable,
+    TemplateEditedInPostHog,
     TemplateManagedBy,
     TemplateSource,
     TemplateUpload,
@@ -80,6 +81,8 @@ def _upload(
     require_workflow_create: WorkflowCreateCheck,
 ) -> Uploaded:
     template = locked_template_with_key(team_id, upload.key)
+    if upload.if_code_managed and template is not None and template.managed_by != TemplateManagedBy.CODE:
+        raise TemplateEditedInPostHog()
     if template is None or template.managed_by is None:
         _require_the_key_workflow_can_be_taken_over(team_id, upload.key, require_workflow_editor)
     if template is None:
diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index 8663957d3db9..1898fed21005 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -559,3 +559,61 @@ def test_an_upload_if_not_superseded_never_puts_replaced_content_back(
         assert uploaded["content_hash"] == template["content_hash"]
         assert (template["content"]["email"]["subject"], template["source_ref"]) == (expected_subject, expected_ref)
         assert self._workflow(newer["transactional_hog_flow_id"])["version"] == expected_version
+
+    def _template_that_is(self, state: str) -> str | None:
+        if state == "new":
+            return None
+        if state == "made_in_posthog":
+            return str(
+                MessageTemplate.objects.create(
+                    team=self.team,
+                    name="Welcome",
+                    key="welcome",
+                    type="email",
+                    content={"email": {"subject": "Hello", "html": "<p>Hello</p>"}},
+                ).id
+            )
+        uploaded = self._upload(WELCOME)
+        if state == "edited_in_posthog":
+            for patch_body in (
+                {"managed_by": "gui"},
+                {"content": {"email": {"subject": "Edited", "html": "<p>E</p>"}}},
+            ):
+                edited = self.client.patch(
+                    f"/api/projects/{self.team.id}/messaging_templates/{uploaded['id']}/", patch_body, format="json"
+                )
+                assert edited.status_code == status.HTTP_200_OK, edited.json()
+        return uploaded["id"]
+
+    @parameterized.expand(
+        [
+            ("made_in_posthog", "made_in_posthog", WELCOME, status.HTTP_409_CONFLICT, None),
+            ("edited_in_posthog_over_superseded_content", "edited_in_posthog", WELCOME, status.HTTP_409_CONFLICT, None),
+            ("managed_by_code", "managed_by_code", GREETING, status.HTTP_200_OK, "updated"),
+            ("new_key", "new", WELCOME, status.HTTP_201_CREATED, "created"),
+        ]
+    )
+    def test_an_upload_if_code_managed_refuses_a_template_edited_in_posthog(
+        self, _post, _flag, _capture, _name, state, body, expected_status, expected_result
+    ):
+        template_id = self._template_that_is(state)
+        templates_before = list(MessageTemplate.objects.values())
+        workflows_before = list(HogFlow.objects.values("id", "version", "actions"))
+
+        with patch("products.messaging.backend.presentation.views.message_templates.publish_resource_edited") as edited:
+            response = self.psak.put(
+                self.url, {**body, "if_code_managed": True, "if_not_superseded": True}, format="json"
+            )
+
+        assert response.status_code == expected_status, response.json()
+        if expected_result is not None:
+            assert response.json()["result"] == expected_result
+            assert response.json()["managed_by"] == "code"
+            assert template_id in (None, response.json()["id"])
+            return
+        refusal = response.json()
+        assert (refusal["code"], refusal["attr"]) == ("template_edited_in_posthog", "if_code_managed")
+        assert "if_code_managed" in refusal["fix"]
+        assert list(MessageTemplate.objects.values()) == templates_before
+        assert list(HogFlow.objects.values("id", "version", "actions")) == workflows_before
+        edited.assert_not_called()
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index 0c1e89d0de3a..803927030af4 100644
--- a/products/messaging/frontend/generated/api.schemas.ts
+++ b/products/messaging/frontend/generated/api.schemas.ts
@@ -1068,6 +1068,8 @@ export interface UploadTemplateApi {
     preheader?: string
     /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
     if_not_superseded?: boolean
+    /** Set it so the upload only updates a template that code manages. When the key names a template edited in PostHog, the upload changes nothing and answers `409` with `template_edited_in_posthog`. A new key, or a template managed by code, uploads as usual. Leave it out to take over a template edited in PostHog, so code manages it from then on. */
+    if_code_managed?: boolean
     /** Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored. */
     source?: TemplateSourceApi
 }
diff --git a/products/messaging/frontend/generated/api.ts b/products/messaging/frontend/generated/api.ts
index 041612f8d153..5f2908ccab25 100644
--- a/products/messaging/frontend/generated/api.ts
+++ b/products/messaging/frontend/generated/api.ts
@@ -985,7 +985,7 @@ export const getMessagingTemplatesByKeyUpdateUrl = (projectId: string, key: stri
 }
 
 /**
- * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps the template's sender and never turns a paused template back on.
+ * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. With `if_code_managed`, an upload to a template edited in PostHog changes nothing and answers `409`. An upload keeps the template's sender and never turns a paused template back on.
  * @summary Upload a template by key
  */
 export const messagingTemplatesByKeyUpdate = async (
diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.ts
index 5c33048abc20..29b9217ffb60 100644
--- a/products/messaging/frontend/generated/api.zod.ts
+++ b/products/messaging/frontend/generated/api.zod.ts
@@ -1417,12 +1417,13 @@ export const MessagingTemplatesSendCreateBody = /* @__PURE__ */ zod.object({
 })
 
 /**
- * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps the template's sender and never turns a paused template back on.
+ * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. With `if_code_managed`, an upload to a template edited in PostHog changes nothing and answers `409`. An upload keeps the template's sender and never turns a paused template back on.
  * @summary Upload a template by key
  */
 export const messagingTemplatesByKeyUpdateBodyNameMax = 400
 
 export const messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault = false
+export const messagingTemplatesByKeyUpdateBodyIfCodeManagedDefault = false
 export const messagingTemplatesByKeyUpdateBodySourceOneRepositoryMax = 400
 
 export const messagingTemplatesByKeyUpdateBodySourceOnePathMax = 400
@@ -1452,6 +1453,12 @@ export const MessagingTemplatesByKeyUpdateBody = /* @__PURE__ */ zod.object({
         .describe(
             'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
         ),
+    if_code_managed: zod
+        .boolean()
+        .default(messagingTemplatesByKeyUpdateBodyIfCodeManagedDefault)
+        .describe(
+            'Set it so the upload only updates a template that code manages. When the key names a template edited in PostHog, the upload changes nothing and answers `409` with `template_edited_in_posthog`. A new key, or a template managed by code, uploads as usual. Leave it out to take over a template edited in PostHog, so code manages it from then on.'
+        ),
     source: zod
         .object({
             repository: zod
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index e320318b6127..3af681c82ce6 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -123552,6 +123552,8 @@ export namespace Schemas {
       preheader?: string;
       /** Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content. */
       if_not_superseded?: boolean;
+      /** Set it so the upload only updates a template that code manages. When the key names a template edited in PostHog, the upload changes nothing and answers `409` with `template_edited_in_posthog`. A new key, or a template managed by code, uploads as usual. Leave it out to take over a template edited in PostHog, so code manages it from then on. */
+      if_code_managed?: boolean;
       /** Where the template file lives, so people in PostHog can find it. Leaving it out, or a part of it, keeps what is stored. */
       source?: TemplateSource;
     }
diff --git a/services/mcp/src/generated/email_templates/api.ts b/services/mcp/src/generated/email_templates/api.ts
index 0400c249c518..e6a82b440b46 100644
--- a/services/mcp/src/generated/email_templates/api.ts
+++ b/services/mcp/src/generated/email_templates/api.ts
@@ -499,7 +499,7 @@ export const MessagingTemplatesMakeTransactionalCreateBody = () => zod.object({
 })
 
 /**
- * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. An upload keeps the template's sender and never turns a paused template back on.
+ * Create or update the email template with this key from HTML, for templates kept as files in a repository. The first upload creates the template and makes it transactional with the project's default verified sender. A later upload publishes changed content at once, and answers `unchanged` when the content is the same. With `if_not_superseded`, an upload of content that is one of the last 100 different contents the template replaced changes nothing and answers `superseded`. With `if_code_managed`, an upload to a template edited in PostHog changes nothing and answers `409`. An upload keeps the template's sender and never turns a paused template back on.
  * @summary Upload a template by key
  */
 export const MessagingTemplatesByKeyUpdateParams = () => zod.object({
@@ -518,6 +518,7 @@ export const MessagingTemplatesByKeyUpdateParams = () => zod.object({
 export const messagingTemplatesByKeyUpdateBodyNameMax = 400
 
 export const messagingTemplatesByKeyUpdateBodyIfNotSupersededDefault = false
+export const messagingTemplatesByKeyUpdateBodyIfCodeManagedDefault = false
 export const messagingTemplatesByKeyUpdateBodySourceOneRepositoryMax = 400
 
 export const messagingTemplatesByKeyUpdateBodySourceOnePathMax = 400
@@ -547,6 +548,12 @@ export const MessagingTemplatesByKeyUpdateBody = () => zod.object({
         .describe(
             'Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.'
         ),
+    if_code_managed: zod
+        .boolean()
+        .default(messagingTemplatesByKeyUpdateBodyIfCodeManagedDefault)
+        .describe(
+            'Set it so the upload only updates a template that code manages. When the key names a template edited in PostHog, the upload changes nothing and answers `409` with `template_edited_in_posthog`. A new key, or a template managed by code, uploads as usual. Leave it out to take over a template edited in PostHog, so code manages it from then on.'
+        ),
     source: zod
         .object({
             repository: zod
diff --git a/services/mcp/src/tools/generated/email_templates.ts b/services/mcp/src/tools/generated/email_templates.ts
index c335fd0274d5..afb6ad4e10bb 100644
--- a/services/mcp/src/tools/generated/email_templates.ts
+++ b/services/mcp/src/tools/generated/email_templates.ts
@@ -349,6 +349,9 @@ const workflowsUploadEmailTemplate = (): ToolBase<
         if (params.if_not_superseded !== undefined) {
             body['if_not_superseded'] = params.if_not_superseded
         }
+        if (params.if_code_managed !== undefined) {
+            body['if_code_managed'] = params.if_code_managed
+        }
         if (params.source !== undefined) {
             body['source'] = params.source
         }
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
index 61be523f4553..ead417fb633c 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-upload-email-template.json
@@ -5,6 +5,11 @@
             "description": "Email body as HTML, stored as sent. Supports Liquid, such as `{{ variables.first_name }}`.",
             "type": "string"
         },
+        "if_code_managed": {
+            "default": false,
+            "description": "Set it so the upload only updates a template that code manages. When the key names a template edited in PostHog, the upload changes nothing and answers `409` with `template_edited_in_posthog`. A new key, or a template managed by code, uploads as usual. Leave it out to take over a template edited in PostHog, so code manages it from then on.",
+            "type": "boolean"
+        },
         "if_not_superseded": {
             "default": false,
             "description": "Set it on uploads a program makes on its own, such as a sync that may hold an older copy of the file. When newer content already replaced this content, the upload changes nothing and answers `superseded`. The check covers the last 100 different contents the template replaced. Content outside those 100 publishes. Leave it out to publish the content in any case, such as to roll back to earlier content.",

From 1899846e41b36456beb05fb49b163bffdfcc652c Mon Sep 17 00:00:00 2001
From: "tests-posthog[bot]"
 <250237707+tests-posthog[bot]@users.noreply.github.com>
Date: Mon, 2 Nov 2026 08:54:08 +0000
Subject: [PATCH 34/42] chore: update OpenAPI generated types

---
 products/workflows/mcp/email_templates.yaml | 69 ++++++++++-----------
 1 file changed, 34 insertions(+), 35 deletions(-)

diff --git a/products/workflows/mcp/email_templates.yaml b/products/workflows/mcp/email_templates.yaml
index f661ac770a36..7047eb7eb461 100644
--- a/products/workflows/mcp/email_templates.yaml
+++ b/products/workflows/mcp/email_templates.yaml
@@ -77,41 +77,6 @@ tools:
                 - content
                 - created_by
                 - draft_content
-    workflows-send-email:
-        operation: messaging_send_email_create
-        enabled: true
-        feature_flag: workflows-email-from-code
-        annotations:
-            readOnly: false
-            destructive: true
-            idempotent: false
-        exclude_params:
-            - template
-            - message_data
-            - identifiers
-        param_overrides:
-            template_key:
-                required: true
-            subject:
-                required: true
-            distinct_id:
-                description: >
-                    Distinct ID of the recipient's person. The send and its engagement events are recorded against that
-                    person. Defaults to the recipient's email address.
-        title: Send transactional email
-        description: >
-            Send one transactional email to one recipient with the content you pass, such as a receipt or an order
-            update. No template has to exist in PostHog first. Name the email with template_key (for
-            example welcome); sends under one key share a workflow, so their metrics and runs group together. Pass the
-            subject and the body as html, text or both, exactly as the recipient should see it: PostHog renders
-            nothing, so {{ }} goes out as typed. When the user points you at a local file, such as an HTML email in
-            their repository, read the file yourself and pass its content as html. This tool can't read files or
-            URLs. from must be an address on a domain the project verified; sender_not_verified means nothing was
-            sent. Each call sends an email, so never repeat a call that succeeded. A 503, a timeout or a connection
-            error means PostHog did not confirm the send, and the email may still go out: do not try again on your own,
-            tell the user. A 404 with code
-            not_found means sending email from code is not enabled for this project, or the project does not
-            exist: stop and tell the user.
     workflows-make-email-template-transactional:
         operation: messaging_templates_make_transactional_create
         enabled: true
@@ -170,6 +135,40 @@ tools:
                 - content
                 - created_by
                 - draft_content
+    workflows-send-email:
+        operation: messaging_send_email_create
+        enabled: true
+        annotations:
+            readOnly: false
+            destructive: true
+            idempotent: false
+        title: Send transactional email
+        description: >
+            Send one transactional email to one recipient with the content you pass, such as a receipt or an order
+            update. No template has to exist in PostHog first. Name the email with template_key (for example welcome);
+            sends under one key share a workflow, so their metrics and runs group together. Pass the subject and the
+            body as html, text or both, exactly as the recipient should see it: PostHog renders nothing, so {{ }} goes
+            out as typed. When the user points you at a local file, such as an HTML email in their repository, read the
+            file yourself and pass its content as html. This tool can't read files or URLs. from must be an address on a
+            domain the project verified; sender_not_verified means nothing was sent. Each call sends an email, so never
+            repeat a call that succeeded. A 503, a timeout or a connection error means PostHog did not confirm the send,
+            and the email may still go out: do not try again on your own, tell the user. A 404 with code not_found means
+            sending email from code is not enabled for this project, or the project does not exist: stop and tell the
+            user.
+        exclude_params:
+            - template
+            - message_data
+            - identifiers
+        param_overrides:
+            template_key:
+                required: true
+            subject:
+                required: true
+            distinct_id:
+                description: >
+                    Distinct ID of the recipient's person. The send and its engagement events are recorded against that
+                    person. Defaults to the recipient's email address.
+        feature_flag: workflows-email-from-code
     workflows-show-email-template:
         operation: messaging_templates_retrieve
         enabled: true

From 2071baa643da8cfb2b64096630f69f38836e1757 Mon Sep 17 00:00:00 2001
From: "tests-posthog[bot]"
 <250237707+tests-posthog[bot]@users.noreply.github.com>
Date: Mon, 2 Nov 2026 08:59:41 +0000
Subject: [PATCH 35/42] chore: update OpenAPI generated types

---
 .../src/tools/generated/email_templates.ts    | 108 +++++++++---------
 1 file changed, 54 insertions(+), 54 deletions(-)

diff --git a/services/mcp/src/tools/generated/email_templates.ts b/services/mcp/src/tools/generated/email_templates.ts
index 27ebcff33985..a521bb5ded4e 100644
--- a/services/mcp/src/tools/generated/email_templates.ts
+++ b/services/mcp/src/tools/generated/email_templates.ts
@@ -130,59 +130,6 @@ const workflowsListEmailTemplates = (): ToolBase<
     },
 })
 
-const WorkflowsSendEmailSchema = () => {
-    const MessagingSendEmailCreateBody = orvalSchemas.MessagingSendEmailCreateBody()
-    return MessagingSendEmailCreateBody.extend({
-        template_key: MessagingSendEmailCreateBody.shape['template_key'].nonoptional(),
-        subject: MessagingSendEmailCreateBody.shape['subject'].nonoptional(),
-        distinct_id: MessagingSendEmailCreateBody.shape['distinct_id'].describe(
-            "Distinct ID of the recipient's person. The send and its engagement events are recorded against that person. Defaults to the recipient's email address."
-        ),
-    })
-}
-
-const workflowsSendEmail = (): ToolBase<ReturnType<typeof WorkflowsSendEmailSchema>, unknown> => ({
-    name: 'workflows-send-email',
-    schema: WorkflowsSendEmailSchema(),
-    handler: async (context: Context, params: z.infer<ReturnType<typeof WorkflowsSendEmailSchema>>) => {
-        const projectId = await context.stateManager.getProjectId()
-        const body: Record<string, unknown> = {}
-        if (params.to !== undefined) {
-            body['to'] = params.to
-        }
-        if (params.template_key !== undefined) {
-            body['template_key'] = params.template_key
-        }
-        if (params.distinct_id !== undefined) {
-            body['distinct_id'] = params.distinct_id
-        }
-        if (params.subject !== undefined) {
-            body['subject'] = params.subject
-        }
-        if (params.html !== undefined) {
-            body['html'] = params.html
-        }
-        if (params.text !== undefined) {
-            body['text'] = params.text
-        }
-        if (params.reply_to !== undefined) {
-            body['reply_to'] = params.reply_to
-        }
-        if (params.capture_engagement !== undefined) {
-            body['capture_engagement'] = params.capture_engagement
-        }
-        if (params.from !== undefined) {
-            body['from'] = params.from
-        }
-        const result = await context.api.request<unknown>({
-            method: 'POST',
-            path: `/api/projects/${encodeURIComponent(String(projectId))}/messaging/send/email/`,
-            body,
-        })
-        return result
-    },
-})
-
 const WorkflowsMakeEmailTemplateTransactionalSchema = () => {
     const MessagingTemplatesMakeTransactionalCreateBody = orvalSchemas.MessagingTemplatesMakeTransactionalCreateBody()
     const MessagingTemplatesMakeTransactionalCreateParams =
@@ -287,6 +234,59 @@ const workflowsPatchEmailTemplate = (): ToolBase<
     },
 })
 
+const WorkflowsSendEmailSchema = () => {
+    const MessagingSendEmailCreateBody = orvalSchemas.MessagingSendEmailCreateBody()
+    return MessagingSendEmailCreateBody.extend({
+        template_key: MessagingSendEmailCreateBody.shape['template_key'].nonoptional(),
+        subject: MessagingSendEmailCreateBody.shape['subject'].nonoptional(),
+        distinct_id: MessagingSendEmailCreateBody.shape['distinct_id'].describe(
+            "Distinct ID of the recipient's person. The send and its engagement events are recorded against that person. Defaults to the recipient's email address."
+        ),
+    })
+}
+
+const workflowsSendEmail = (): ToolBase<ReturnType<typeof WorkflowsSendEmailSchema>, unknown> => ({
+    name: 'workflows-send-email',
+    schema: WorkflowsSendEmailSchema(),
+    handler: async (context: Context, params: z.infer<ReturnType<typeof WorkflowsSendEmailSchema>>) => {
+        const projectId = await context.stateManager.getProjectId()
+        const body: Record<string, unknown> = {}
+        if (params.to !== undefined) {
+            body['to'] = params.to
+        }
+        if (params.template_key !== undefined) {
+            body['template_key'] = params.template_key
+        }
+        if (params.distinct_id !== undefined) {
+            body['distinct_id'] = params.distinct_id
+        }
+        if (params.subject !== undefined) {
+            body['subject'] = params.subject
+        }
+        if (params.html !== undefined) {
+            body['html'] = params.html
+        }
+        if (params.text !== undefined) {
+            body['text'] = params.text
+        }
+        if (params.reply_to !== undefined) {
+            body['reply_to'] = params.reply_to
+        }
+        if (params.capture_engagement !== undefined) {
+            body['capture_engagement'] = params.capture_engagement
+        }
+        if (params.from !== undefined) {
+            body['from'] = params.from
+        }
+        const result = await context.api.request<unknown>({
+            method: 'POST',
+            path: `/api/projects/${encodeURIComponent(String(projectId))}/messaging/send/email/`,
+            body,
+        })
+        return result
+    },
+})
+
 const WorkflowsShowEmailTemplateSchema = () => {
     const MessagingTemplatesRetrieveParams = orvalSchemas.MessagingTemplatesRetrieveParams()
     return MessagingTemplatesRetrieveParams.omit({ project_id: true })
@@ -369,10 +369,10 @@ export const GENERATED_TOOLS: Record<string, () => ToolBase<ZodObjectAny>> = {
     'workflows-create-email-template': workflowsCreateEmailTemplate,
     'workflows-get-email-template': workflowsGetEmailTemplate,
     'workflows-list-email-templates': workflowsListEmailTemplates,
-    'workflows-send-email': workflowsSendEmail,
     'workflows-make-email-template-transactional-prepare': workflowsMakeEmailTemplateTransactionalPrepare,
     'workflows-make-email-template-transactional-execute': workflowsMakeEmailTemplateTransactionalExecute,
     'workflows-patch-email-template': workflowsPatchEmailTemplate,
+    'workflows-send-email': workflowsSendEmail,
     'workflows-show-email-template': workflowsShowEmailTemplate,
     'workflows-update-email-template': workflowsUpdateEmailTemplate,
 }

From b312421181cd6865be8142417e6740a27ee7f960 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 2 Nov 2026 09:11:06 +0000
Subject: [PATCH 36/42] fix(messaging): import HogFlow through the workflows
 facade in the upload tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 products/messaging/backend/tests/api/test_template_upload.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/products/messaging/backend/tests/api/test_template_upload.py b/products/messaging/backend/tests/api/test_template_upload.py
index 3a422ce447d1..f93d77617627 100644
--- a/products/messaging/backend/tests/api/test_template_upload.py
+++ b/products/messaging/backend/tests/api/test_template_upload.py
@@ -24,7 +24,7 @@
 )
 from products.messaging.backend.services import template_uploads
 from products.workflows.backend.facade.api import set_default_email_sender_if_unset
-from products.workflows.backend.models import HogFlow
+from products.workflows.backend.facade.models import HogFlow
 
 WELCOME: dict[str, Any] = {
     "name": "Welcome",

From 5cf748bd75395d38f35001b2ca6c08443827aabe Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 2 Nov 2026 10:07:57 +0000
Subject: [PATCH 37/42] chore(messaging): sync the MCP email template tools
 with scaffold-yaml

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 products/workflows/mcp/email_templates.yaml   | 47 +++++----
 .../src/tools/generated/email_templates.ts    | 96 +++++++++----------
 2 files changed, 71 insertions(+), 72 deletions(-)

diff --git a/products/workflows/mcp/email_templates.yaml b/products/workflows/mcp/email_templates.yaml
index 24feda76dfdd..062b6547f64e 100644
--- a/products/workflows/mcp/email_templates.yaml
+++ b/products/workflows/mcp/email_templates.yaml
@@ -190,30 +190,6 @@ tools:
                 - content.email.design
                 - created_by
                 - draft_content
-    workflows-upload-email-template:
-        operation: messaging_templates_by_key_update
-        enabled: true
-        feature_flag: workflows-email-from-code
-        annotations:
-            readOnly: false
-            destructive: false
-            idempotent: true
-        enrich_url: '{id}'
-        title: Upload email template by key
-        description: >
-            Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or
-            password-reset). Use this for templates that live in code; use workflows-create-email-template for
-            templates designed in PostHog. Send name, subject, html, and optionally text, preheader and source
-            (repository, path, ref of the file). Use {{ variables.* }} for every value the email needs; templates
-            can't read person properties. The first upload creates the template and makes it sendable over the
-            transactional email API with the project's default verified sender, so verify a sender first. Later uploads
-            publish changed content at once and answer unchanged when nothing changed. Uploading replaces edits made
-            in PostHog. Set if_not_superseded when an older copy of the file must not replace newer content: an
-            answer of superseded means newer content is already published and nothing changed. The check covers the
-            last 100 different contents the template replaced; content outside those 100 publishes. Leave it out to publish
-            this content even when newer content replaced it, such as to roll back. A 404 with code not_found means
-            sending email from code is not enabled for this project, or the project does not exist: stop and tell
-            the user.
     workflows-update-email-template:
         operation: messaging_templates_partial_update
         enabled: true
@@ -241,3 +217,26 @@ tools:
                 - content
                 - draft_content
                 - created_by
+    workflows-upload-email-template:
+        operation: messaging_templates_by_key_update
+        enabled: true
+        annotations:
+            readOnly: false
+            destructive: false
+            idempotent: true
+        enrich_url: '{id}'
+        title: Upload email template by key
+        description: >
+            Upload an email template kept as an HTML file in a repository, by a key you choose (such as welcome or
+            password-reset). Use this for templates that live in code; use workflows-create-email-template for templates
+            designed in PostHog. Send name, subject, html, and optionally text, preheader and source (repository, path,
+            ref of the file). Use {{ variables.* }} for every value the email needs; templates can't read person
+            properties. The first upload creates the template and makes it sendable over the transactional email API
+            with the project's default verified sender, so verify a sender first. Later uploads publish changed content
+            at once and answer unchanged when nothing changed. Uploading replaces edits made in PostHog. Set
+            if_not_superseded when an older copy of the file must not replace newer content: an answer of superseded
+            means newer content is already published and nothing changed. The check covers the last 100 different
+            contents the template replaced; content outside those 100 publishes. Leave it out to publish this content
+            even when newer content replaced it, such as to roll back. A 404 with code not_found means sending email
+            from code is not enabled for this project, or the project does not exist: stop and tell the user.
+        feature_flag: workflows-email-from-code
diff --git a/services/mcp/src/tools/generated/email_templates.ts b/services/mcp/src/tools/generated/email_templates.ts
index 046bfc434e41..f482b8189ecb 100644
--- a/services/mcp/src/tools/generated/email_templates.ts
+++ b/services/mcp/src/tools/generated/email_templates.ts
@@ -314,53 +314,6 @@ const workflowsShowEmailTemplate = (): ToolBase<
         },
     })
 
-const WorkflowsUploadEmailTemplateSchema = () => {
-    const MessagingTemplatesByKeyUpdateBody = orvalSchemas.MessagingTemplatesByKeyUpdateBody()
-    const MessagingTemplatesByKeyUpdateParams = orvalSchemas.MessagingTemplatesByKeyUpdateParams()
-    return MessagingTemplatesByKeyUpdateParams.omit({ project_id: true }).extend(
-        MessagingTemplatesByKeyUpdateBody.shape
-    )
-}
-
-const workflowsUploadEmailTemplate = (): ToolBase<
-    ReturnType<typeof WorkflowsUploadEmailTemplateSchema>,
-    WithPostHogUrl<Schemas.UploadTemplateResponse>
-> => ({
-    name: 'workflows-upload-email-template',
-    schema: WorkflowsUploadEmailTemplateSchema(),
-    handler: async (context: Context, params: z.infer<ReturnType<typeof WorkflowsUploadEmailTemplateSchema>>) => {
-        const projectId = await context.stateManager.getProjectId()
-        const body: Record<string, unknown> = {}
-        if (params.name !== undefined) {
-            body['name'] = params.name
-        }
-        if (params.subject !== undefined) {
-            body['subject'] = params.subject
-        }
-        if (params.html !== undefined) {
-            body['html'] = params.html
-        }
-        if (params.text !== undefined) {
-            body['text'] = params.text
-        }
-        if (params.preheader !== undefined) {
-            body['preheader'] = params.preheader
-        }
-        if (params.if_not_superseded !== undefined) {
-            body['if_not_superseded'] = params.if_not_superseded
-        }
-        if (params.source !== undefined) {
-            body['source'] = params.source
-        }
-        const result = await context.api.request<Schemas.UploadTemplateResponse>({
-            method: 'PUT',
-            path: `/api/projects/${encodeURIComponent(String(projectId))}/messaging_templates/by_key/${encodeURIComponent(String(params.key))}/`,
-            body,
-        })
-        return await withPostHogUrl(context, result, `/workflows/library/templates/${result.id}`)
-    },
-})
-
 const WorkflowsUpdateEmailTemplateSchema = () => {
     const MessagingTemplatesPartialUpdateBody = orvalSchemas.MessagingTemplatesPartialUpdateBody()
     const MessagingTemplatesPartialUpdateParams = orvalSchemas.MessagingTemplatesPartialUpdateParams()
@@ -412,6 +365,53 @@ const workflowsUpdateEmailTemplate = (): ToolBase<
     },
 })
 
+const WorkflowsUploadEmailTemplateSchema = () => {
+    const MessagingTemplatesByKeyUpdateBody = orvalSchemas.MessagingTemplatesByKeyUpdateBody()
+    const MessagingTemplatesByKeyUpdateParams = orvalSchemas.MessagingTemplatesByKeyUpdateParams()
+    return MessagingTemplatesByKeyUpdateParams.omit({ project_id: true }).extend(
+        MessagingTemplatesByKeyUpdateBody.shape
+    )
+}
+
+const workflowsUploadEmailTemplate = (): ToolBase<
+    ReturnType<typeof WorkflowsUploadEmailTemplateSchema>,
+    WithPostHogUrl<Schemas.UploadTemplateResponse>
+> => ({
+    name: 'workflows-upload-email-template',
+    schema: WorkflowsUploadEmailTemplateSchema(),
+    handler: async (context: Context, params: z.infer<ReturnType<typeof WorkflowsUploadEmailTemplateSchema>>) => {
+        const projectId = await context.stateManager.getProjectId()
+        const body: Record<string, unknown> = {}
+        if (params.name !== undefined) {
+            body['name'] = params.name
+        }
+        if (params.subject !== undefined) {
+            body['subject'] = params.subject
+        }
+        if (params.html !== undefined) {
+            body['html'] = params.html
+        }
+        if (params.text !== undefined) {
+            body['text'] = params.text
+        }
+        if (params.preheader !== undefined) {
+            body['preheader'] = params.preheader
+        }
+        if (params.if_not_superseded !== undefined) {
+            body['if_not_superseded'] = params.if_not_superseded
+        }
+        if (params.source !== undefined) {
+            body['source'] = params.source
+        }
+        const result = await context.api.request<Schemas.UploadTemplateResponse>({
+            method: 'PUT',
+            path: `/api/projects/${encodeURIComponent(String(projectId))}/messaging_templates/by_key/${encodeURIComponent(String(params.key))}/`,
+            body,
+        })
+        return await withPostHogUrl(context, result, `/workflows/library/templates/${result.id}`)
+    },
+})
+
 export const GENERATED_TOOLS: Record<string, () => ToolBase<ZodObjectAny>> = {
     'workflows-create-email-template': workflowsCreateEmailTemplate,
     'workflows-get-email-template': workflowsGetEmailTemplate,
@@ -421,6 +421,6 @@ export const GENERATED_TOOLS: Record<string, () => ToolBase<ZodObjectAny>> = {
     'workflows-patch-email-template': workflowsPatchEmailTemplate,
     'workflows-send-email': workflowsSendEmail,
     'workflows-show-email-template': workflowsShowEmailTemplate,
-    'workflows-upload-email-template': workflowsUploadEmailTemplate,
     'workflows-update-email-template': workflowsUpdateEmailTemplate,
+    'workflows-upload-email-template': workflowsUploadEmailTemplate,
 }

From 002a08f3681c01c0f1d2f06acfc4420b1bda4c5a Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Mon, 2 Nov 2026 10:13:32 +0000
Subject: [PATCH 38/42] fix(messaging): import HogFlow through the workflows
 facade in the adoption tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 products/messaging/backend/tests/api/test_template_adoption.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/products/messaging/backend/tests/api/test_template_adoption.py b/products/messaging/backend/tests/api/test_template_adoption.py
index 295b4160befd..c36a797bda68 100644
--- a/products/messaging/backend/tests/api/test_template_adoption.py
+++ b/products/messaging/backend/tests/api/test_template_adoption.py
@@ -14,7 +14,7 @@
 from products.access_control.backend.models.access_control import AccessControl
 from products.messaging.backend.models.message_template import MessageTemplate
 from products.messaging.backend.models.transactional_email_key import TransactionalEmailKey
-from products.workflows.backend.models import HogFlow
+from products.workflows.backend.facade.models import HogFlow
 
 DOCS_URL = "https://posthog.com/docs/workflows/transactional-email-api"
 

From f32ee011843d3f81dfcf316a60326ad6d8882fd3 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sat, 31 Oct 2026 12:04:23 +0000
Subject: [PATCH 39/42] feat(messaging): point a sender refusal at the from a
 send names

A code send that names a `from` on no verified domain now answers `sender_not_verified` with `attr: "from"`, so
an SDK can show which field to fix. A send without `from` whose project
has no verified default sender still names no field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 products/messaging/backend/facade/contracts.py        |  5 +++++
 .../backend/presentation/views/message_templates.py   |  8 +++++++-
 .../messaging/backend/services/transactional_email.py |  3 ++-
 .../backend/tests/api/test_transactional_email.py     | 11 ++++++++++-
 4 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index ca909adcb536..c17aaa23749e 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -38,6 +38,7 @@ class TransactionalEmailError(Exception):
     """A send the caller has to fix before retrying. `code` is stable for API clients."""
 
     code = "invalid"
+    attr: str | None = None
 
 
 class TemplateNotSendable(TransactionalEmailError):
@@ -102,6 +103,10 @@ class SenderNotVerified(TransactionalEmailError):
     code = "sender_not_verified"
 
 
+class NamedSenderNotVerified(SenderNotVerified):
+    attr = "from"
+
+
 @frozen
 class CodeEmail:
     key: str
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 987f381fe658..1b488be60a89 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -581,6 +581,12 @@ def __init__(self, error: TransactionalEmailError) -> None:
         super().__init__(detail=str(error), code=error.code)
 
 
+def _rejection(error: TransactionalEmailError) -> exceptions.APIException:
+    if error.attr:
+        return exceptions.ValidationError({error.attr: [str(error)]}, code=error.code)
+    return TransactionalEmailRejected(error)
+
+
 class TransactionalEmailUnavailable(exceptions.APIException):
     status_code = status.HTTP_503_SERVICE_UNAVAILABLE
     default_detail = "The email pipeline is unavailable. Try again shortly."
@@ -756,7 +762,7 @@ def _queue_send(
             outcome["outcome"] = "replayed" if queued.replayed else "queued"
         except TransactionalEmailError as e:
             outcome.update({"outcome": "rejected", "error_code": e.code})
-            raise TransactionalEmailRejected(e)
+            raise _rejection(e)
         except DeliveryUnavailable:
             outcome["outcome"] = "unavailable"
             raise unavailable() from None
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index 4599b018a768..b20fe5ff334f 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -31,6 +31,7 @@
     InvalidIdempotencyKey,
     InvalidRecipient,
     MarketingTemplate,
+    NamedSenderNotVerified,
     QueuedEmail,
     QuotaLimited,
     RecipientSuppressed,
@@ -511,7 +512,7 @@ def _code_send_sender(team_id: int, address: str | None) -> dict[str, Any]:
         sender = code_send_sender(team_id=team_id, email=email or None, name=name or None)
     except TransactionalEmailSenderUnavailable as e:
         if address:
-            raise SenderNotVerified(f"No verified sender in this project can send from `{email}`.") from e
+            raise NamedSenderNotVerified(f"No verified sender in this project can send from `{email}`.") from e
         raise SenderNotVerified("The project has no verified default email sender.") from e
     return {"integrationId": sender.integration_id, "email": sender.email, "name": sender.name}
 
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index af4efa48b273..947aaf7b1916 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -531,11 +531,20 @@ def test_refuses_a_code_send_from_an_unverified_domain(self, mock_post, _flag, c
         )
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
-        assert response.json()["code"] == "sender_not_verified"
+        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", "from")
         assert not TransactionalEmailKey.objects.for_team(self.team.id).exists()
         assert capture.call_args.kwargs["properties"]["error_code"] == "sender_not_verified"
         mock_post.assert_not_called()
 
+    def test_a_code_send_without_from_names_no_field_when_the_project_has_no_sender(self, mock_post, _flag, _capture):
+        TeamWorkflowsConfig.objects.filter(team_id=self.team.id).update(default_email_integration_id=None)
+
+        response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, self._code_send(), format="json")
+
+        assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", None)
+        mock_post.assert_not_called()
+
     def test_a_code_send_the_pipeline_does_not_confirm_warns_it_may_still_go_out(self, mock_post, _flag, _capture):
         mock_post.side_effect = requests.ReadTimeout()
 

From bd945e0bc887c458bcb23ab66298f5ea2cecc898 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 17:49:00 +0000
Subject: [PATCH 40/42] fix(messaging): answer a refused named sender as
 invalid_request like every send refusal

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../backend/presentation/views/message_templates.py  | 12 +++---------
 .../backend/tests/api/test_transactional_email.py    | 12 ++++++++++--
 2 files changed, 13 insertions(+), 11 deletions(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 1b488be60a89..496fa3d2d5db 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -563,7 +563,7 @@ class SendTransactionalEmailResponseSerializer(serializers.Serializer):
     )
 
 
-class TransactionalEmailRejected(exceptions.APIException):
+class TransactionalEmailRejected(exceptions.ValidationError):
     STATUS_BY_CODE = {
         "quota_limited": 429,
         "idempotency_key_in_flight": 409,
@@ -578,13 +578,7 @@ class TransactionalEmailRejected(exceptions.APIException):
 
     def __init__(self, error: TransactionalEmailError) -> None:
         self.status_code = self.STATUS_BY_CODE.get(error.code, status.HTTP_400_BAD_REQUEST)
-        super().__init__(detail=str(error), code=error.code)
-
-
-def _rejection(error: TransactionalEmailError) -> exceptions.APIException:
-    if error.attr:
-        return exceptions.ValidationError({error.attr: [str(error)]}, code=error.code)
-    return TransactionalEmailRejected(error)
+        super().__init__(detail={error.attr: [str(error)]} if error.attr else str(error), code=error.code)
 
 
 class TransactionalEmailUnavailable(exceptions.APIException):
@@ -762,7 +756,7 @@ def _queue_send(
             outcome["outcome"] = "replayed" if queued.replayed else "queued"
         except TransactionalEmailError as e:
             outcome.update({"outcome": "rejected", "error_code": e.code})
-            raise _rejection(e)
+            raise TransactionalEmailRejected(e)
         except DeliveryUnavailable:
             outcome["outcome"] = "unavailable"
             raise unavailable() from None
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index 947aaf7b1916..0318391bb8f2 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -531,7 +531,11 @@ def test_refuses_a_code_send_from_an_unverified_domain(self, mock_post, _flag, c
         )
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
-        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", "from")
+        assert (response.json()["type"], response.json()["code"], response.json()["attr"]) == (
+            "invalid_request",
+            "sender_not_verified",
+            "from",
+        )
         assert not TransactionalEmailKey.objects.for_team(self.team.id).exists()
         assert capture.call_args.kwargs["properties"]["error_code"] == "sender_not_verified"
         mock_post.assert_not_called()
@@ -542,7 +546,11 @@ def test_a_code_send_without_from_names_no_field_when_the_project_has_no_sender(
         response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, self._code_send(), format="json")
 
         assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
-        assert (response.json()["code"], response.json()["attr"]) == ("sender_not_verified", None)
+        assert (response.json()["type"], response.json()["code"], response.json()["attr"]) == (
+            "invalid_request",
+            "sender_not_verified",
+            None,
+        )
         mock_post.assert_not_called()
 
     def test_a_code_send_the_pipeline_does_not_confirm_warns_it_may_still_go_out(self, mock_post, _flag, _capture):

From aea01712db06aaca7046c5833d67367e703fd3b6 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Sun, 1 Nov 2026 18:17:04 +0000
Subject: [PATCH 41/42] chore(messaging): say why send refusals keep the
 invalid_request type

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../messaging/backend/presentation/views/message_templates.py   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 496fa3d2d5db..c66b27febef0 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -573,7 +573,7 @@ class TransactionalEmailRejected(exceptions.ValidationError):
         "recipient_suppressed": 422,
         "recipient_unreachable": 422,
     }
-    # The caller has to change the request. Without this the error handler reports a server error.
+    # The caller has to change the request. Without this the error handler types it `validation_error`.
     default_type = "invalid_request"
 
     def __init__(self, error: TransactionalEmailError) -> None:

From 60062148d6478c39d74a427125a995817e5339e3 Mon Sep 17 00:00:00 2001
From: "Reichenbach, Michael" <755327+Silthus@users.noreply.github.com>
Date: Wed, 4 Nov 2026 11:35:15 +0000
Subject: [PATCH 42/42] chore(messaging): start CI on the base merge

GitHub sent no pull_request event for 5b3f20d, so no CI ran on it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>