Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(messaging): send an email with inline html from code (#127123)

Michael Reichenbach01d46bc77a0e
diff --git a/.semgrep/rules/security/idor-team-scoped-models.yaml b/.semgrep/rules/security/idor-team-scoped-models.yaml
index 51243651aeee..75a02142a40b 100644
--- a/.semgrep/rules/security/idor-team-scoped-models.yaml
+++ b/.semgrep/rules/security/idor-team-scoped-models.yaml
@@ -488,6 +488,7 @@ rules:
|TraceReviewScore
|TracesRetentionRule
|TracingView
+ |TransactionalEmailKey
|UploadedMedia
|UptimeMonitor
|UserInterview
@@ -986,6 +987,7 @@ rules:
|TraceReviewScore
|TracesRetentionRule
|TracingView
+ |TransactionalEmailKey
|UploadedMedia
|UptimeMonitor
|UserInterview
@@ -1316,6 +1318,7 @@ rules:
|TraceReview
|TraceReviewScore
|TracesRetentionRule
+ |TransactionalEmailKey
|User
|UserGroup
|UserInterview
diff --git a/posthog/plugins/plugin_server_api.py b/posthog/plugins/plugin_server_api.py
index 071ff89c4d5f..6849a84ed8b9 100644
--- a/posthog/plugins/plugin_server_api.py
+++ b/posthog/plugins/plugin_server_api.py
@@ -264,12 +264,14 @@ WORKFLOWS_RESUME_BATCH_JWT_PURPOSE = ScopedServiceJwtPurpose(
)
-def _mint_transactional_email_jwt(team_id: int, hog_flow_id: str) -> str:
+def _mint_transactional_email_jwt(team_id: int, hog_flow_id: str, **route_claims: str) -> str:
"""Short-lived scoped JWT for one transactional email send, pinned to the team and the transactional email's
workflow so a leaked token can only send that email. Verified in the plugin server's CdpApi."""
if not WORKFLOWS_TRANSACTIONAL_EMAIL_JWT_PURPOSE.enabled():
raise RuntimeError("WORKFLOWS_TRANSACTIONAL_EMAIL_JWT_SECRET is not configured — cannot send email")
- return WORKFLOWS_TRANSACTIONAL_EMAIL_JWT_PURPOSE.mint({"team_id": team_id, "hog_flow_id": hog_flow_id})
+ return WORKFLOWS_TRANSACTIONAL_EMAIL_JWT_PURPOSE.mint(
+ {"team_id": team_id, "hog_flow_id": hog_flow_id, **route_claims}
+ )
def send_transactional_email(
@@ -285,6 +287,20 @@ def send_transactional_email(
)
+def send_accepted_transactional_email(
+ team_id: int, hog_flow_id: str, payload: dict, *, timeout: float = 10
+) -> requests.Response:
+ return internal_requests.post(
+ CDP_API_URL + f"/api/projects/{team_id}/hog_flows/{hog_flow_id}/transactional_email/send",
+ data=json.dumps(payload, ensure_ascii=False).encode(),
+ headers={
+ "Content-Type": "application/json",
+ "Authorization": f"Bearer {_mint_transactional_email_jwt(team_id, hog_flow_id, kind='code_send')}",
+ },
+ timeout=timeout,
+ )
+
+
def resume_hog_flow_batch_job(team_id: int, hog_flow_id: str, batch_job_id: str) -> requests.Response:
"""Wake a batch run's resolver, parked until its realtime cohort finished calculating. The JSON
`outcome` is `resumed` or `already_resumed` on success; a 409 means the resolver isn't parked."""
diff --git a/posthog/plugins/test/test_plugin_server_api.py b/posthog/plugins/test/test_plugin_server_api.py
index a822994905df..3e5650d6efb7 100644
--- a/posthog/plugins/test/test_plugin_server_api.py
+++ b/posthog/plugins/test/test_plugin_server_api.py
@@ -1,10 +1,17 @@
+import json
+
from unittest.mock import patch
-from django.test import SimpleTestCase
+from django.test import SimpleTestCase, override_settings
from parameterized import parameterized
-from posthog.plugins.plugin_server_api import validate_messaging_preferences_token
+from posthog.plugins.plugin_server_api import (
+ WORKFLOWS_TRANSACTIONAL_EMAIL_JWT_PURPOSE,
+ send_accepted_transactional_email,
+ send_transactional_email,
+ validate_messaging_preferences_token,
+)
VALID_TOKEN = "eyJhbGciOiJIUzI1NiJ9.eyJ0ZWFtX2lkIjoxLCJpZGVudGlmaWVyIjoiYUBiLmNvbSJ9.c2ln"
@@ -35,3 +42,34 @@ class TestValidateMessagingPreferencesToken(SimpleTestCase):
mock_internal_requests.get.assert_called_once()
called_url = mock_internal_requests.get.call_args.args[0]
self.assertTrue(called_url.endswith(f"/api/messaging/validate_preferences_token/{VALID_TOKEN}"))
+
+
+@override_settings(WORKFLOWS_TRANSACTIONAL_EMAIL_JWT_SECRETS=["test-transactional-email-key"])
+class TestTransactionalEmailTokens(SimpleTestCase):
+ @parameterized.expand(
+ [
+ ("template_send", send_transactional_email, "/transactional_email", None),
+ ("code_send", send_accepted_transactional_email, "/transactional_email/send", "code_send"),
+ ]
+ )
+ @patch("posthog.plugins.plugin_server_api.internal_requests")
+ def test_mints_a_token_only_its_own_route_accepts(self, _name, send, path, kind, mock_internal_requests):
+ send(7, "flow-1", {"to": "[email protected]"})
+
+ url, headers = (
+ mock_internal_requests.post.call_args.args[0],
+ mock_internal_requests.post.call_args.kwargs["headers"],
+ )
+ claims = WORKFLOWS_TRANSACTIONAL_EMAIL_JWT_PURPOSE.verify(headers["Authorization"].removeprefix("Bearer "))
+ self.assertTrue(url.endswith(f"/api/projects/7/hog_flows/flow-1{path}"))
+ self.assertEqual((claims["team_id"], claims["hog_flow_id"], claims.get("kind")), (7, "flow-1", kind))
+
+ @patch("posthog.plugins.plugin_server_api.internal_requests")
+ def test_a_code_send_posts_text_outside_ascii_as_utf8(self, mock_internal_requests):
+ payload = {"send": {"content": {"subject": "注文", "html": "<p>注文 🎉</p>"}}}
+
+ send_accepted_transactional_email(7, "flow-1", payload)
+
+ body = mock_internal_requests.post.call_args.kwargs["data"]
+ self.assertEqual(json.loads(body), payload)
+ self.assertIn("<p>注文 🎉</p>".encode(), body)
diff --git a/products/desktop/packages/api-client/src/generated.ts b/products/desktop/packages/api-client/src/generated.ts
index 1f8da1131518..c7304ac855e3 100644
--- a/products/desktop/packages/api-client/src/generated.ts
+++ b/products/desktop/packages/api-client/src/generated.ts
@@ -11554,11 +11554,13 @@ export namespace Schemas {
* * `loops` - Loops
* * `broadcasts` - Broadcasts
* * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys
*/
export type HogFlowOriginProductEnum =
| "loops"
| "broadcasts"
- | "transactional_emails";
+ | "transactional_emails"
+ | "transactional_email_keys";
export type HogFlowMasking = {
ttl?: (number | null) | undefined;
threshold?: (number | null) | undefined;
@@ -11998,6 +12000,7 @@ export namespace Schemas {
* * `loops` - Loops
* * `broadcasts` - Broadcasts
* * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys
*/
origin_product: HogFlowOriginProductEnum | NullEnum;
created_at: string;
diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.py
index 25c3a76cb5c5..6416bbfc6e3f 100644
--- a/products/messaging/backend/facade/contracts.py
+++ b/products/messaging/backend/facade/contracts.py
@@ -98,6 +98,37 @@ class RecipientUnreachable(TransactionalEmailError):
code = "recipient_unreachable"
+class SenderNotVerified(TransactionalEmailError):
+ code = "sender_not_verified"
+
+
+class SenderRequired(TransactionalEmailError):
+ code = "sender_required"
+
+
+class TooManyKeys(TransactionalEmailError):
+ code = "too_many_keys"
+
+
+class ContentTooLarge(TransactionalEmailError):
+ code = "content_too_large"
+
+
+class InvalidRequest(TransactionalEmailError):
+ code = "invalid_request"
+
+
+@frozen
+class CodeEmail:
+ key: str
+ subject: str
+ html: str
+ text: str
+ 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/transactional_email.py b/products/messaging/backend/facade/transactional_email.py
index dbff0513fde0..e6c9db537824 100644
--- a/products/messaging/backend/facade/transactional_email.py
+++ b/products/messaging/backend/facade/transactional_email.py
@@ -1,6 +1,7 @@
"""Transactional email: a template made sendable over the API, backed by a workflow that runs once per send."""
from products.messaging.backend.facade.contracts import (
+ CodeEmail,
DeliveryUnavailable,
EmailDeliveryStatus,
EmailStatus,
@@ -8,12 +9,16 @@ from products.messaging.backend.facade.contracts import (
TransactionalEmailError,
)
from products.messaging.backend.services.transactional_email import (
+ PIPELINE_ADDRESS_PATTERN,
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,
+ send_code_email,
send_transactional_email,
sender_address_error,
sync_transactional_workflow,
@@ -22,7 +27,10 @@ from products.messaging.backend.services.transactional_email import (
from products.messaging.backend.services.transactional_email_status import get_email_status
__all__ = [
+ "PIPELINE_ADDRESS_PATTERN",
"SENDER_ADDRESS_MAX_LENGTH",
+ "SENDER_ADDRESS_PATTERN",
+ "CodeEmail",
"DeliveryUnavailable",
"EmailDeliveryStatus",
"EmailStatus",
@@ -34,6 +42,8 @@ __all__ = [
"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",
diff --git a/products/messaging/backend/migrations/0013_messagetemplate_key.py b/products/messaging/backend/migrations/0013_messagetemplate_key.py
new file mode 100644
index 000000000000..b018ffb443e7
--- /dev/null
+++ b/products/messaging/backend/migrations/0013_messagetemplate_key.py
@@ -0,0 +1,20 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+ dependencies = [
+ ("messaging", "0012_email_hard_bounce"),
+ ]
+
+ operations = [
+ migrations.AddField(
+ model_name="messagetemplate",
+ name="key",
+ field=models.CharField(
+ blank=True,
+ help_text="Client-chosen identifier, unique within this environment among templates that are not deleted. Letters, numbers, hyphens (-) and underscores (_) only.",
+ max_length=400,
+ null=True,
+ ),
+ ),
+ ]
diff --git a/products/messaging/backend/migrations/0014_messagetemplate_unique_key_per_team.py b/products/messaging/backend/migrations/0014_messagetemplate_unique_key_per_team.py
new file mode 100644
index 000000000000..fbcaa9d33b25
--- /dev/null
+++ b/products/messaging/backend/migrations/0014_messagetemplate_unique_key_per_team.py
@@ -0,0 +1,35 @@
+from django.db import migrations, models
+
+from posthog.migration_helpers import CreateIndexConcurrently
+
+
+class Migration(migrations.Migration):
+ atomic = False
+
+ dependencies = [
+ ("messaging", "0013_messagetemplate_key"),
+ ]
+
+ operations = [
+ migrations.SeparateDatabaseAndState(
+ state_operations=[
+ migrations.AddConstraint(
+ model_name="messagetemplate",
+ constraint=models.UniqueConstraint(
+ fields=("team", "key"),
+ condition=models.Q(("deleted", False), ("key__isnull", False)),
+ name="unique_message_template_key_per_team",
+ ),
+ ),
+ ],
+ database_operations=[
+ CreateIndexConcurrently(
+ index_name="unique_message_template_key_per_team",
+ table_name="posthog_messagetemplate",
+ columns='("team_id", "key")',
+ unique=True,
+ where='WHERE (NOT "deleted" AND "key" IS NOT NULL)',
+ ),
+ ],
+ ),
+ ]
diff --git a/products/messaging/backend/migrations/0015_transactional_email_key.py b/products/messaging/backend/migrations/0015_transactional_email_key.py
new file mode 100644
index 000000000000..63ce68080543
--- /dev/null
+++ b/products/messaging/backend/migrations/0015_transactional_email_key.py
@@ -0,0 +1,48 @@
+import django.db.models.deletion
+from django.db import migrations, models
+
+import posthog.uuidt
+
+
+class Migration(migrations.Migration):
+ dependencies = [
+ ("messaging", "0014_messagetemplate_unique_key_per_team"),
+ ("posthog", "1401_drop_userproductlist_table"),
+ ]
+
+ operations = [
+ migrations.CreateModel(
+ name="TransactionalEmailKey",
+ fields=[
+ (
+ "id",
+ models.UUIDField(
+ default=posthog.uuidt.uuid7,
+ editable=False,
+ primary_key=True,
+ serialize=False,
+ ),
+ ),
+ ("key", models.CharField(max_length=400)),
+ ("hog_flow_id", models.UUIDField()),
+ ("created_at", models.DateTimeField(auto_now_add=True)),
+ (
+ "team",
+ models.ForeignKey(
+ db_constraint=False,
+ on_delete=django.db.models.deletion.CASCADE,
+ related_name="+",
+ to="posthog.team",
+ ),
+ ),
+ ],
+ options={
+ "constraints": [
+ models.UniqueConstraint(
+ fields=("team", "key"),
+ name="unique_transactional_email_key_per_team",
+ )
+ ],
+ },
+ ),
+ ]
diff --git a/products/messaging/backend/migrations/max_migration.txt b/products/messaging/backend/migrations/max_migration.txt
index 309226c3f69b..11b055dbd3c6 100644
--- a/products/messaging/backend/migrations/max_migration.txt
+++ b/products/messaging/backend/migrations/max_migration.txt
@@ -1 +1 @@
-0012_email_hard_bounce
+0015_transactional_email_key
diff --git a/products/messaging/backend/models/__init__.py b/products/messaging/backend/models/__init__.py
index d4c0d97749b6..4ba7c27de7fc 100644
--- a/products/messaging/backend/models/__init__.py
+++ b/products/messaging/backend/models/__init__.py
@@ -6,6 +6,7 @@ from .message_template import MessageTemplate
from .optout_sync_config import OptOutSyncConfig
from .provider_import_run import ProviderImportRun
from .supabase_auth_email_config import SupabaseAuthEmailConfig
+from .transactional_email_key import TransactionalEmailKey
__all__ = [
"ALL_MESSAGE_PREFERENCE_CATEGORY_ID",
@@ -20,4 +21,5 @@ __all__ = [
"ProviderImportRun",
"SupabaseAuthEmailConfig",
"SuppressionSource",
+ "TransactionalEmailKey",
]
diff --git a/products/messaging/backend/models/message_template.py b/products/messaging/backend/models/message_template.py
index dbfbb701529d..0670af8610d2 100644
--- a/products/messaging/backend/models/message_template.py
+++ b/products/messaging/backend/models/message_template.py
@@ -3,6 +3,8 @@ from django.db import models
from posthog.models.tagged_items_relation import Taggable
from posthog.models.utils import UUIDTModel
+KEY_CONSTRAINT = "unique_message_template_key_per_team"
+
# nosemgrep: no-new-uuidt-models -- an existing model, and its stored ids cannot change.
class MessageTemplate(Taggable, UUIDTModel):
@@ -28,9 +30,23 @@ class MessageTemplate(Taggable, UUIDTModel):
# For emails carrying codes or reset links: sends keep no rendered body or subject, and clicks keep only
# the link's origin.
sensitive = models.BooleanField(default=False, db_default=False)
+ key = models.CharField(
+ max_length=400,
+ null=True,
+ blank=True,
+ help_text="Client-chosen identifier, unique within this environment among templates that are not deleted. "
+ "Letters, numbers, hyphens (-) and underscores (_) only.",
+ )
class Meta:
db_table = "posthog_messagetemplate"
+ constraints = [
+ models.UniqueConstraint(
+ fields=["team", "key"],
+ condition=models.Q(key__isnull=False, deleted=False),
+ name=KEY_CONSTRAINT,
+ ),
+ ]
def __str__(self):
return self.name
diff --git a/products/messaging/backend/models/transactional_email_key.py b/products/messaging/backend/models/transactional_email_key.py
new file mode 100644
index 000000000000..ad35b11db698
--- /dev/null
+++ b/products/messaging/backend/models/transactional_email_key.py
@@ -0,0 +1,20 @@
+from django.db import models
+
+from posthog.models.scoping.manager import TeamScopedManager
+from posthog.models.utils import UUIDModel
+
+TRANSACTIONAL_EMAIL_KEY_CONSTRAINT = "unique_transactional_email_key_per_team"
+
+
+class TransactionalEmailKey(UUIDModel):
+ objects = TeamScopedManager()
+
+ team = models.ForeignKey("posthog.Team", on_delete=models.CASCADE, db_constraint=False, related_name="+")
+ key = models.CharField(max_length=400)
+ hog_flow_id = models.UUIDField()
+ created_at = models.DateTimeField(auto_now_add=True)
+
+ class Meta:
+ constraints = [
+ models.UniqueConstraint(fields=["team", "key"], name=TRANSACTIONAL_EMAIL_KEY_CONSTRAINT),
+ ]
diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.py
index 31264ec77797..ca0536b69874 100644
--- a/products/messaging/backend/presentation/views/message_templates.py
+++ b/products/messaging/backend/presentation/views/message_templates.py
@@ -1,10 +1,13 @@
import time
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
from contextlib import AbstractContextManager, nullcontext
from dataclasses import fields as dataclass_fields
+from email.utils import parseaddr
from types import SimpleNamespace
from typing import Any, cast
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.core.validators import validate_email
from django.db import transaction
import structlog
@@ -58,14 +61,20 @@ from products.messaging.backend.facade.templates import (
update_template,
)
from products.messaging.backend.facade.transactional_email import (
+ PIPELINE_ADDRESS_PATTERN,
SENDER_ADDRESS_MAX_LENGTH,
+ SENDER_ADDRESS_PATTERN,
+ CodeEmail,
DeliveryUnavailable,
+ 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,
@@ -74,6 +83,7 @@ from products.messaging.backend.facade.transactional_email import (
from products.messaging.backend.presentation.views.serializers import DesignOperationSerializer
from products.notifications.backend.facade.api import publish_resource_edited
from products.workflows.backend.facade.api import WorkflowAccessDenied, WorkflowNotFound
+from products.workflows.backend.facade.transactional_emails import EMAIL_FROM_CODE_FLAG
from products.workflows.backend.facade.workflows import get_workflow
logger = structlog.get_logger(__name__)
@@ -411,8 +421,16 @@ class TransactionalEmailIdentifiersSerializer(serializers.Serializer):
)
+def _validate_pipeline_address(address: str) -> None:
+ if not PIPELINE_ADDRESS_PATTERN.fullmatch(address):
+ raise serializers.ValidationError(
+ "Enter an address PostHog can send to, like [email protected]. Quoted names, IP addresses and "
+ "non-ASCII domains aren't supported."
+ )
+
+
class TransactionalEmailMessageSerializer(serializers.Serializer):
- to = serializers.EmailField(help_text="Email address of the recipient.")
+ to = serializers.EmailField(validators=[_validate_pipeline_address], help_text="Email address of the recipient.")
message_data = serializers.DictField(
child=serializers.JSONField(allow_null=True),
required=False,
@@ -428,13 +446,64 @@ class SendTransactionalEmailSerializer(TransactionalEmailMessageSerializer):
)
+CODE_SEND_FIELDS = ("template_key", "subject", "html", "text", "from", "reply_to", "capture_engagement")
+CODE_BODY_MAX_BYTES = 5 * 1024 * 1024
+
+
class SendEmailSerializer(TransactionalEmailMessageSerializer):
template_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. Send either "
+ "`template_id` or `template_key`.",
+ )
+ template_key = serializers.RegexField(
+ r"^[a-zA-Z0-9_-]+$",
+ max_length=400,
+ required=False,
+ help_text="Names an email whose content your code rendered, such as `order-shipped`, 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.",
)
distinct_id = serializers.CharField(
required=False, allow_null=True, allow_blank=True, max_length=400, help_text=DISTINCT_ID_HELP_TEXT
)
+ subject = serializers.CharField(
+ required=False, trim_whitespace=False, help_text="Subject of the email your code rendered."
+ )
+ html = serializers.CharField(
+ required=False,
+ allow_blank=True,
+ trim_whitespace=False,
+ help_text="HTML body of the email your code rendered, at most 5 MiB as UTF-8.",
+ )
+ text = serializers.CharField(
+ required=False,
+ allow_blank=True,
+ trim_whitespace=False,
+ help_text="Plain text body of the email your code rendered, at most 5 MiB as UTF-8. Without it, PostHog "
+ "derives the text from `html`.",
+ )
+ from_address = serializers.CharField(
+ required=False,
+ # parseaddr() is quadratic on group addresses, so the raw value is bounded before validate_from parses it.
+ max_length=1024,
+ help_text="Sender of the email your code rendered, as `[email protected]` or "
+ "`Example <[email protected]>`, on a verified domain of the project. Without it, the email goes out from "
+ "the project's default sender, or from its only verified sender when it has no default.",
+ )
+ reply_to = serializers.ListField(
+ child=serializers.EmailField(validators=[_validate_pipeline_address]),
+ required=False,
+ allow_empty=False,
+ max_length=10,
+ help_text="Addresses replies to the email your code rendered go to.",
+ )
+ 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.",
+ )
def to_internal_value(self, data: Any) -> Any:
# posthog-node 5.61.0 and posthog 7.81.0 send `template.id` and `identifiers.distinct_id`, so that shape
@@ -447,6 +516,67 @@ class SendEmailSerializer(TransactionalEmailMessageSerializer):
data = {**data, "distinct_id": identifiers.get("distinct_id")}
return super().to_internal_value(data)
+ def get_fields(self) -> dict[str, serializers.Field]:
+ fields = super().get_fields()
+ fields["from"] = fields.pop("from_address")
+ return fields
+
+ def validate_html(self, value: str) -> str:
+ return _within_body_limit(value, "The HTML body")
+
+ def validate_text(self, value: str) -> str:
+ return _within_body_limit(value, "The plain text body")
+
+ def validate_from(self, value: str) -> str:
+ try:
+ _name, address = parseaddr(value)
+ except RecursionError:
+ address = ""
+ if not _is_sender_address(address):
+ raise serializers.ValidationError("Enter an address, such as `Example <[email protected]>`.")
+ return value
+
+ def validate(self, data: dict[str, Any]) -> dict[str, Any]:
+ sent = set(self.initial_data) if isinstance(self.initial_data, Mapping) else set()
+ if ("template_id" in data) == ("template_key" in data):
+ raise serializers.ValidationError({"template_id": "Send either `template_id` or `template_key`."})
+ if "template_id" 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."})
+ return data
+ unknown = next((field for field in sorted(sent) if field not in self.fields), None)
+ if unknown is not None:
+ raise serializers.ValidationError(
+ {unknown: "PostHog doesn't take this field, so it doesn't send the email without it."}
+ )
+ if "message_data" in sent:
+ raise serializers.ValidationError(
+ {"message_data": "A send with `template_key` carries content your code rendered, not `message_data`."}
+ )
+ if not data.get("subject"):
+ raise serializers.ValidationError({"subject": "A send with `template_key` needs a subject."})
+ if not (data.get("html") or data.get("text")):
+ raise serializers.ValidationError({"html": "A send with `template_key` needs `html`, `text` or both."})
+ return data
+
+
+def _within_body_limit(value: str, body: str) -> str:
+ if len(value.encode()) > CODE_BODY_MAX_BYTES:
+ raise serializers.ValidationError(
+ f"{body} can be at most 5 MiB as UTF-8. Link to large images and files instead of embedding them."
+ )
+ return value
+
+
+def _is_sender_address(address: str) -> bool:
+ if len(address) > SENDER_ADDRESS_MAX_LENGTH or not SENDER_ADDRESS_PATTERN.match(address):
+ return False
+ try:
+ validate_email(address)
+ except DjangoValidationError:
+ return False
+ return True
+
class MakeTransactionalSerializer(serializers.Serializer):
from_integration_id = serializers.IntegerField(
@@ -491,6 +621,14 @@ class TransactionalEmailUnavailable(exceptions.APIException):
default_code = "delivery_unavailable"
+class UnconfirmedEmailSend(TransactionalEmailUnavailable):
+ default_detail = (
+ "The email pipeline did not confirm the send, so the email may still go out. To retry, send it again "
+ "within 24 hours with the same Idempotency-Key, so it goes out once. A retry without that key, or after "
+ "that time, may send it twice."
+ )
+
+
class TransactionalEmailBurstThrottle(PersonalOrProjectSecretApiKeyRateThrottle):
scope = "transactional_email_burst"
rate = "600/minute"
@@ -523,16 +661,35 @@ def transactional_email_authorized_by(request: Any, required_scope: str) -> str:
def require_transactional_email_api(team: Any) -> None:
- if not posthoganalytics.feature_enabled(
- TRANSACTIONAL_EMAIL_API_FLAG,
- str(team.uuid),
- groups={"organization": str(team.organization_id)},
- group_properties={"organization": {"id": str(team.organization_id)}},
- send_feature_flag_events=False,
- ):
+ _require_flag(team, TRANSACTIONAL_EMAIL_API_FLAG)
+
+
+def require_email_from_code(team: Any) -> None:
+ _require_flag(team, EMAIL_FROM_CODE_FLAG)
+
+
+def require_email_status_read(team: Any) -> None:
+ if not (_flag_enabled(team, TRANSACTIONAL_EMAIL_API_FLAG) or _flag_enabled(team, EMAIL_FROM_CODE_FLAG)):
raise NotFound()
+def _require_flag(team: Any, flag: str) -> None:
+ 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,
+ )
+ )
+
+
def transactional_email_throttles() -> list[BaseThrottle]:
# Both send routes share these scopes, so a caller can't double its rate by using both.
return [
@@ -546,8 +703,9 @@ def transactional_email_throttles() -> list[BaseThrottle]:
SEND_RESPONSES: dict[int, ResponseDeclaration] = {
202: OpenApiResponse(response=SendTransactionalEmailResponseSerializer, description="Email queued"),
400: OpenApiResponse(
- description="The template isn't transactional or its email is paused, the recipient can't be used, "
- "or the Idempotency-Key is invalid"
+ description="A field is invalid, the template isn't transactional or its email is paused, the sender isn't "
+ "verified, the recipient can't be used, the Idempotency-Key is invalid, the email is too large to send, or "
+ "the project has reached its limit of template keys and the `template_key` is new"
),
404: OpenApiResponse(description="Template not found"),
409: OpenApiResponse(description="A request with the same Idempotency-Key is still in progress"),
@@ -619,6 +777,29 @@ class TransactionalEmailSendMixin:
if template.transactional_hog_flow_id:
self._require_workflow_editor(template.transactional_hog_flow_id)
data = request.validated_data
+ return self._queue_send(
+ request,
+ lambda idempotency_key: send_transactional_email(
+ self.team,
+ template,
+ to=data["to"],
+ distinct_id=_distinct_id(data),
+ message_data=data["message_data"],
+ idempotency_key=idempotency_key,
+ ),
+ route=route,
+ addressed={"template_id": str(template.id)},
+ )
+
+ def _queue_send(
+ self,
+ request: Any,
+ send: Callable[[str | None], QueuedEmail],
+ *,
+ route: str,
+ addressed: dict[str, str],
+ unavailable: type[TransactionalEmailUnavailable] = TransactionalEmailUnavailable,
+ ) -> Response:
idempotency_key = request.headers.get("Idempotency-Key")
outcome: dict[str, Any] = {
"outcome": "error",
@@ -626,24 +807,17 @@ class TransactionalEmailSendMixin:
"route": route,
}
try:
- queued = send_transactional_email(
- self.team,
- template,
- to=data["to"],
- distinct_id=data.get("distinct_id") or (data.get("identifiers") or {}).get("distinct_id") or None,
- message_data=data["message_data"],
- idempotency_key=idempotency_key,
- )
+ queued = send(idempotency_key)
outcome["outcome"] = "replayed" if queued.replayed else "queued"
except TransactionalEmailError as e:
outcome.update({"outcome": "rejected", "error_code": e.code})
raise TransactionalEmailRejected(e)
except DeliveryUnavailable:
outcome["outcome"] = "unavailable"
- raise TransactionalEmailUnavailable() from None
+ raise unavailable() from None
finally:
with transactional_email_stage("usage_event"):
- self._report_transactional_email_send(request, template, outcome)
+ self._report_transactional_email_send(request, {**addressed, **outcome})
return Response(
SendTransactionalEmailResponseSerializer(queued).data,
status=status.HTTP_202_ACCEPTED,
@@ -669,22 +843,25 @@ class TransactionalEmailSendMixin:
except WorkflowNotFound:
return
- def _report_transactional_email_send(
- self, request: Any, template: MessageTemplateRow, outcome: dict[str, Any]
- ) -> None:
+ def _require_workflow_create(self) -> None:
+ if is_authenticated_via_project_secret_api_key(self.request):
+ return
+ if not self.user_access_control.check_access_level_for_resource("hog_flow", "editor"):
+ 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:
# 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",
properties={
- "template_id": str(template.id),
"team_id": self.team_id,
"auth_method": "project_secret_api_key"
if is_authenticated_via_project_secret_api_key(request)
else "user",
"authorized_by": transactional_email_authorized_by(request, TRANSACTIONAL_EMAIL_SEND_SCOPE),
- **outcome,
+ **properties,
},
groups=groups(self.organization, self.team),
)
@@ -1002,17 +1179,21 @@ class MessagingSendViewSet(TransactionalEmailSendMixin, TeamAndOrgViewSetMixin,
responses=SEND_RESPONSES,
summary="Send a transactional email",
description=(
- "Send one transactional email to one recipient from the template named in `template_id`. The template "
- "must be made transactional first. `message_data` fills the template's `{{ variables.* }}` placeholders. "
- "Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry "
- "safely without sending the email twice. Needs the `transactional_email:write` scope. A key with "
- "`hog_flow:write` also works, but that scope reaches the rest of Workflows too."
+ "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. Needs the "
+ "`transactional_email:write` scope. A key with `hog_flow:write` also works, but that scope reaches the "
+ "rest of Workflows too."
),
parameters=[IDEMPOTENCY_KEY_PARAMETER],
)
@action(detail=False, methods=["POST"], required_scopes=[TRANSACTIONAL_EMAIL_SEND_SCOPE])
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)
with transactional_email_stage("feature_flag"):
self._require_transactional_email_flag()
with transactional_email_stage("template_lookup"):
@@ -1022,3 +1203,42 @@ class MessagingSendViewSet(TransactionalEmailSendMixin, TeamAndOrgViewSetMixin,
raise NotFound()
self.check_object_permissions(request, template)
return self._queue_transactional_email(request, template, route="send_email")
+
+ def _send_code_email(self, request: Any) -> Response:
+ with transactional_email_stage("feature_flag"):
+ require_email_from_code(self.team)
+ data = request.validated_data
+ key = data["template_key"]
+ with transactional_email_stage("workflow_access"):
+ require_code_email_access(
+ self.team_id,
+ key,
+ require_workflow_editor=self._require_workflow_editor,
+ require_workflow_create=self._require_workflow_create,
+ )
+ email = CodeEmail(
+ key=key,
+ subject=data["subject"],
+ html=data.get("html", ""),
+ text=data.get("text", ""),
+ sender=data.get("from"),
+ reply_to=tuple(data.get("reply_to", ())),
+ capture_engagement=data.get("capture_engagement", True),
+ )
+ return self._queue_send(
+ request,
+ lambda idempotency_key: send_code_email(
+ self.team,
+ email,
+ to=data["to"],
+ distinct_id=_distinct_id(data),
+ idempotency_key=idempotency_key,
+ ),
+ route="send_email",
+ addressed={"addressed_by": "template_key"},
+ unavailable=UnconfirmedEmailSend,
+ )
+
+
+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/presentation/views/transactional_email_status.py b/products/messaging/backend/presentation/views/transactional_email_status.py
index 683b144ae879..f3deae2c53b5 100644
--- a/products/messaging/backend/presentation/views/transactional_email_status.py
+++ b/products/messaging/backend/presentation/views/transactional_email_status.py
@@ -21,7 +21,7 @@ from posthog.rate_limit import PersonalOrProjectSecretApiKeyRateThrottle, Projec
from products.messaging.backend.facade.transactional_email import EmailDeliveryStatus, EmailStatus, get_email_status
from products.messaging.backend.presentation.views.message_templates import (
TRANSACTIONAL_EMAIL_STATUS_SCOPE,
- require_transactional_email_api,
+ require_email_status_read,
transactional_email_authorized_by,
)
@@ -117,7 +117,7 @@ class MessagingEmailsViewSet(TeamAndOrgViewSetMixin, viewsets.ViewSet):
# server that sent the email, so only its project secret API key can read it.
if not is_authenticated_via_project_secret_api_key(request):
raise exceptions.NotAuthenticated()
- require_transactional_email_api(self.team)
+ require_email_status_read(self.team)
email_status = self._email_status(pk)
self._report_status_read(request, email_status)
if email_status is None:
diff --git a/products/messaging/backend/services/html_text.py b/products/messaging/backend/services/html_text.py
new file mode 100644
index 000000000000..43bad8dd7694
--- /dev/null
+++ b/products/messaging/backend/services/html_text.py
@@ -0,0 +1,157 @@
+import re
+from collections import Counter
+from html.parser import HTMLParser
+
+from posthog.dataclasses import frozen
+
+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"})
+VOID_TAGS = frozenset(
+ {
+ "area",
+ "base",
+ "basefont",
+ "bgsound",
+ "br",
+ "col",
+ "command",
+ "embed",
+ "frame",
+ "hr",
+ "image",
+ "img",
+ "input",
+ "isindex",
+ "keygen",
+ "link",
+ "menuitem",
+ "meta",
+ "nextid",
+ "param",
+ "source",
+ "spacer",
+ "track",
+ "wbr",
+ }
+)
+LINK_SCHEMES = ("http://", "https://", "mailto:")
+BLANK_LINES = re.compile(r"\n{3,}")
+WHITESPACE = re.compile(r"\s+")
+LINE_END = "\x00"
+LINE_ENDS = re.compile(r"\n?\x00+\n?")
+
+
+def text_from_html(html: str) -> str:
+ parser = _TextParser()
+ parser.feed(html.replace(LINE_END, ""))
+ parser.close()
+ text = LINE_ENDS.sub(_line_break, "".join(parser.parts))
+ lines = "\n".join(" ".join(line.split()) for line in text.split("\n"))
+ return BLANK_LINES.sub("\n\n", lines).strip()
+
+
+def _line_break(match: re.Match[str]) -> str:
+ return match.group(0).replace(LINE_END, "") or "\n"
+
+
+@frozen
+class _OpenLink:
+ depth: int
+ href: str
+ label_start: int
+
+
+class _TextParser(HTMLParser):
+ def __init__(self) -> None:
+ super().__init__(convert_charrefs=True)
+ self.parts: list[str] = []
+ self.open_tags: list[str] = []
+ self.open_counts: Counter[str] = Counter()
+ self.open_links: list[_OpenLink] = []
+ self.hidden_from: int | None = None
+ self.label_text: list[str] = []
+ self.label_length = 0
+
+ def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+ if tag in VOID_TAGS:
+ self.handle_startendtag(tag, attrs)
+ return
+ self._start(tag, attrs)
+ self._push(tag)
+
+ def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+ self._start(tag, attrs)
+ self._push(tag)
+ self._end_last()
+
+ def handle_endtag(self, tag: str) -> None:
+ if tag in VOID_TAGS or not self.open_counts[tag]:
+ return
+ while self.open_tags[-1] != tag:
+ self._end_last()
+ self._end_last()
+
+ def handle_data(self, data: str) -> None:
+ if self.hidden_from is not None:
+ return
+ self.parts.append(WHITESPACE.sub(" ", data))
+ if stripped := data.strip():
+ self.label_text.append(stripped)
+ self.label_length += len(stripped)
+
+ def close(self) -> None:
+ super().close()
+ while self.open_tags:
+ self._end_last()
+
+ def _start(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+ if self.hidden_from is not None:
+ return
+ if tag in HIDDEN_TAGS:
+ self.hidden_from = len(self.open_tags)
+ return
+ if tag == "br":
+ self.parts.append("\n")
+ elif tag in PARAGRAPH_TAGS:
+ self.parts.append("\n\n")
+ elif tag in LINE_TAGS:
+ self.parts.append("\n")
+ href = dict(attrs).get("href") if tag == "a" else None
+ if href is not None and href.startswith(LINK_SCHEMES):
+ self.open_links.append(_OpenLink(depth=len(self.open_tags), href=href, label_start=self.label_length))
+
+ def _push(self, tag: str) -> None:
+ self.open_tags.append(tag)
+ self.open_counts[tag] += 1
+
+ def _end_last(self) -> None:
+ tag = self.open_tags.pop()
+ self.open_counts[tag] -= 1
+ depth = len(self.open_tags)
+ if self.hidden_from is not None:
+ if depth == self.hidden_from:
+ self.hidden_from = None
+ return
+ if self.open_links and self.open_links[-1].depth == depth:
+ link = self.open_links.pop()
+ if not self._label_is(link):
+ self.parts.append(f" ({link.href})")
+ elif tag in ("td", "th"):
+ self.parts.append(" ")
+ if tag in PARAGRAPH_TAGS:
+ self.parts.append("\n\n")
+ elif tag in LINE_TAGS:
+ self.parts.append(LINE_END)
+
+ def _label_is(self, link: _OpenLink) -> bool:
+ if self.label_length - link.label_start != len(link.href):
+ return False
+ label: list[str] = []
+ length = 0
+ for text in reversed(self.label_text):
+ if length >= len(link.href):
+ break
+ label.append(text)
+ length += len(text)
+ return "".join(reversed(label))[length - len(link.href) :] == link.href
diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.py
index 7a5d57debf9e..f38f9c8abe78 100644
--- a/products/messaging/backend/services/transactional_email.py
+++ b/products/messaging/backend/services/transactional_email.py
@@ -3,12 +3,13 @@ per send, so sends get the workflow's metrics, run history and versions."""
import re
import time
-from collections.abc import Iterator
+from collections.abc import Callable, Iterator
from contextlib import contextmanager
+from email.utils import parseaddr
from typing import Any, Literal, Protocol
from uuid import UUID
-from django.db import transaction
+from django.db import connection, transaction
import requests
import structlog
@@ -16,34 +17,47 @@ from prometheus_client import Counter, Histogram
from posthog.integrations import IntegrationManager, IntegrationNotFound
from posthog.models.team import Team
-from posthog.plugins.plugin_server_api import send_transactional_email as run_transactional_workflow
+from posthog.plugins.plugin_server_api import (
+ send_accepted_transactional_email,
+ send_transactional_email as run_transactional_workflow,
+)
from products.messaging.backend.facade.contracts import (
+ CodeEmail,
+ ContentTooLarge,
DeliveryUnavailable,
IdempotencyKeyInFlight,
IdempotencyKeyReused,
InvalidIdempotencyKey,
InvalidRecipient,
+ InvalidRequest,
MarketingTemplate,
QueuedEmail,
QuotaLimited,
RecipientSuppressed,
RecipientUnreachable,
+ SenderNotVerified,
+ SenderRequired,
SenderUnavailable,
SendingPaused,
SendingSuspended,
TemplateNotSendable,
TemplateNotTransactional,
+ TooManyKeys,
TransactionalEmailError,
TransactionalEmailPaused,
)
-from products.messaging.backend.models import MessageCategory, MessageTemplate
+from products.messaging.backend.models import MessageCategory, MessageTemplate, TransactionalEmailKey
from products.messaging.backend.models.message_category import MessageCategoryType
+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 (
TransactionalEmailContent,
TransactionalEmailContentInvalid,
+ TransactionalEmailSenderRequired,
TransactionalEmailSenderUnavailable,
+ code_send_sender_id,
+ create_code_email_workflow,
create_transactional_email_workflow,
resolve_transactional_email_sender,
update_transactional_email_workflow,
@@ -152,11 +166,19 @@ PIPELINE_REFUSALS: dict[str, tuple[type[TransactionalEmailError], str]] = {
"The recipient's address can't receive email: it isn't a valid address, or its domain has no mail servers, "
"so the email would bounce. Check the address for a typo.",
),
- "not_sendable": (TransactionalEmailPaused, "The template's transactional email isn't active."),
+ "not_sendable": (TransactionalEmailPaused, "This email's workflow isn't active. Turn it back on to send."),
+ "invalid_request": (
+ InvalidRequest,
+ "The email pipeline couldn't accept a field of this email, so it wasn't sent. Check the addresses and "
+ "fields, then send it again.",
+ ),
}
IDEMPOTENCY_KEY_PATTERN = re.compile(r"[!-~]{1,255}")
+TRANSACTIONAL_EMAIL_KEY_LIMIT = 1000
+TRANSACTIONAL_EMAIL_KEY_LOCK = "transactional-email-keys"
+
def check_sendable(team_id: int, *, template_type: str, content: dict, message_category_id: UUID | None) -> None:
"""Raise when a template with these fields can't be a transactional email."""
@@ -179,6 +201,11 @@ def check_sendable(team_id: int, *, template_type: str, content: dict, message_c
SENDER_ADDRESS_MAX_LENGTH = 254
# Matches the send path, which ignores a custom address that fails these checks and sends from the sender's own.
SENDER_ADDRESS_PATTERN = re.compile(r'^[^\s@"<>,;]+@[^\s@"<>,;]+\.[^\s@"<>,;]+$')
+PIPELINE_ADDRESS_PATTERN = re.compile(
+ r"[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*"
+ r"@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?"
+ r"(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+"
+)
def sender_address_error(team_id: int, sender: dict[str, Any]) -> str | None:
@@ -360,13 +387,88 @@ def _transactional_workflow_id(team_id: int, template: TransactionalTemplate) ->
content=template.content,
message_category_id=template.message_category_id,
)
+ _require_active(team_id, template.transactional_hog_flow_id)
+ return template.transactional_hog_flow_id
+
+
+def _require_active(team_id: int, hog_flow_id: UUID) -> None:
try:
- workflow = get_workflow_summary(team_id=team_id, workflow_id=str(template.transactional_hog_flow_id))
+ workflow = get_workflow_summary(team_id=team_id, workflow_id=str(hog_flow_id))
except WorkflowNotFound as e:
- raise TransactionalEmailPaused("The template's transactional email no longer exists.") from e
+ raise TransactionalEmailPaused("This email's workflow no longer exists.") from e
if workflow.status != "active":
- raise TransactionalEmailPaused("The template's transactional email isn't active.")
- return template.transactional_hog_flow_id
+ raise TransactionalEmailPaused("This email's workflow isn't active. Turn it back on to send.")
+
+
+def _code_email_workflow_id(team_id: int, key: str) -> UUID:
+ template = _template_for_key(team_id, key)
+ if template is not None:
+ return _transactional_workflow_id(team_id, template)
+ hog_flow_id = _key_workflow_id(team_id, key)
+ _require_active(team_id, hog_flow_id)
+ return hog_flow_id
+
+
+def _template_for_key(team_id: int, key: str) -> MessageTemplate | None:
+ return MessageTemplate.objects.filter(team_id=team_id, key=key, deleted=False).first()
+
+
+def known_key(team_id: int, key: str) -> TransactionalEmailKey | None:
+ return TransactionalEmailKey.objects.for_team(team_id, canonical=True).filter(key=key).first()
+
+
+def _key_workflow_id(team_id: int, key: str) -> UUID:
+ known = known_key(team_id, key)
+ if known is not None and _workflow_exists(team_id, known.hog_flow_id):
+ return known.hog_flow_id
+ with transaction.atomic():
+ _lock_team_keys(team_id)
+ known = known_key(team_id, key)
+ if known is not None:
+ if _workflow_exists(team_id, known.hog_flow_id):
+ return known.hog_flow_id
+ known.delete()
+ keys = TransactionalEmailKey.objects.for_team(team_id, canonical=True)
+ if keys.count() >= TRANSACTIONAL_EMAIL_KEY_LIMIT:
+ raise TooManyKeys(
+ f"This project has reached its limit of {TRANSACTIONAL_EMAIL_KEY_LIMIT} template keys, so it can't "
+ "send under a new one. Use one template_key for each type of email, such as `order-shipped`, and "
+ "reuse it for every recipient."
+ )
+ hog_flow_id = create_code_email_workflow(team_id=team_id, key=key)
+ keys.create(team_id=team_id, key=key, hog_flow_id=hog_flow_id)
+ return hog_flow_id
+
+
+def _lock_team_keys(team_id: int) -> None:
+ with connection.cursor() as cursor:
+ cursor.execute(
+ "SELECT pg_advisory_xact_lock(hashtextextended(%s, 0))", [f"{TRANSACTIONAL_EMAIL_KEY_LOCK}:{team_id}"]
+ )
+
+
+def require_code_email_access(
+ team_id: int,
+ key: str,
+ *,
+ 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()
+ if template is not None:
+ if template.transactional_hog_flow_id is not None:
+ require_workflow_editor(template.transactional_hog_flow_id)
+ return
+ hog_flow_id = (
+ TransactionalEmailKey.objects.for_team(team_id, canonical=True)
+ .filter(key=key)
+ .values_list("hog_flow_id", flat=True)
+ .first()
+ )
+ if hog_flow_id is not None and _workflow_exists(team_id, hog_flow_id):
+ require_workflow_editor(hog_flow_id)
+ else:
+ require_workflow_create()
def send_transactional_email(
@@ -379,6 +481,35 @@ def send_transactional_email(
idempotency_key: str | None = None,
timeout: float = 10,
) -> QueuedEmail:
+ _check_send_request(to, idempotency_key)
+ with transactional_email_stage("workflow_lookup"):
+ # A template passed in must be one of the team's templates that is not deleted, as this lookup returns.
+ if isinstance(template, UUID):
+ model = MessageTemplate.objects.get(team_id=team.id, id=template, deleted=False)
+ hog_flow_id = _transactional_workflow_id(team.id, model)
+ else:
+ hog_flow_id = _transactional_workflow_id(team.id, template)
+ payload = _send_payload(to, distinct_id, message_data, idempotency_key)
+ return _queue(team.id, hog_flow_id, payload, run_transactional_workflow, timeout=timeout)
+
+
+def send_code_email(
+ team: Team,
+ email: CodeEmail,
+ *,
+ to: str,
+ distinct_id: str | None,
+ idempotency_key: str | None = None,
+) -> QueuedEmail:
+ _check_send_request(to, idempotency_key)
+ with transactional_email_stage("workflow_lookup"):
+ accepted_send = _accepted_send(team.id, email)
+ hog_flow_id = _code_email_workflow_id(team.id, email.key)
+ payload = {**_send_payload(to, distinct_id, {}, idempotency_key), "send": accepted_send}
+ return _queue(team.id, hog_flow_id, payload, send_accepted_transactional_email)
+
+
+def _check_send_request(to: str, idempotency_key: str | None) -> None:
if idempotency_key is not None and not IDEMPOTENCY_KEY_PATTERN.fullmatch(idempotency_key):
raise InvalidIdempotencyKey(
"The Idempotency-Key header must be 1 to 255 visible ASCII characters, with no spaces."
@@ -387,16 +518,11 @@ def send_transactional_email(
if "{" in to or "}" in to:
raise InvalidRecipient("The recipient address can't contain { or }.")
- with transactional_email_stage("workflow_lookup"):
- # A template passed in must be one of the team's templates that is not deleted, as this lookup returns.
- if isinstance(template, UUID):
- template_id = template
- model = MessageTemplate.objects.get(team_id=team.id, id=template_id, deleted=False)
- hog_flow_id = _transactional_workflow_id(team.id, model)
- else:
- template_id = template.id
- hog_flow_id = _transactional_workflow_id(team.id, template)
- payload = {
+
+def _send_payload(
+ to: str, distinct_id: str | None, message_data: dict[str, Any], idempotency_key: str | None
+) -> dict[str, Any]:
+ payload: dict[str, Any] = {
"to": to,
# The recipient is the person the send is tracked against. Without a distinct_id, the address is one.
"distinct_id": distinct_id or to,
@@ -405,31 +531,86 @@ def send_transactional_email(
if idempotency_key is not None:
# The CDP service holds the key, because only it knows whether the email was queued.
payload["idempotency_key"] = idempotency_key
+ return payload
+
+
+def _accepted_send(team_id: int, email: CodeEmail) -> dict[str, Any]:
+ accepted: dict[str, Any] = {
+ "content": _without_empty(
+ {"subject": email.subject, "html": email.html, "text": email.text or text_from_html(email.html)}
+ ),
+ "from": _without_empty(_code_send_sender(team_id, email.sender)),
+ "tracking": {"captureEngagement": email.capture_engagement},
+ }
+ if email.reply_to:
+ accepted["replyTo"] = list(email.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:
+ sender_id = code_send_sender_id(team_id=team_id, email=email or None)
+ except TransactionalEmailSenderRequired as e:
+ raise SenderRequired(
+ "This project has more than one verified sender and no default sender. Send `from` to choose one."
+ ) from e
+ except TransactionalEmailSenderUnavailable as e:
+ if address:
+ raise SenderNotVerified(f"No verified sender in this project can send from `{email}`.") from e
+ raise SenderNotVerified("This project has no verified email sender. Verify a sender domain first.") from e
+ return {"integrationId": sender_id, "email": email, "name": name}
+
+
+def _without_empty(fields: dict[str, Any]) -> dict[str, Any]:
+ return {name: value for name, value in fields.items() if value}
+
+
+class _PipelinePost(Protocol):
+ def __call__(self, team_id: int, hog_flow_id: str, payload: dict, *, timeout: float = ...) -> requests.Response: ...
+
+
+def _queue(
+ team_id: int,
+ hog_flow_id: UUID,
+ payload: dict[str, Any],
+ post: _PipelinePost,
+ *,
+ timeout: float = 10,
+) -> QueuedEmail:
started_at = time.monotonic()
try:
- response = run_transactional_workflow(team.id, str(hog_flow_id), payload, timeout=timeout)
+ response = post(team_id, str(hog_flow_id), payload, timeout=timeout)
except Exception as e:
_observe_cdp_call(time.monotonic() - started_at)
CDP_SEND_RESULTS.labels(result=_cdp_error_result(e)).inc()
- logger.exception("transactional_email_queue_failed", team_id=team.id, template_id=str(template_id))
+ logger.exception("transactional_email_queue_failed", team_id=team_id, hog_flow_id=str(hog_flow_id))
raise DeliveryUnavailable() from e
_observe_cdp_call(time.monotonic() - started_at)
CDP_SEND_RESULTS.labels(result=_cdp_response_result(response.status_code)).inc()
+ if response.status_code == 413:
+ raise ContentTooLarge(
+ "The email is larger than PostHog can send. Make its content or data smaller, and link to "
+ "large images and files instead of embedding them."
+ )
if response.status_code != 202:
refusal_code = _refusal_code(response)
refusal = PIPELINE_REFUSALS.get(refusal_code or "")
- if refusal is not None:
- error_class, message = refusal
- raise error_class(message)
- logger.error(
- "transactional_email_queue_rejected",
- team_id=team.id,
- template_id=str(template_id),
- status_code=response.status_code,
- refusal_code=refusal_code,
- )
- raise DeliveryUnavailable()
+ if refusal is None and response.status_code == 400:
+ refusal = PIPELINE_REFUSALS["invalid_request"]
+ if refusal is None or refusal[0] is InvalidRequest:
+ logger.error(
+ "transactional_email_queue_rejected",
+ team_id=team_id,
+ hog_flow_id=str(hog_flow_id),
+ status_code=response.status_code,
+ refusal_code=refusal_code,
+ )
+ if refusal is None:
+ raise DeliveryUnavailable()
+ error_class, message = refusal
+ raise error_class(message)
body = response.json()
return QueuedEmail(message_id=str(body["invocation_id"]), replayed=bool(body.get("replayed", False)))
diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.py
index e9f7ea32e08f..8040bc32d368 100644
--- a/products/messaging/backend/tests/api/test_transactional_email.py
+++ b/products/messaging/backend/tests/api/test_transactional_email.py
@@ -1,5 +1,6 @@
+import json
from typing import Any, get_args
-from uuid import uuid4
+from uuid import UUID, uuid4
import pytest
from posthog.test.base import APIBaseTest
@@ -21,8 +22,33 @@ from posthog.models.utils import generate_random_token_secret
from products.access_control.backend.facade.testing import create_access_control
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
+from products.messaging.backend.presentation.views.message_templates import (
+ CODE_SEND_FIELDS,
+ EMAIL_FROM_CODE_FLAG,
+ TRANSACTIONAL_EMAIL_API_FLAG,
+)
+from products.messaging.backend.services import transactional_email
from products.messaging.backend.services.transactional_email import TransactionalEmailStage, make_transactional
from products.workflows.backend.facade.api import set_default_email_sender_if_unset
+from products.workflows.backend.facade.models import HogFlow
+from products.workflows.backend.facade.team_extension import TeamWorkflowsConfig
+
+ADDRESS_VERDICTS = [
+ ("[email protected]", True),
+ ("[email protected]", True),
+ ("jane#[email protected]", True),
+ ("o'[email protected]", True),
+ ("a!b$c%d&e*f/g?h^i`j|[email protected]", True),
+ ("[email protected]", True),
+ ("jane@bücher.example", False),
+ ("jane@[192.0.2.1]", False),
+ ('"jane doe"@example.com', False),
+ ("jane@localhost", False),
+ ("[email protected]", False),
+ ("[email protected]", False),
+ ("[email protected]", False),
+]
def _stage_counts() -> dict[str, float]:
@@ -89,10 +115,10 @@ class TestTransactionalEmail(APIBaseTest):
flat["distinct_id"] = body["identifiers"]["distinct_id"]
return {**flat, "template_id": str(self.template.id)}
- def _psak_client(self, scopes: list[str]) -> APIClient:
+ def _psak_client(self, scopes: list[str], team: Team | None = None) -> APIClient:
raw_token = generate_random_token_secret()
ProjectSecretAPIKey.objects.create(
- team=self.team,
+ team=team or self.team,
label="transactional email",
secure_value=hash_key_value(raw_token),
scopes=scopes,
@@ -104,24 +130,25 @@ class TestTransactionalEmail(APIBaseTest):
@parameterized.expand(
[
- ("with_distinct_id", "template", {"distinct_id": "user-1"}, "user-1"),
+ ("with_distinct_id", "template", {"identifiers": {"distinct_id": "user-1"}}, "user-1"),
# Without a distinct_id the recipient's address is the person the send is tracked against.
- ("email_only", "template", None, "[email protected]"),
+ ("email_only", "template", {}, "[email protected]"),
("with_distinct_id_on_send_email", "send_email", {"distinct_id": "user-1"}, "user-1"),
- ("email_only_on_send_email", "send_email", None, "[email protected]"),
- ("with_distinct_id_on_send_email_nested", "send_email_nested", {"distinct_id": "user-1"}, "user-1"),
- ("email_only_on_send_email_nested", "send_email_nested", None, "[email protected]"),
+ ("email_only_on_send_email", "send_email", {}, "[email protected]"),
+ (
+ "with_distinct_id_on_send_email_nested",
+ "send_email_nested",
+ {"identifiers": {"distinct_id": "user-1"}},
+ "user-1",
+ ),
+ ("email_only_on_send_email_nested", "send_email_nested", {}, "[email protected]"),
]
)
def test_runs_the_templates_workflow_for_the_recipient(
- self, mock_post, _flag, capture, _name, route, identifiers, expected_distinct_id
+ self, mock_post, _flag, capture, _name, route, recipient, expected_distinct_id
):
self._cdp_accepts(mock_post)
- body = (
- {**self.body, "identifiers": identifiers}
- if identifiers
- else {k: v for k, v in self.body.items() if k != "identifiers"}
- )
+ body = {**{k: v for k, v in self.body.items() if k != "identifiers"}, **recipient}
client = self._psak_client(["hog_flow:write"])
stages_before = _stage_counts()
@@ -180,6 +207,7 @@ class TestTransactionalEmail(APIBaseTest):
("send_with_status_scope", "post", "send/", ["transactional_email:read"], status.HTTP_403_FORBIDDEN),
("send_email_with_write_scope", "post", "send_email", ["hog_flow:write"], status.HTTP_202_ACCEPTED),
("send_email_with_read_scope", "post", "send_email", ["hog_flow:read"], status.HTTP_403_FORBIDDEN),
+ ("code_send_with_read_scope", "post", "code_send", ["hog_flow:read"], status.HTTP_403_FORBIDDEN),
(
"send_email_with_preference_scope",
"post",
@@ -201,6 +229,13 @@ class TestTransactionalEmail(APIBaseTest):
["transactional_email:read"],
status.HTTP_403_FORBIDDEN,
),
+ (
+ "code_send_with_send_scope",
+ "post",
+ "code_send",
+ ["transactional_email:write"],
+ status.HTTP_202_ACCEPTED,
+ ),
("retrieve_is_not_a_psak_action", "get", "", ["hog_flow:write"], status.HTTP_403_FORBIDDEN),
(
"make_transactional_is_not_a_psak_action",
@@ -217,6 +252,8 @@ class TestTransactionalEmail(APIBaseTest):
self._cdp_accepts(mock_post)
if suffix == "send_email":
url, body = self.send_email_url, self._flat(self.body)
+ elif suffix == "code_send":
+ url, body = self.send_email_url, self._code_send()
else:
url, body = f"/api/projects/{self.team.id}/messaging_templates/{self.template.id}/{suffix}", self.body
@@ -313,10 +350,10 @@ class TestTransactionalEmail(APIBaseTest):
("connection_error", requests.ConnectionError(), "connection_error", None),
("cdp_api_error", MagicMock(status_code=500, json=dict), "5xx", None),
(
- "invalid_request",
- MagicMock(status_code=400, json=lambda: {"error": "invalid_request"}),
+ "workflow_not_found",
+ MagicMock(status_code=404, json=lambda: {"error": "Workflow not found"}),
"4xx",
- "invalid_request",
+ "Workflow not found",
),
]
)
@@ -401,6 +438,9 @@ class TestTransactionalEmail(APIBaseTest):
("recipient_suppressed", 422, 422, "recipient_suppressed"),
("recipient_unreachable", 422, 422, "recipient_unreachable"),
("not_sendable", 400, 400, "transactional_email_paused"),
+ ("invalid_request", 400, 400, "invalid_request"),
+ ("a 400 without a known code", 400, 400, "invalid_request"),
+ ("Request entity too large", 413, 400, "content_too_large"),
]
)
def test_reports_a_send_the_pipeline_refuses(
@@ -455,6 +495,348 @@ class TestTransactionalEmail(APIBaseTest):
assert response.status_code == expected_status, response.json()
mock_post.assert_not_called()
+ def _code_send(self, **fields: Any) -> dict[str, Any]:
+ return {
+ "distinct_id": "user-1",
+ "template_key": "welcome",
+ "subject": "Welcome, Jane",
+ "html": "<p>Hi Jane</p>",
+ **fields,
+ }
+
+ @parameterized.expand([("new_key", "welcome"), ("key_that_names_a_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)
+ templates_before = MessageTemplate.objects.filter(team=self.team).count()
+ psak = self._psak_client(["hog_flow:write"])
+
+ first = psak.post(self.send_email_url, self._code_send(template_key=key), format="json")
+ second = psak.post(self.send_email_url, self._code_send(template_key=key, subject="Again"), format="json")
+
+ assert first.status_code == status.HTTP_202_ACCEPTED, first.json()
+ assert first.json() == {"message_id": "invocation-1", "replayed": False}
+ assert second.status_code == status.HTTP_202_ACCEPTED, second.json()
+ first_url, second_url = (call.args[0] for call in mock_post.call_args_list)
+ 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":
+ assert hog_flow_id == str(self.hog_flow_id)
+ else:
+ assert TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).get(
+ key=key
+ ).hog_flow_id == UUID(hog_flow_id)
+ listed = self.client.get(f"/api/projects/{self.team.id}/hog_flows/").json()["results"]
+ assert hog_flow_id not in {workflow["id"] for workflow in listed}
+ email_step = HogFlow.objects.get(team=self.team, id=hog_flow_id).actions[1]["config"]
+ assert (email_step["sensitive"], email_step.get("template_key")) == (
+ (True, "welcome") if key == "welcome" else (False, None)
+ )
+ assert json.loads(mock_post.call_args_list[0].kwargs["data"]) == {
+ "distinct_id": "user-1",
+ "variables": {},
+ "send": {
+ "content": {"subject": "Welcome, Jane", "html": "<p>Hi Jane</p>", "text": "Hi Jane"},
+ "from": {"integrationId": self.sender.id},
+ "tracking": {"captureEngagement": True},
+ },
+ }
+ assert MessageTemplate.objects.filter(team=self.team).count() == templates_before
+ reported = capture.call_args.kwargs["properties"]
+ assert (reported["route"], reported["addressed_by"], reported["outcome"]) == (
+ "send_email",
+ "template_key",
+ "queued",
+ )
+
+ def test_each_environment_of_a_project_keeps_its_own_workflow_for_a_key(self, mock_post, _flag, _capture):
+ self._cdp_accepts(mock_post)
+ env = Team.objects.create(organization=self.organization, parent_team=self.team, name="env")
+ env_sender = Integration.objects.create(
+ team=env, kind="email", integration_id="[email protected]", config={"verified": True}
+ )
+ set_default_email_sender_if_unset(env.id, env_sender.id)
+ clients = {
+ self.team.id: self._psak_client(["hog_flow:write"]),
+ env.id: self._psak_client(["hog_flow:write"], env),
+ }
+
+ for team_id in (self.team.id, env.id, self.team.id, env.id):
+ response = clients[team_id].post(
+ f"/api/projects/{team_id}/messaging/send/email/", self._code_send(), format="json"
+ )
+ assert response.status_code == status.HTTP_202_ACCEPTED, response.json()
+
+ workflow_ids = [call.args[0].split("/hog_flows/")[1].split("/")[0] for call in mock_post.call_args_list]
+ assert workflow_ids[0] == workflow_ids[2]
+ assert workflow_ids[1] == workflow_ids[3]
+ assert workflow_ids[0] != workflow_ids[1]
+
+ def test_a_known_key_keeps_sending_at_the_key_limit_while_a_new_key_is_refused(self, mock_post, _flag, capture):
+ self._cdp_accepts(mock_post)
+ psak = self._psak_client(["hog_flow:write"])
+ with patch.object(transactional_email, "TRANSACTIONAL_EMAIL_KEY_LIMIT", 1):
+ first = psak.post(self.send_email_url, self._code_send(template_key="welcome"), format="json")
+ deleted_workflow_id = (
+ TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).get(key="welcome").hog_flow_id
+ )
+ HogFlow.objects.filter(team=self.team, id=deleted_workflow_id).delete()
+
+ second = psak.post(self.send_email_url, self._code_send(template_key="welcome"), format="json")
+ new_key = psak.post(self.send_email_url, self._code_send(template_key="receipt"), format="json")
+
+ assert first.status_code == second.status_code == status.HTTP_202_ACCEPTED, second.json()
+ new_workflow_id = (
+ TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).get(key="welcome").hog_flow_id
+ )
+ assert new_workflow_id != deleted_workflow_id
+ assert f"/hog_flows/{new_workflow_id}/" in mock_post.call_args_list[1].args[0]
+ assert new_key.status_code == status.HTTP_400_BAD_REQUEST, new_key.json()
+ assert new_key.json()["code"] == "too_many_keys"
+ assert capture.call_args.kwargs["properties"]["error_code"] == "too_many_keys"
+ assert mock_post.call_count == 2
+ assert not TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).filter(key="receipt").exists()
+ assert not HogFlow.objects.filter(team=self.team, name="receipt").exists()
+
+ @parameterized.expand(
+ [
+ (
+ "sender_and_reply_to",
+ {"text": "Hi", "from": "Example <[email protected]>", "reply_to": ["[email protected]"]},
+ {
+ "content": {"subject": "Welcome, Jane", "html": "<p>Hi Jane</p>", "text": "Hi"},
+ "from": {"email": "[email protected]", "name": "Example"},
+ "replyTo": ["[email protected]"],
+ "tracking": {"captureEngagement": True},
+ },
+ ),
+ (
+ "without_engagement_capture",
+ {"capture_engagement": False},
+ {
+ "content": {"subject": "Welcome, Jane", "html": "<p>Hi Jane</p>", "text": "Hi Jane"},
+ "tracking": {"captureEngagement": False},
+ },
+ ),
+ (
+ "text_only",
+ {"html": "", "text": "Hi"},
+ {"content": {"subject": "Welcome, Jane", "text": "Hi"}, "tracking": {"captureEngagement": True}},
+ ),
+ ]
+ )
+ def test_a_code_send_carries_what_the_caller_set(self, mock_post, _flag, _capture, _name, fields, sent):
+ self._cdp_accepts(mock_post)
+ newer_default = Integration.objects.create(
+ team=self.team, kind="email", integration_id="[email protected]", config={"verified": True}
+ )
+ TeamWorkflowsConfig.objects.filter(team_id=self.team.id).update(default_email_integration_id=newer_default.id)
+
+ response = self._psak_client(["hog_flow:write"]).post(
+ self.send_email_url, self._code_send(**fields), format="json"
+ )
+
+ assert response.status_code == status.HTTP_202_ACCEPTED, response.json()
+ sent = {**sent, "from": {**sent.get("from", {}), "integrationId": newer_default.id}}
+ assert json.loads(mock_post.call_args.kwargs["data"])["send"] == sent
+
+ @parameterized.expand(
+ [
+ ("no_subject", {"subject": ""}, "subject"),
+ ("no_body", {"html": None}, "html"),
+ ("data_for_rendered_content", {"message_data": {"name": "Jane"}}, "message_data"),
+ ("both_a_template_and_a_key", {"template_id": str(uuid4())}, "template_id"),
+ ("both_a_nested_template_and_a_key", {"template": {"id": str(uuid4())}}, "template_id"),
+ ("neither_a_template_nor_a_key", {"template_key": None}, "template_id"),
+ ("nested_identifiers", {"identifiers": {"distinct_id": "user-1"}}, "identifiers"),
+ ("invalid_key", {"template_key": "welcome email"}, "template_key"),
+ ("sender_that_is_not_an_address", {"from": "Example"}, "from"),
+ ("sender_with_a_quoted_local_part", {"from": '"security"@example.com'}, "from"),
+ ("sender_nested_too_deep_to_parse", {"from": "(" * 1000 + "[email protected]" + ")" * 1000}, "from"),
+ ("sender_over_1024_characters", {"from": "E" * 1024 + " <[email protected]>"}, "from"),
+ ("empty_reply_to", {"reply_to": []}, "reply_to"),
+ ("field_this_server_lacks", {"scheduled_at": "2026-11-01T09:00:00Z"}, "scheduled_at"),
+ ("empty_key_beside_a_field_this_server_lacks", {"": "", "scheduled_at": "2026-11-01T09:00:00Z"}, None),
+ ("html_over_5_mib_in_utf8", {"html": "é" * (5 * 1024 * 1024 // 2 + 1)}, "html"),
+ ("text_over_5_mib_in_utf8", {"text": "é" * (5 * 1024 * 1024 // 2 + 1)}, "text"),
+ ]
+ )
+ def test_refuses_a_code_send_with_an_invalid_field(self, mock_post, _flag, _capture, _name, fields, attr):
+ body = {key: value for key, value in self._code_send(**fields).items() if value is not None}
+
+ response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, body, format="json")
+
+ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+ assert response.json()["attr"] == attr
+ mock_post.assert_not_called()
+
+ @parameterized.expand(
+ [(field, address, accepted) for field in ("to", "reply_to") for address, accepted in ADDRESS_VERDICTS]
+ )
+ def test_a_code_send_takes_the_addresses_the_pipeline_takes(
+ self, mock_post, _flag, _capture, field, address, accepted
+ ):
+ self._cdp_accepts(mock_post)
+ value = address if field == "to" else [address]
+
+ response = self._psak_client(["hog_flow:write"]).post(
+ self.send_email_url, self._code_send(**{field: value}), format="json"
+ )
+
+ if accepted:
+ assert response.status_code == status.HTTP_202_ACCEPTED, response.json()
+ sent = json.loads(mock_post.call_args.kwargs["data"])
+ assert (sent["to"] if field == "to" else sent["send"]["replyTo"]) == value
+ else:
+ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+ assert response.json()["attr"].startswith(field)
+ 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"})
+
+ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+ assert response.json()["attr"] == "subject"
+ mock_post.assert_not_called()
+
+ @parameterized.expand(
+ [
+ ("the_only_verified_sender", ["verified"], status.HTTP_202_ACCEPTED, None),
+ (
+ "one_of_several_verified_senders",
+ ["verified", "verified"],
+ status.HTTP_400_BAD_REQUEST,
+ "sender_required",
+ ),
+ ("no_verified_sender", ["unverified"], status.HTTP_400_BAD_REQUEST, "sender_not_verified"),
+ ]
+ )
+ def test_a_code_send_without_from_and_without_a_default_sends_from(
+ self, mock_post, _flag, _capture, _name, senders, expected_status, code
+ ):
+ self._cdp_accepts(mock_post)
+ Integration.objects.filter(id=self.sender.id).delete()
+ TeamWorkflowsConfig.objects.filter(team_id=self.team.id).update(default_email_integration_id=None)
+ created = [
+ Integration.objects.create(
+ team=self.team,
+ kind="email",
+ integration_id=f"sender-{index}@example.com",
+ config={"verified": state == "verified"},
+ )
+ for index, state in enumerate(senders)
+ ]
+
+ response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, self._code_send(), format="json")
+
+ assert response.status_code == expected_status, response.json()
+ if code is None:
+ assert json.loads(mock_post.call_args.kwargs["data"])["send"]["from"] == {"integrationId": created[0].id}
+ else:
+ assert response.json()["code"] == code
+ 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": "[email protected]"}), format="json"
+ )
+
+ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()
+ assert response.json()["code"] == "sender_not_verified"
+ assert not TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).exists()
+ 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):
+ mock_post.side_effect = requests.ReadTimeout()
+
+ response = self._psak_client(["hog_flow:write"]).post(self.send_email_url, self._code_send(), format="json")
+
+ assert response.status_code == status.HTTP_503_SERVICE_UNAVAILABLE
+ assert response.json()["code"] == "delivery_unavailable"
+ assert "may still go out" in response.json()["detail"]
+ assert "within 24 hours with the same Idempotency-Key" in response.json()["detail"]
+
+ def test_the_send_schema_gives_a_template_send_no_code_only_field(self, _mock_post, _flag, _capture):
+ schema = self.client.get("/api/schema/").data
+
+ 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]} == {}
+
+ @parameterized.expand(
+ [
+ ("replay", 202, {"invocation_id": "first-send", "replayed": True}, 202, None),
+ ("key_used_by_a_template_send", 422, {"error": "idempotency_key_reused"}, 422, "idempotency_key_reused"),
+ ("recipient_suppressed", 422, {"error": "recipient_suppressed"}, 422, "recipient_suppressed"),
+ ]
+ )
+ def test_a_code_send_passes_its_idempotency_key_and_reports_the_pipelines_answer(
+ self, mock_post, _flag, _capture, _name, pipeline_status, pipeline_body, expected_status, expected_code
+ ):
+ mock_post.return_value = MagicMock(status_code=pipeline_status, json=lambda: pipeline_body)
+
+ response = self._psak_client(["hog_flow:write"]).post(
+ self.send_email_url, self._code_send(), format="json", headers={"Idempotency-Key": "welcome:user-1"}
+ )
+
+ assert response.status_code == expected_status, response.json()
+ assert json.loads(mock_post.call_args.kwargs["data"])["idempotency_key"] == "welcome:user-1"
+ if expected_code:
+ assert response.json()["code"] == expected_code
+ else:
+ assert response.json() == {"message_id": "first-send", "replayed": True}
+
+ @parameterized.expand(
+ [
+ ("below_the_key_limit", transactional_email.TRANSACTIONAL_EMAIL_KEY_LIMIT),
+ ("winner_takes_the_last_key", 1),
+ ]
+ )
+ def test_two_racing_first_sends_of_a_key_make_one_workflow(self, mock_post, _flag, _capture, _name, key_limit):
+ self._cdp_accepts(mock_post)
+ psak = self._psak_client(["hog_flow:write"])
+ lookup = transactional_email.known_key
+ lookups: list[str] = []
+
+ def misses_the_winner_once(team_id: int, key: str) -> TransactionalEmailKey | None:
+ lookups.append(key)
+ return None if len(lookups) == 1 else lookup(team_id, key)
+
+ with patch.object(transactional_email, "TRANSACTIONAL_EMAIL_KEY_LIMIT", key_limit):
+ winner = psak.post(self.send_email_url, self._code_send(), format="json")
+ with patch.object(transactional_email, "known_key", side_effect=misses_the_winner_once):
+ loser = psak.post(self.send_email_url, self._code_send(), format="json")
+
+ assert (winner.status_code, loser.status_code) == (status.HTTP_202_ACCEPTED, status.HTTP_202_ACCEPTED)
+ first_url, second_url = (call.args[0] for call in mock_post.call_args_list)
+ assert first_url == second_url
+ assert TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).filter(key="welcome").count() == 1
+ assert HogFlow.objects.filter(team=self.team, name="welcome").count() == 1
+
+ @parameterized.expand(
+ [
+ ("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),
+ ]
+ )
+ def test_each_form_of_a_send_answers_only_while_its_flag_is_on(
+ self, mock_post, flag, _capture, _name, form, enabled_flags, expected_status
+ ):
+ 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._flat(self.body)
+
+ response = self.client.post(self.send_email_url, body, format="json")
+
+ assert response.status_code == expected_status, response.json()
+ assert mock_post.called == (expected_status == status.HTTP_202_ACCEPTED)
+
def _other_team_template(self) -> MessageTemplate:
other_team = Team.objects.create(organization=self.organization, name="Other project")
template = MessageTemplate.objects.create(
@@ -743,6 +1125,33 @@ class TestTransactionalEmailWorkflowAccess(APIBaseTest):
assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
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")
+
+ response = self.client.post(
+ f"/api/projects/{self.team.id}/messaging/send/email/",
+ {"to": "[email protected]", "template_key": "password-reset", "subject": "Hi", "html": "<p>Hi</p>"},
+ format="json",
+ )
+
+ assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
+ mock_post.assert_not_called()
+
+ def test_a_member_who_cannot_create_workflows_cannot_send_code_under_a_new_key(self, mock_post, _flag):
+ self._login_member("[email protected]", {None: "viewer", str(self.hog_flow_id): "editor"})
+ workflows_before = HogFlow.objects.filter(team=self.team).count()
+
+ response = self.client.post(
+ f"/api/projects/{self.team.id}/messaging/send/email/",
+ {"to": "[email protected]", "template_key": "welcome", "subject": "Welcome", "html": "<p>Hi</p>"},
+ format="json",
+ )
+
+ assert response.status_code == status.HTTP_403_FORBIDDEN, response.json()
+ assert HogFlow.objects.filter(team=self.team).count() == workflows_before
+ assert not TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).exists()
+ mock_post.assert_not_called()
+
@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("[email protected]", {None: "viewer", str(self.hog_flow_id): "editor"})
diff --git a/products/messaging/backend/tests/api/test_transactional_email_status.py b/products/messaging/backend/tests/api/test_transactional_email_status.py
index c53839eee9d4..b4c42565304b 100644
--- a/products/messaging/backend/tests/api/test_transactional_email_status.py
+++ b/products/messaging/backend/tests/api/test_transactional_email_status.py
@@ -187,10 +187,17 @@ class TestTransactionalEmailStatus(ClickhouseTestMixin, APIBaseTest):
assert response.status_code == status.HTTP_401_UNAUTHORIZED
- def test_is_hidden_while_the_flag_is_off(self, flag):
- flag.return_value = False
+ @parameterized.expand(
+ [
+ ("both_send_flags_off", set(), status.HTTP_404_NOT_FOUND),
+ ("only_the_template_send_flag", {"workflows-transactional-email-api"}, status.HTTP_200_OK),
+ ("only_the_code_send_flag", {"workflows-email-from-code"}, status.HTTP_200_OK),
+ ]
+ )
+ def test_reads_a_status_under_either_send_flag(self, flag, _name, enabled_flags, expected_status):
+ flag.side_effect = lambda key, *args, **kwargs: key in enabled_flags
self._status_rows([("queued", 0, "")])
response = self.client.get(self._url(self.message_id))
- assert response.status_code == status.HTTP_404_NOT_FOUND
+ assert response.status_code == expected_status
diff --git a/products/messaging/backend/tests/test_html_text.py b/products/messaging/backend/tests/test_html_text.py
new file mode 100644
index 000000000000..a977cf0f26f5
--- /dev/null
+++ b/products/messaging/backend/tests/test_html_text.py
@@ -0,0 +1,90 @@
+import tracemalloc
+
+import pytest
+
+from django.test import SimpleTestCase
+
+from parameterized import parameterized
+
+from products.messaging.backend.services.html_text import text_from_html
+
+
+class TestTextFromHtml(SimpleTestCase):
+ @parameterized.expand(
+ [
+ (
+ "blocks_become_lines",
+ "<h1>Reset</h1><p>Hi Jane,</p><p>Use the link.</p>",
+ "Reset\n\nHi Jane,\n\nUse the link.",
+ ),
+ ("line_breaks_stay", "<p>Line one<br>Line two</p>", "Line one\nLine two"),
+ (
+ "link_keeps_its_address",
+ '<p><a href="https://example.com/reset?t=1">Reset password</a></p>',
+ "Reset password (https://example.com/reset?t=1)",
+ ),
+ (
+ "link_that_shows_its_address",
+ '<a href="https://example.com">https://example.com</a>',
+ "https://example.com",
+ ),
+ ("hidden_parts_are_dropped", "<style>p{color:red}</style><script>x()</script><p>Hi</p>", "Hi"),
+ ("entities_are_decoded", "<p>Tom &amp; Jerry&nbsp;&lt;3</p>", "Tom & Jerry <3"),
+ ("source_whitespace_collapses", "<p>Hi\n Jane</p>\n\n\n<p>Bye</p>", "Hi Jane\n\nBye"),
+ ("list_items_are_lines", "<ul><li>One</li><li>Two</li></ul>", "One\nTwo"),
+ ("text_after_a_line_block_starts_a_new_line", "<div>Order 123</div>shipped", "Order 123\nshipped"),
+ ]
+ )
+ def test_derives_readable_text(self, _name, html, expected):
+ assert text_from_html(html) == expected
+
+ @parameterized.expand(
+ [
+ ("divs", "<div>" * 5000 + "Hi" + "</div>" * 5000, "Hi"),
+ (
+ "links_that_show_their_address",
+ '<a href="https://example.com">' * 5000 + "https://example.com" + "</a>" * 5000,
+ "https://example.com",
+ ),
+ (
+ "links_with_a_label",
+ '<a href="https://example.com">' * 5000 + "Go" + "</a>" * 5000,
+ "Go" + " (https://example.com)" * 5000,
+ ),
+ (
+ "link_inside_a_link",
+ '<a href="https://example.com/a">Outer <a href="https://example.com/b">https://example.com/b</a></a>',
+ "Outer https://example.com/b (https://example.com/a)",
+ ),
+ (
+ "address_split_over_elements",
+ '<a href="https://example.com/ab">https://example.com/<b>ab</b></a>',
+ "https://example.com/ab",
+ ),
+ ]
+ )
+ def test_deeply_nested_html_still_gives_its_text(self, _name, html, expected):
+ assert text_from_html(html) == expected
+
+ @parameterized.expand(
+ [
+ ("line_breaks", "<br>" * 131072 + "Hi", "Hi"),
+ ("unclosed_nesting", "<div><p>" * 65536 + "Hi", "Hi"),
+ ("closed_nesting", "<div>" * 50000 + "Hi" + "</div>" * 50000, "Hi"),
+ ]
+ )
+ def test_half_a_mebibyte_of_markup_converts_in_bounded_memory(self, _name, html, expected):
+ tracemalloc.start()
+ try:
+ text = text_from_html(html)
+ peak = tracemalloc.get_traced_memory()[1]
+ finally:
+ tracemalloc.stop()
+ assert text == expected
+ assert peak < 24 * 1024 * 1024
+
+ @pytest.mark.timeout(30, func_only=True)
+ def test_closing_tags_without_an_open_match_convert_in_linear_time(self):
+ html = "<div>" * 43690 + "Hi" + "</span>" * 43690
+
+ assert text_from_html(html) == "Hi"
diff --git a/products/messaging/backend/tests/test_message_template_key.py b/products/messaging/backend/tests/test_message_template_key.py
new file mode 100644
index 000000000000..ad0201893ccc
--- /dev/null
+++ b/products/messaging/backend/tests/test_message_template_key.py
@@ -0,0 +1,34 @@
+from posthog.test.base import BaseTest
+
+from django.db import IntegrityError, transaction
+
+from parameterized import parameterized
+
+from posthog.models import Team
+
+from products.messaging.backend.models.message_template import MessageTemplate
+
+
+class TestMessageTemplateKey(BaseTest):
+ def _create_template(self, team: Team, key: str, deleted: bool = False) -> MessageTemplate:
+ return MessageTemplate.objects.create(team=team, name=key, key=key, deleted=deleted)
+
+ def test_a_live_template_holds_its_key_within_its_team(self) -> None:
+ self._create_template(self.team, "welcome")
+
+ with self.assertRaises(IntegrityError), transaction.atomic():
+ self._create_template(self.team, "welcome")
+
+ @parameterized.expand(
+ [
+ ("in_another_team", False, True),
+ ("after_the_holder_is_deleted", True, False),
+ ]
+ )
+ def test_the_key_is_free(self, _name: str, first_is_deleted: bool, second_in_other_team: bool) -> None:
+ other_team = Team.objects.create(organization=self.organization, name="Other team")
+ self._create_template(self.team, "welcome", deleted=first_is_deleted)
+
+ second = self._create_template(other_team if second_in_other_team else self.team, "welcome")
+
+ self.assertEqual(MessageTemplate.objects.get(pk=second.pk).key, "welcome")
diff --git a/products/messaging/backend/tests/test_transactional_email_key_lock.py b/products/messaging/backend/tests/test_transactional_email_key_lock.py
new file mode 100644
index 000000000000..a50e53582ed3
--- /dev/null
+++ b/products/messaging/backend/tests/test_transactional_email_key_lock.py
@@ -0,0 +1,62 @@
+import uuid
+
+import pytest
+from posthog.test.base import NonAtomicBaseTest
+from unittest.mock import patch
+
+from django.db import connection
+
+import psycopg
+from psycopg import sql
+
+from products.messaging.backend.models.transactional_email_key import TransactionalEmailKey
+from products.messaging.backend.services import transactional_email
+from products.workflows.backend.facade.models import HogFlow
+
+
+class TestTransactionalEmailKeyLock(NonAtomicBaseTest):
+ def _other_connection(self) -> psycopg.Connection:
+ db = connection.settings_dict
+ return psycopg.connect(
+ dbname=db["NAME"],
+ user=db["USER"],
+ password=db["PASSWORD"],
+ host=db["HOST"] or None,
+ port=db["PORT"] or None,
+ autocommit=True,
+ )
+
+ def test_a_new_key_counts_a_key_another_sender_committed_while_it_waited_for_the_lock(self) -> None:
+ lock = transactional_email._lock_team_keys
+ lock_free_for_another_sender: list[bool] = []
+
+ def lock_then_another_sender_takes_the_last_key(team_id: int) -> None:
+ lock(team_id)
+ with self._other_connection() as other:
+ row = other.execute(
+ "SELECT pg_try_advisory_xact_lock(hashtextextended(%s, 0))",
+ [f"{transactional_email.TRANSACTIONAL_EMAIL_KEY_LOCK}:{team_id}"],
+ ).fetchone()
+ assert row is not None
+ lock_free_for_another_sender.append(row[0])
+ other.execute(
+ sql.SQL(
+ "INSERT INTO {} (id, team_id, key, hog_flow_id, created_at) VALUES (%s, %s, %s, %s, now())"
+ ).format(sql.Identifier(TransactionalEmailKey._meta.db_table)),
+ [uuid.uuid4(), team_id, "welcome", uuid.uuid4()],
+ )
+
+ with (
+ patch.object(transactional_email, "TRANSACTIONAL_EMAIL_KEY_LIMIT", 1),
+ patch.object(
+ transactional_email, "_lock_team_keys", side_effect=lock_then_another_sender_takes_the_last_key
+ ),
+ pytest.raises(transactional_email.TooManyKeys),
+ ):
+ transactional_email._key_workflow_id(self.team.id, "receipt")
+
+ assert lock_free_for_another_sender == [False]
+ assert list(
+ TransactionalEmailKey.objects.for_team(self.team.id, canonical=True).values_list("key", flat=True)
+ ) == ["welcome"]
+ assert not HogFlow.objects.filter(team=self.team, name="receipt").exists()
diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.ts
index f3b1b706ea79..4118521f164a 100644
--- a/products/messaging/frontend/generated/api.schemas.ts
+++ b/products/messaging/frontend/generated/api.schemas.ts
@@ -93,14 +93,38 @@ export interface SendEmailApi {
to: string
/** Data for the template's Liquid placeholders, available as `variables`. For example `{"reset_link": "https://..."}` fills `{{ variables.reset_link }}`. */
message_data?: SendEmailApiMessageData
- /** ID of the email template to send. The template must be made transactional first. */
- template_id: string
+ /** ID of the email template to send. The template must be made transactional first. Send either `template_id` or `template_key`. */
+ template_id?: string
+ /**
+ * Names an email whose content your code rendered, such as `order-shipped`, 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.
+ * @maxLength 400
+ * @pattern ^[a-zA-Z0-9_-]+$
+ */
+ template_key?: string
/**
* Distinct ID of the recipient's person. The email's engagement events (sent, delivered, opened, clicked, bounced) and the send itself are recorded against that person. Defaults to the recipient's email address. The template can't read the person's properties, so pass everything it needs in `message_data`.
* @maxLength 400
* @nullable
*/
distinct_id?: string | null
+ /** Subject of the email your code rendered. */
+ subject?: string
+ /** HTML body of the email your code rendered, at most 5 MiB as UTF-8. */
+ html?: string
+ /** Plain text body of the email your code rendered, at most 5 MiB as UTF-8. Without it, PostHog derives the text from `html`. */
+ text?: string
+ /**
+ * Addresses replies to the email your code rendered go to.
+ * @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. */
+ capture_engagement?: boolean
+ /**
+ * Sender of the email your code rendered, as `[email protected]` or `Example <[email protected]>`, on a verified domain of the project. Without it, the email goes out from the project's default sender, or from its only verified sender when it has no default.
+ * @maxLength 1024
+ */
+ from?: string
}
export interface SendTransactionalEmailResponseApi {
diff --git a/products/messaging/frontend/generated/api.ts b/products/messaging/frontend/generated/api.ts
index fa4ab62a0374..3e3de191036a 100644
--- a/products/messaging/frontend/generated/api.ts
+++ b/products/messaging/frontend/generated/api.ts
@@ -109,7 +109,7 @@ export const getMessagingSendEmailCreateUrl = (projectId: string) => {
}
/**
- * Send one transactional email to one recipient from the template named in `template_id`. The template must be made transactional first. `message_data` fills the template's `{{ variables.* }}` placeholders. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice. Needs the `transactional_email:write` scope. A key with `hog_flow:write` also works, but that scope reaches the rest of Workflows too.
+ * 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. Needs the `transactional_email:write` scope. A key with `hog_flow:write` also works, but that scope reaches the rest of Workflows too.
* @summary Send a transactional email
*/
export const messagingSendEmailCreate = async (
diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.ts
index 253eb055b837..1177986e0f31 100644
--- a/products/messaging/frontend/generated/api.zod.ts
+++ b/products/messaging/frontend/generated/api.zod.ts
@@ -37,11 +37,18 @@ export const MessagingPreferencesCreateBody = /* @__PURE__ */ zod.object({
})
/**
- * Send one transactional email to one recipient from the template named in `template_id`. The template must be made transactional first. `message_data` fills the template's `{{ variables.* }}` placeholders. Transactional emails skip opt-outs and frequency caps. Send an `Idempotency-Key` header to retry safely without sending the email twice. Needs the `transactional_email:write` scope. A key with `hog_flow:write` also works, but that scope reaches the rest of Workflows too.
+ * 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. Needs the `transactional_email:write` scope. A key with `hog_flow:write` also works, but that scope reaches the rest of Workflows too.
* @summary Send a transactional email
*/
+export const messagingSendEmailCreateBodyTemplateKeyMax = 400
+
+export const messagingSendEmailCreateBodyTemplateKeyRegExp = new RegExp('^[a-zA-Z0-9_-]+$')
export const messagingSendEmailCreateBodyDistinctIdMax = 400
+export const messagingSendEmailCreateBodyReplyToMax = 10
+
+export const messagingSendEmailCreateBodyFromMax = 1024
+
export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({
to: zod.email().describe('Email address of the recipient.'),
message_data: zod
@@ -52,7 +59,18 @@ export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({
),
template_id: zod
.uuid()
- .describe('ID of the email template to send. The template must be made transactional first.'),
+ .optional()
+ .describe(
+ 'ID of the email template to send. The template must be made transactional first. Send either `template_id` or `template_key`.'
+ ),
+ template_key: zod
+ .string()
+ .max(messagingSendEmailCreateBodyTemplateKeyMax)
+ .regex(messagingSendEmailCreateBodyTemplateKeyRegExp)
+ .optional()
+ .describe(
+ 'Names an email whose content your code rendered, such as `order-shipped`, 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.'
+ ),
distinct_id: zod
.string()
.max(messagingSendEmailCreateBodyDistinctIdMax)
@@ -60,6 +78,32 @@ export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({
.describe(
"Distinct ID of the recipient's person. The email's engagement events (sent, delivered, opened, clicked, bounced) and the send itself are recorded against that person. Defaults to the recipient's email address. The template can't read the person's properties, so pass everything it needs in `message_data`."
),
+ subject: zod.string().optional().describe('Subject of the email your code rendered.'),
+ html: zod.string().optional().describe('HTML body of the email your code rendered, at most 5 MiB as UTF-8.'),
+ text: zod
+ .string()
+ .optional()
+ .describe(
+ 'Plain text body of the email your code rendered, at most 5 MiB as UTF-8. Without it, PostHog derives the text from `html`.'
+ ),
+ reply_to: zod
+ .array(zod.email())
+ .max(messagingSendEmailCreateBodyReplyToMax)
+ .optional()
+ .describe('Addresses replies to the email your code rendered go to.'),
+ 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.'
+ ),
+ from: zod
+ .string()
+ .max(messagingSendEmailCreateBodyFromMax)
+ .optional()
+ .describe(
+ "Sender of the email your code rendered, as `[email protected]` or `Example <[email protected]>`, on a verified domain of the project. Without it, the email goes out from the project's default sender, or from its only verified sender when it has no default."
+ ),
})
export const messagingCategoriesCreateBodyKeyMax = 64
diff --git a/products/workflows/backend/facade/contracts.py b/products/workflows/backend/facade/contracts.py
index 3ef7f57ba67c..a5aeb0397ae4 100644
--- a/products/workflows/backend/facade/contracts.py
+++ b/products/workflows/backend/facade/contracts.py
@@ -681,6 +681,8 @@ class WorkflowRef:
has_email_step: bool
+EMAIL_FROM_CODE_FLAG: Final[str] = "workflows-email-from-code"
+
# Engagement tracking and message assets key on this id, so it stays stable across versions.
TRANSACTIONAL_EMAIL_ACTION_ID: Final[str] = "transactional_email"
@@ -710,6 +712,10 @@ class TransactionalEmailSenderUnavailable(Exception):
"""No verified email sender: neither the requested one nor the project's default."""
+class TransactionalEmailSenderRequired(Exception):
+ """The project has several verified email senders and no default, so the send has to name one."""
+
+
class TransactionalEmailContentInvalid(Exception):
"""The content has no subject or no body, so the workflow could not send it."""
diff --git a/products/workflows/backend/facade/enums.py b/products/workflows/backend/facade/enums.py
index 4710d68269b2..7b38ec2f132d 100644
--- a/products/workflows/backend/facade/enums.py
+++ b/products/workflows/backend/facade/enums.py
@@ -103,6 +103,7 @@ class HogFlowOriginProduct(LabeledStrEnum):
LOOPS = "loops", "Loops"
BROADCASTS = "broadcasts", "Broadcasts"
TRANSACTIONAL_EMAILS = "transactional_emails", "Transactional emails"
+ TRANSACTIONAL_EMAIL_KEYS = "transactional_email_keys", "Transactional email keys"
class HogFlowEmailSendingPausedBy(LabeledStrEnum):
diff --git a/products/workflows/backend/facade/transactional_emails.py b/products/workflows/backend/facade/transactional_emails.py
index 7d8a8c4f4a47..ca98930e5bf2 100644
--- a/products/workflows/backend/facade/transactional_emails.py
+++ b/products/workflows/backend/facade/transactional_emails.py
@@ -1,22 +1,30 @@
"""Transactional emails: a message template made sendable over the API, backed by a one-step workflow."""
from products.workflows.backend.facade.contracts import (
+ EMAIL_FROM_CODE_FLAG,
TransactionalEmailContent,
TransactionalEmailContentInvalid,
+ TransactionalEmailSenderRequired,
TransactionalEmailSenderUnavailable,
WorkflowNotFound,
)
from products.workflows.backend.services.transactional_email_workflows import (
+ code_send_sender_id,
+ create_code_email_workflow,
create_transactional_email_workflow,
resolve_transactional_email_sender,
update_transactional_email_workflow,
)
__all__ = [
+ "EMAIL_FROM_CODE_FLAG",
"TransactionalEmailContent",
"TransactionalEmailContentInvalid",
+ "TransactionalEmailSenderRequired",
"TransactionalEmailSenderUnavailable",
"WorkflowNotFound",
+ "code_send_sender_id",
+ "create_code_email_workflow",
"create_transactional_email_workflow",
"resolve_transactional_email_sender",
"update_transactional_email_workflow",
diff --git a/products/workflows/backend/presentation/views/hog_flow.py b/products/workflows/backend/presentation/views/hog_flow.py
index af4e8d931a26..c041ffabee48 100644
--- a/products/workflows/backend/presentation/views/hog_flow.py
+++ b/products/workflows/backend/presentation/views/hog_flow.py
@@ -185,6 +185,7 @@ from products.workflows.backend.facade.broadcast_conversion import (
)
from products.workflows.backend.facade.content import DRAFT_CONTENT_FIELDS, deep_merge, snapshot_content
from products.workflows.backend.facade.contracts import (
+ EMAIL_FROM_CODE_FLAG,
EmailDesignRenderFailed,
EmailDesignRenderingNotConfigured,
StaffPausedError,
@@ -393,6 +394,22 @@ def _cohort_conditions_rolled_out(user: Any, organization_id: str) -> bool:
return False
+LISTED_ORIGIN_PRODUCTS: list[str] = [
+ origin for origin in HogFlowOriginProduct.values if origin != HogFlowOriginProduct.TRANSACTIONAL_EMAIL_KEYS
+]
+
+
+def _code_sends_rolled_out(team: Any) -> bool:
+ organization_id = str(team.organization_id)
+ return feature_enabled_or_false(
+ EMAIL_FROM_CODE_FLAG,
+ str(team.uuid),
+ groups={"organization": organization_id},
+ group_properties={"organization": {"id": organization_id}},
+ send_feature_flag_events=False,
+ )
+
+
def _authored_condition(condition: Optional[dict]) -> Optional[dict]:
"""The parts of a wait condition a person actually wrote, with compiler output dropped."""
if not isinstance(condition, dict):
@@ -3346,7 +3363,8 @@ class HogFlowSerializer(HogFlowMinimalSerializer):
required=False,
allow_null=True,
help_text="Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when "
- "creating a workflow. Filter the list with `?origin_product=`.",
+ "creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. "
+ "Filter the list with `?origin_product=`.",
)
source_record = serializers.RegexField(
r"^[a-z_]+:[A-Za-z0-9_-]+$",
@@ -3724,6 +3742,11 @@ class HogFlowSerializer(HogFlowMinimalSerializer):
"last_run",
]
+ def validate_origin_product(self, value: str | None) -> str | None:
+ if value == HogFlowOriginProduct.TRANSACTIONAL_EMAIL_KEYS:
+ raise serializers.ValidationError("A code send key's workflow is made by its first send.")
+ return value
+
def validate(self, data):
instance = cast(Optional[WorkflowEditState], self.instance)
is_draft = self.context.get("is_draft")
@@ -4999,7 +5022,7 @@ class HogFlowVersionMetricsRequestSerializer(AppMetricsRequestSerializer):
OpenApiParameter(
"origin_product",
OpenApiTypes.STR,
- enum=HogFlowOriginProduct.values,
+ enum=LISTED_ORIGIN_PRODUCTS,
description="Filter to workflows owned by a product surface, e.g. `loops` for Desktop loops.",
),
OpenApiParameter(
@@ -5311,10 +5334,8 @@ class HogFlowViewSet(
)
origin_product = params.get("origin_product")
- if origin_product and origin_product not in HogFlowOriginProduct.values:
- raise exceptions.ValidationError(
- {"origin_product": f"Must be one of: {', '.join(HogFlowOriginProduct.values)}"}
- )
+ if origin_product and origin_product not in LISTED_ORIGIN_PRODUCTS:
+ raise exceptions.ValidationError({"origin_product": f"Must be one of: {', '.join(LISTED_ORIGIN_PRODUCTS)}"})
trigger = self._trigger_filter()
tags = self._tags_filter()
@@ -5456,7 +5477,6 @@ class HogFlowViewSet(
`person:read` and `group:read` on top of `hog_flow:write`.
"""
hog_flow = self._workflow_ref()
-
serializer = HogInvocationRerunRequestSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
self._require_replay_vision_caller_access(request, self._edit_state().actions)
@@ -5470,7 +5490,7 @@ class HogFlowViewSet(
team_id=self.team_id,
function_kind="hog_flow",
function_id=str(hog_flow.id),
- payload=serializer.data,
+ payload={**serializer.data, "replay_code_sends": _code_sends_rolled_out(self.team)},
)
if res.status_code != 200:
diff --git a/products/workflows/backend/services/hog_flow_reads.py b/products/workflows/backend/services/hog_flow_reads.py
index 9864f9024efd..f4f5510d038f 100644
--- a/products/workflows/backend/services/hog_flow_reads.py
+++ b/products/workflows/backend/services/hog_flow_reads.py
@@ -236,6 +236,7 @@ def _list_queryset(
) -> QuerySet:
queryset: QuerySet = (
HogFlow.objects.filter(team_id=team_id)
+ .exclude(origin_product__in=HIDDEN_ORIGIN_PRODUCTS)
.select_related("created_by")
# _to_workflow reads prefetched_tags, so a page costs one tag query rather than one per row.
.prefetch_related(
@@ -417,6 +418,7 @@ OWNED_WORKFLOW_TYPES: Final[dict[str, str]] = {
"broadcast": HogFlow.OriginProduct.BROADCASTS,
"transactional_email": HogFlow.OriginProduct.TRANSACTIONAL_EMAILS,
}
+HIDDEN_ORIGIN_PRODUCTS: Final[tuple[str, ...]] = (HogFlow.OriginProduct.TRANSACTIONAL_EMAIL_KEYS,)
def workflow_type_q(requested: set[str]) -> Q:
@@ -428,7 +430,7 @@ def workflow_type_q(requested: set[str]) -> Q:
messaging = Q()
for action_type in MESSAGING_ACTION_TYPES:
messaging |= Q(actions__contains=[{"type": action_type}])
- unowned = ~Q(origin_product__in=list(OWNED_WORKFLOW_TYPES.values()))
+ unowned = ~Q(origin_product__in=[*OWNED_WORKFLOW_TYPES.values(), *HIDDEN_ORIGIN_PRODUCTS])
if behavioural == {"messaging", "automation"}:
return owned | unowned
return owned | (unowned & (messaging if behavioural == {"messaging"} else ~messaging))
diff --git a/products/workflows/backend/services/transactional_email_workflows.py b/products/workflows/backend/services/transactional_email_workflows.py
index 5204bfbb220c..4f0094c6fe1c 100644
--- a/products/workflows/backend/services/transactional_email_workflows.py
+++ b/products/workflows/backend/services/transactional_email_workflows.py
@@ -14,6 +14,7 @@ from products.workflows.backend.facade.contracts import (
TRANSACTIONAL_EMAIL_ACTION_ID,
TransactionalEmailContent,
TransactionalEmailContentInvalid,
+ TransactionalEmailSenderRequired,
TransactionalEmailSenderUnavailable,
WorkflowNotFound,
)
@@ -30,7 +31,49 @@ EXIT_ACTION_ID = "exit_node"
RECIPIENT_EXPRESSION = "{{ event.properties.to | raw }}"
+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]:
+ return _actions(
+ name=content.name,
+ step_config={
+ **_template_provenance(content),
+ "message_category_id": str(content.message_category_id) if content.message_category_id else None,
+ "sensitive": content.sensitive,
+ },
+ email={
+ "from": {
+ "integrationId": from_integration_id,
+ **({"email": content.from_email} if content.from_email else {}),
+ **({"name": content.from_name} if content.from_name else {}),
+ },
+ "replyTo": content.reply_to,
+ "subject": content.subject,
+ "preheader": content.preheader,
+ "text": content.text,
+ "html": content.html,
+ },
+ )
+
+
+def code_email_actions(key: str) -> list[dict]:
+ return _actions(
+ name=key,
+ step_config={"template_key": key, "message_category_id": None, "sensitive": True},
+ email={
+ "from": {"integrationId": None},
+ "replyTo": "",
+ "subject": "",
+ "preheader": "",
+ "text": "",
+ "html": "",
+ },
+ )
+
+
+def _actions(*, name: str, step_config: dict, email: dict) -> list[dict]:
return [
{
"id": TRIGGER_ACTION_ID,
@@ -41,37 +84,20 @@ def transactional_email_actions(content: TransactionalEmailContent, from_integra
},
{
"id": TRANSACTIONAL_EMAIL_ACTION_ID,
- "name": content.name,
+ "name": name,
"description": "",
"type": "function_email",
# Nothing comes after the email, so a failed send must fail the run.
"on_error": "abort",
"config": {
"template_id": "template-email",
- # Provenance only: the body below is set, so a save never re-reads the template.
- "template_uuid": str(content.message_template_id),
- "message_category_id": str(content.message_category_id) if content.message_category_id else None,
+ **step_config,
# Puts the send on the email queue's fast lane and skips marketing opt-outs.
"message_category_type": "transactional",
- "sensitive": content.sensitive,
"inputs": {
"email": {
"templating": "liquid",
- "value": {
- "to": {"email": RECIPIENT_EXPRESSION, "name": ""},
- "from": {
- "integrationId": from_integration_id,
- **({"email": content.from_email} if content.from_email else {}),
- **({"name": content.from_name} if content.from_name else {}),
- },
- "replyTo": content.reply_to,
- "cc": "",
- "bcc": "",
- "subject": content.subject,
- "preheader": content.preheader,
- "text": content.text,
- "html": content.html,
- },
+ "value": {"to": {"email": RECIPIENT_EXPRESSION, "name": ""}, "cc": "", "bcc": "", **email},
}
},
},
@@ -89,9 +115,12 @@ def transactional_email_actions(content: TransactionalEmailContent, from_integra
def _content_fields(content: TransactionalEmailContent, from_integration_id: int) -> dict:
if not content.subject or not (content.html or content.text):
raise TransactionalEmailContentInvalid()
- actions = transactional_email_actions(content, from_integration_id)
+ return _flow_fields(content.name, transactional_email_actions(content, from_integration_id))
+
+
+def _flow_fields(name: str, actions: list[dict]) -> dict:
return {
- "name": content.name,
+ "name": name,
"actions": actions,
"edges": [
{"from": TRIGGER_ACTION_ID, "to": TRANSACTIONAL_EMAIL_ACTION_ID, "type": "continue"},
@@ -103,13 +132,17 @@ def _content_fields(content: TransactionalEmailContent, from_integration_id: int
}
-def resolve_transactional_email_sender(team_id: int, requested_id: int | None) -> int:
- """The requested sender, or the project's default when none is requested. Raise when it isn't verified."""
- sender_id = requested_id or (
+def _default_sender_id(team_id: int) -> int | None:
+ return (
TeamWorkflowsConfig.objects.filter(team_id=team_id)
.values_list("default_email_integration_id", flat=True)
.first()
)
+
+
+def resolve_transactional_email_sender(team_id: int, requested_id: int | None) -> int:
+ """The requested sender, or the project's default when none is requested. Raise when it isn't verified."""
+ sender_id = requested_id or _default_sender_id(team_id)
sender = None
if sender_id:
try:
@@ -121,6 +154,43 @@ def resolve_transactional_email_sender(team_id: int, requested_id: int | None) -
return sender.id
+def _sender_without_address(team_id: int) -> int:
+ if _default_sender_id(team_id) is not None:
+ return resolve_transactional_email_sender(team_id, None)
+ verified = [
+ sender.id for sender in IntegrationManager.email.credentials.list(team_id) if sender.config.get("verified")
+ ]
+ if len(verified) > 1:
+ raise TransactionalEmailSenderRequired()
+ if not verified:
+ raise TransactionalEmailSenderUnavailable()
+ return verified[0]
+
+
+def _sender_on_domain(team_id: int, email: str) -> int:
+ address = email.lower()
+ domain = address.rpartition("@")[2]
+ on_domain: list[int] = []
+ for sender in IntegrationManager.email.credentials.list(team_id):
+ if not sender.config.get("verified"):
+ continue
+ own = str(sender.config.get("email") or sender.integration_id or "").lower()
+ if own == address:
+ return sender.id
+ if str(sender.config.get("domain") or own.rpartition("@")[2]).lower() == domain:
+ on_domain.append(sender.id)
+ if not on_domain:
+ raise TransactionalEmailSenderUnavailable()
+ default_sender_id = _default_sender_id(team_id)
+ if default_sender_id is not None and default_sender_id in on_domain:
+ return default_sender_id
+ return on_domain[0]
+
+
+def code_send_sender_id(*, team_id: int, email: str | None) -> int:
+ return _sender_without_address(team_id) if email is None else _sender_on_domain(team_id, email)
+
+
def _current_sender(flow: HogFlow) -> int | None:
# The email step is missing when someone edited the workflow directly. The update writes it back.
email = next((action for action in flow.actions if action.get("id") == TRANSACTIONAL_EMAIL_ACTION_ID), None)
@@ -178,3 +248,18 @@ def update_transactional_email_workflow(
validated_status=flow.status,
keeps_live_sensitivity=False,
)
+
+
+@with_team_scope()
+def create_code_email_workflow(*, team_id: int, key: str) -> UUID:
+ result = create_workflow(
+ team_id=team_id,
+ user_id=None,
+ validated_data={
+ **_flow_fields(key, code_email_actions(key)),
+ "status": HogFlow.State.ACTIVE,
+ "origin_product": HogFlowOriginProduct.TRANSACTIONAL_EMAIL_KEYS,
+ "exit_condition": "exit_only_at_end",
+ },
+ )
+ return UUID(str(result.current["id"]))
diff --git a/products/workflows/backend/test/test_workflow_setup_status.py b/products/workflows/backend/test/test_workflow_setup_status.py
index 295020c053a0..7260369a2a4a 100644
--- a/products/workflows/backend/test/test_workflow_setup_status.py
+++ b/products/workflows/backend/test/test_workflow_setup_status.py
@@ -99,6 +99,11 @@ class TestWorkflowSetupStatusAPI(APIBaseTest):
("a Slack-only automation", {"action_type": "function"}, False),
("an archived email workflow", {"action_type": "function_email", "status": "archived"}, False),
("a broadcast", {"action_type": "function_email", "origin_product": "broadcasts"}, False),
+ (
+ "a code send key's hidden workflow",
+ {"action_type": "function_email", "status": "active", "origin_product": "transactional_email_keys"},
+ False,
+ ),
]
)
def test_first_workflow_counts_only_live_messaging_workflows(self, _name, workflow, expected) -> None:
diff --git a/products/workflows/backend/tests/api/test_hog_flow.py b/products/workflows/backend/tests/api/test_hog_flow.py
index 01b0c3b3993d..6b57a5e13c61 100644
--- a/products/workflows/backend/tests/api/test_hog_flow.py
+++ b/products/workflows/backend/tests/api/test_hog_flow.py
@@ -62,6 +62,8 @@ from products.replay_vision.backend.models.replay_scanner import ReplayScanner
from products.replay_vision.backend.tests.helpers import create_experiment
from products.skills.backend.models.skills import LLMSkill
from products.tasks.backend.facade.contracts import WorkflowLastRunDTO
+from products.workflows.backend.facade.enums import HogFlowOriginProduct
+from products.workflows.backend.facade.transactional_emails import create_code_email_workflow
from products.workflows.backend.facade.writes import update_workflow
from products.workflows.backend.models.hog_flow.hog_flow import SUPPORTED_ACTION_TYPES, HogFlow
from products.workflows.backend.models.hog_flow_batch_job.hog_flow_batch_job import HogFlowBatchJob
@@ -882,6 +884,12 @@ class TestHogFlowAPI(APIBaseTest):
hog_flow, _ = self._create_hog_flow_with_action(
{"template_id": "template-webhook", "inputs": {"url": {"value": "https://example.com"}}}
)
+ response = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows", {**hog_flow, "origin_product": "transactional_email_keys"}
+ )
+ assert response.status_code == 400, response.json()
+ assert response.json()["attr"] == "origin_product"
+
response = self.client.post(f"/api/projects/{self.team.id}/hog_flows", {**hog_flow, "origin_product": "loops"})
assert response.status_code == 201, response.json()
flow_id = response.json()["id"]
@@ -8430,6 +8438,43 @@ class TestReplayVisionActionValidation(APIBaseTest):
assert "session recordings" in response.json()["detail"], response.json()
rerun.assert_not_called()
+ @parameterized.expand(
+ [
+ (f"{origin}_{'flag_on' if flag_on else 'flag_off'}", origin, flag_on)
+ for origin in ("code_key", "template")
+ for flag_on in (False, True)
+ ]
+ )
+ def test_a_rerun_replays_code_sends_only_while_the_code_send_flag_is_on(self, _name, origin, flag_on) -> None:
+ if origin == "code_key":
+ flow_id = create_code_email_workflow(team_id=self.team.id, key="welcome")
+ else:
+ flow_id = HogFlow.objects.create(
+ team=self.team,
+ name="Welcome template",
+ status="active",
+ trigger={"type": "event", "filters": {}},
+ actions=[_TRIGGER],
+ origin_product=HogFlowOriginProduct.TRANSACTIONAL_EMAILS,
+ ).id
+
+ with (
+ patch(
+ "products.workflows.backend.presentation.views.hog_flow.feature_enabled_or_false",
+ side_effect=lambda key, *args, **kwargs: flag_on and key == "workflows-email-from-code",
+ ),
+ patch("products.workflows.backend.presentation.views.hog_flow.rerun_hog_invocations") as rerun,
+ ):
+ rerun.return_value = MagicMock(status_code=200, json=lambda: {"queued_count": 1, "skipped_count": 0})
+ response = self.client.post(
+ f"/api/projects/{self.team.id}/hog_flows/{flow_id}/rerun/",
+ {"filter": {"window_start": "2026-10-13T00:00:00Z", "window_end": "2026-10-14T00:00:00Z"}},
+ format="json",
+ )
+
+ assert response.status_code == status.HTTP_200_OK, response.json()
+ assert rerun.call_args.kwargs["payload"]["replay_code_sends"] is flag_on
+
def test_a_variables_only_edit_is_checked_against_the_staged_draft_too(self) -> None:
self._enable_access_control()
AccessControl.objects.create(team=self.team, resource="session_recording", access_level="none")
diff --git a/products/workflows/frontend/generated/api.schemas.ts b/products/workflows/frontend/generated/api.schemas.ts
index d6138097e788..47c9d6af1c70 100644
--- a/products/workflows/frontend/generated/api.schemas.ts
+++ b/products/workflows/frontend/generated/api.schemas.ts
@@ -415,6 +415,7 @@ export const HogFlowStateEnumApi = {
* * `loops` - Loops
* * `broadcasts` - Broadcasts
* * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys
*/
export type HogFlowOriginProductEnumApi = (typeof HogFlowOriginProductEnumApi)[keyof typeof HogFlowOriginProductEnumApi]
@@ -422,6 +423,7 @@ export const HogFlowOriginProductEnumApi = {
Loops: 'loops',
Broadcasts: 'broadcasts',
TransactionalEmails: 'transactional_emails',
+ TransactionalEmailKeys: 'transactional_email_keys',
} as const
/**
@@ -768,11 +770,12 @@ export interface HogFlowApi {
* * `active` - Active
* * `archived` - Archived */
status?: HogFlowStateEnumApi
- /** Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.
+ /** Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
origin_product?: HogFlowOriginProductEnumApi | null
/**
* The record another product's entry point started this workflow from, as '<kind>:<id>'. Set only when creating a workflow. Filter the list with `?source_record=`.
@@ -887,7 +890,8 @@ export interface HogFlowUpdateApi {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product: HogFlowOriginProductEnumApi | null
readonly created_at: string
readonly created_by: UserBasicApi
@@ -995,7 +999,8 @@ export interface PatchedHogFlowUpdateApi {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product?: HogFlowOriginProductEnumApi | null
readonly created_at?: string
readonly created_by?: UserBasicApi
@@ -1230,7 +1235,8 @@ export interface HogFlowConvertedToBroadcastApi {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product: HogFlowOriginProductEnumApi
}
@@ -2332,7 +2338,8 @@ export interface SendCalendarFlowApi {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product: HogFlowOriginProductEnumApi | null
/** User who created the workflow. */
readonly created_by: UserBasicApi | null
diff --git a/products/workflows/frontend/generated/api.zod.ts b/products/workflows/frontend/generated/api.zod.ts
index 9c32bb91600c..11ef526d918a 100644
--- a/products/workflows/frontend/generated/api.zod.ts
+++ b/products/workflows/frontend/generated/api.zod.ts
@@ -566,15 +566,15 @@ export const HogFlowsCreateBody = /* @__PURE__ */ zod
origin_product: zod
.union([
zod
- .enum(['loops', 'broadcasts', 'transactional_emails'])
+ .enum(['loops', 'broadcasts', 'transactional_emails', 'transactional_email_keys'])
.describe(
- '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
zod.null(),
])
.optional()
.describe(
- 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
source_record: zod
.string()
@@ -2022,15 +2022,15 @@ export const HogFlowsInvocationsCreateBody = /* @__PURE__ */ zod.object({
origin_product: zod
.union([
zod
- .enum(['loops', 'broadcasts', 'transactional_emails'])
+ .enum(['loops', 'broadcasts', 'transactional_emails', 'transactional_email_keys'])
.describe(
- '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
zod.null(),
])
.optional()
.describe(
- 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
source_record: zod
.string()
@@ -2946,15 +2946,15 @@ export const HogFlowsBulkDeleteCreateBody = /* @__PURE__ */ zod
origin_product: zod
.union([
zod
- .enum(['loops', 'broadcasts', 'transactional_emails'])
+ .enum(['loops', 'broadcasts', 'transactional_emails', 'transactional_email_keys'])
.describe(
- '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
zod.null(),
])
.optional()
.describe(
- 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
source_record: zod
.string()
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 6a067f92f516..448bba577c83 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -51856,6 +51856,7 @@ export namespace Schemas {
* * `loops` - Loops
* * `broadcasts` - Broadcasts
* * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys
*/
export type HogFlowOriginProductEnum = typeof HogFlowOriginProductEnum[keyof typeof HogFlowOriginProductEnum];
@@ -51864,6 +51865,7 @@ export namespace Schemas {
Loops: 'loops',
Broadcasts: 'broadcasts',
TransactionalEmails: 'transactional_emails',
+ TransactionalEmailKeys: 'transactional_email_keys',
} as const;
export interface HogFlowMasking {
@@ -52184,11 +52186,12 @@ export namespace Schemas {
* * `active` - Active
* * `archived` - Archived */
status?: HogFlowStateEnum;
- /** Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.
+ /** Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
origin_product?: HogFlowOriginProductEnum | null;
/**
* The record another product's entry point started this workflow from, as '<kind>:<id>'. Set only when creating a workflow. Filter the list with `?source_record=`.
@@ -52342,7 +52345,8 @@ export namespace Schemas {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product: HogFlowOriginProductEnum;
}
@@ -52812,7 +52816,8 @@ export namespace Schemas {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product: HogFlowOriginProductEnum | null;
readonly created_at: string;
readonly created_by: UserBasic;
@@ -82216,7 +82221,8 @@ export namespace Schemas {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product?: HogFlowOriginProductEnum | null;
readonly created_at?: string;
readonly created_by?: UserBasic;
@@ -104014,7 +104020,8 @@ export namespace Schemas {
*
* * `loops` - Loops
* * `broadcasts` - Broadcasts
- * * `transactional_emails` - Transactional emails */
+ * * `transactional_emails` - Transactional emails
+ * * `transactional_email_keys` - Transactional email keys */
readonly origin_product: HogFlowOriginProductEnum | null;
/** User who created the workflow. */
readonly created_by: UserBasic | null;
@@ -104068,14 +104075,38 @@ export namespace Schemas {
to: string;
/** Data for the template's Liquid placeholders, available as `variables`. For example `{"reset_link": "https://..."}` fills `{{ variables.reset_link }}`. */
message_data?: SendEmailMessageData;
- /** ID of the email template to send. The template must be made transactional first. */
- template_id: string;
+ /** ID of the email template to send. The template must be made transactional first. Send either `template_id` or `template_key`. */
+ template_id?: string;
+ /**
+ * Names an email whose content your code rendered, such as `order-shipped`, 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.
+ * @maxLength 400
+ * @pattern ^[a-zA-Z0-9_-]+$
+ */
+ template_key?: string;
/**
* Distinct ID of the recipient's person. The email's engagement events (sent, delivered, opened, clicked, bounced) and the send itself are recorded against that person. Defaults to the recipient's email address. The template can't read the person's properties, so pass everything it needs in `message_data`.
* @maxLength 400
* @nullable
*/
distinct_id?: string | null;
+ /** Subject of the email your code rendered. */
+ subject?: string;
+ /** HTML body of the email your code rendered, at most 5 MiB as UTF-8. */
+ html?: string;
+ /** Plain text body of the email your code rendered, at most 5 MiB as UTF-8. Without it, PostHog derives the text from `html`. */
+ text?: string;
+ /**
+ * Addresses replies to the email your code rendered go to.
+ * @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. */
+ capture_engagement?: boolean;
+ /**
+ * Sender of the email your code rendered, as `[email protected]` or `Example <[email protected]>`, on a verified domain of the project. Without it, the email goes out from the project's default sender, or from its only verified sender when it has no default.
+ * @maxLength 1024
+ */
+ from?: string;
}
/**
diff --git a/services/mcp/src/generated/workflows/api.ts b/services/mcp/src/generated/workflows/api.ts
index 16f69ede9aff..67bd5962f3c0 100644
--- a/services/mcp/src/generated/workflows/api.ts
+++ b/services/mcp/src/generated/workflows/api.ts
@@ -139,15 +139,15 @@ export const HogFlowsCreateBody = () => zod
origin_product: zod
.union([
zod
- .enum(['loops', 'broadcasts', 'transactional_emails'])
+ .enum(['loops', 'broadcasts', 'transactional_emails', 'transactional_email_keys'])
.describe(
- '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ '\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
zod.null(),
])
.optional()
.describe(
- 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails'
+ 'Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.\n\n\* `loops` - Loops\n\* `broadcasts` - Broadcasts\n\* `transactional_emails` - Transactional emails\n\* `transactional_email_keys` - Transactional email keys'
),
source_record: zod
.string()
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/broadcasts-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/broadcasts-create.json
index e13e864605e4..c0019b0c47b2 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/broadcasts-create.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/broadcasts-create.json
@@ -544,15 +544,15 @@
"origin_product": {
"anyOf": [
{
- "description": "* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails",
- "enum": ["loops", "broadcasts", "transactional_emails"],
+ "description": "* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails\n* `transactional_email_keys` - Transactional email keys",
+ "enum": ["loops", "broadcasts", "transactional_emails", "transactional_email_keys"],
"type": "string"
},
{
"type": "null"
}
],
- "description": "Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.\n\n* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails"
+ "description": "Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.\n\n* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails\n* `transactional_email_keys` - Transactional email keys"
},
"source_record": {
"anyOf": [
diff --git a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-create.json b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-create.json
index e13e864605e4..c0019b0c47b2 100644
--- a/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-create.json
+++ b/services/mcp/tests/unit/__snapshots__/tool-schemas/workflows-create.json
@@ -544,15 +544,15 @@
"origin_product": {
"anyOf": [
{
- "description": "* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails",
- "enum": ["loops", "broadcasts", "transactional_emails"],
+ "description": "* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails\n* `transactional_email_keys` - Transactional email keys",
+ "enum": ["loops", "broadcasts", "transactional_emails", "transactional_email_keys"],
"type": "string"
},
{
"type": "null"
}
],
- "description": "Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow. Filter the list with `?origin_product=`.\n\n* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails"
+ "description": "Product surface that owns this workflow (e.g. `loops` for Desktop loops). Set only when creating a workflow, and never to `transactional_email_keys`: the email send API sets that one. Filter the list with `?origin_product=`.\n\n* `loops` - Loops\n* `broadcasts` - Broadcasts\n* `transactional_emails` - Transactional emails\n* `transactional_email_keys` - Transactional email keys"
},
"source_record": {
"anyOf": [