: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(messaging): send cc, bcc and attachments on a code send (#127988)
Michael Reichenbach696240a1044a
diff --git a/products/messaging/backend/facade/contracts.py b/products/messaging/backend/facade/contracts.pyindex e9d1214523aa..09c8a1cbd802 100644--- a/products/messaging/backend/facade/contracts.py+++ b/products/messaging/backend/facade/contracts.py@@ -1,4 +1,4 @@-from dataclasses import dataclass+from dataclasses import dataclass, fieldfrom datetime import datetimefrom typing import Anyfrom uuid import UUID@@ -107,6 +107,22 @@ class NamedSenderNotVerified(SenderNotVerified):attr = "from"+class FieldNotAccepted(TransactionalEmailError):+ code = "field_not_accepted"++ def __init__(self, field: str) -> None:+ super().__init__(f"PostHog doesn't take `{field}` yet.")+ self.field = field+++@frozen+class EmailAttachment:+ filename: str+ content: str = field(repr=False)+ content_type: str | None = None+ content_id: str | None = None++class SenderRequired(TransactionalEmailError):code = "sender_required"@@ -132,6 +148,9 @@ class CodeEmail:sender: str | Nonereply_to: tuple[str, ...]capture_engagement: bool+ cc: tuple[str, ...] = ()+ bcc: tuple[str, ...] = ()+ attachments: tuple[EmailAttachment, ...] = ()class DeliveryUnavailable(Exception):diff --git a/products/messaging/backend/facade/transactional_email.py b/products/messaging/backend/facade/transactional_email.pyindex bed97b4009c2..6fdc9f48e367 100644--- a/products/messaging/backend/facade/transactional_email.py+++ b/products/messaging/backend/facade/transactional_email.py@@ -3,8 +3,10 @@from products.messaging.backend.facade.contracts import (CodeEmail,DeliveryUnavailable,+ EmailAttachment,EmailDeliveryStatus,EmailStatus,+ FieldNotAccepted,QueuedEmail,TransactionalEmailError,)@@ -33,6 +35,8 @@ __all__ = ["SENDER_ADDRESS_PATTERN","CodeEmail","DeliveryUnavailable",+ "FieldNotAccepted",+ "EmailAttachment","EmailDeliveryStatus","EmailStatus","QueuedEmail",diff --git a/products/messaging/backend/presentation/views/code_send_fields.py b/products/messaging/backend/presentation/views/code_send_fields.pynew file mode 100644index 000000000000..049850087deb--- /dev/null+++ b/products/messaging/backend/presentation/views/code_send_fields.py@@ -0,0 +1,274 @@+import re+import base64+from collections.abc import Mapping+from typing import Any++from drf_spectacular.utils import extend_schema_field+from rest_framework import serializers+from rest_framework.settings import api_settings++from posthog.dataclasses import frozen++from products.messaging.backend.facade.transactional_email import PIPELINE_ADDRESS_PATTERN++MAX_ADDRESSES_PER_FIELD = 10+MAX_ATTACHMENTS = 10+MAX_ATTACHMENTS_BYTES = 512 * 1024+MAX_FILENAME_LENGTH = 255+SES_ATTACHMENT_HEADER_MAX_LENGTH = 78+BLOCKED_ATTACHMENT_EXTENSIONS = frozenset(+ {+ "ade", "adp", "apk", "app", "appx", "appxbundle", "asp", "bas", "bat", "cab", "cer", "chm", "cmd", "com", "cpl",+ "crt", "csh", "der", "diagcab", "diagcfg", "diagpkg", "dll", "dmg", "ex", "ex_", "exe", "fxp", "gadget", "hlp",+ "hta", "img", "inf", "ins", "iso", "isp", "its", "jar", "jnlp", "js", "jse", "ksh", "lib", "lnk", "mad", "maf",+ "mag", "mam", "maq", "mar", "mas", "mat", "mau", "mav", "maw", "mda", "mdb", "mde", "mdt", "mdw", "mdz", "mjs",+ "msc", "msh", "msh1", "msh1xml", "msh2", "msh2xml", "mshxml", "msi", "msix", "msixbundle", "msp", "mst", "nsh",+ "ops", "pcd", "pif", "plg", "prf", "prg", "ps1", "ps1xml", "ps2", "ps2xml", "psc1", "psc2", "reg", "scf", "scr",+ "sct", "shb", "shs", "sys", "tmp", "url", "vb", "vbe", "vbs", "vhd", "vps", "vsmacros", "vss", "vst", "vsw",+ "vxd", "ws", "wsc", "wsf", "wsh", "xll", "xnk",+ }+) # fmt: skip+MIME_TYPE_WITHOUT_PARAMETERS = re.compile(+ r"[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}"+)+CONTROL_CHARACTERS = re.compile(r"[\x00-\x1f\x7f]")++ADDRESS_FIELDS = ("cc", "bcc")+CODE_SEND_EXTRA_FIELDS = (*ADDRESS_FIELDS, "attachments")+++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."+ )+++def _extension_as_windows_saves_it(filename: str) -> str | None:+ _, dot, extension = filename.rstrip(". ").rpartition(".")+ return extension.lower() if dot else None+++@extend_schema_field(+ {+ "oneOf": [+ {"type": "string", "format": "email"},+ {+ "type": "array",+ "items": {"type": "string", "format": "email"},+ "maxItems": MAX_ADDRESSES_PER_FIELD,+ },+ ]+ }+)+class AddressListField(serializers.ListField):+ def __init__(self, **kwargs: Any) -> None:+ super().__init__(+ child=serializers.EmailField(validators=[validate_pipeline_address]),+ max_length=MAX_ADDRESSES_PER_FIELD,+ error_messages={"max_length": "Send at most {max_length} addresses."},+ **kwargs,+ )++ def to_internal_value(self, data: Any) -> list[str]:+ return super().to_internal_value([data] if isinstance(data, str) else data)+++class EmailAttachmentSerializer(serializers.Serializer):+ filename = serializers.CharField(+ max_length=MAX_FILENAME_LENGTH,+ help_text="File name the recipient sees, such as `invoice.pdf`. No path and no line breaks. A file type "+ "mailbox providers block, such as `.exe`, is refused.",+ )+ content = serializers.CharField(+ trim_whitespace=False,+ help_text="The file's bytes as standard base64, without line breaks.",+ )+ content_type = serializers.CharField(+ required=False,+ max_length=SES_ATTACHMENT_HEADER_MAX_LENGTH,+ help_text="MIME type of the file, such as `application/pdf`. Without it, the type follows from the file name.",+ )+ content_id = serializers.CharField(+ required=False,+ max_length=SES_ATTACHMENT_HEADER_MAX_LENGTH,+ help_text="Content ID that the HTML body references as `cid:<content_id>` to show the file inline, such as "+ "`logo`. Without `<` or `>`.",+ )++ def to_internal_value(self, data: Any) -> dict[str, Any]:+ if isinstance(data, Mapping):+ unknown = next((key for key in sorted(data) if key not in self.fields), None)+ if unknown is not None:+ raise serializers.ValidationError(+ {unknown: "An attachment takes `filename`, `content`, `content_type` and `content_id`."},+ code="unknown_attachment_field",+ )+ return super().to_internal_value(data)++ def validate_filename(self, filename: str) -> str:+ if "/" in filename or "\\" in filename or CONTROL_CHARACTERS.search(filename):+ raise serializers.ValidationError(+ "Use a file name with no path separator and no line break.", code="unsafe_filename"+ )+ extension = _extension_as_windows_saves_it(filename)+ if extension in BLOCKED_ATTACHMENT_EXTENSIONS:+ raise serializers.ValidationError(+ f"Mailbox providers block `.{extension}` files.", code="blocked_file_type"+ )+ return filename++ def validate_content(self, content: str) -> str:+ if not _decoded_size(content):+ raise serializers.ValidationError("The content is empty.", code="empty_attachment")+ return content++ def validate_content_type(self, content_type: str) -> str:+ if not MIME_TYPE_WITHOUT_PARAMETERS.fullmatch(content_type):+ raise serializers.ValidationError("Enter a MIME type, such as `application/pdf`.", code="not_mime_type")+ return content_type++ def validate_content_id(self, content_id: str) -> str:+ if "<" in content_id or ">" in content_id or CONTROL_CHARACTERS.search(content_id):+ raise serializers.ValidationError(+ "Send the content ID without `<`, `>` or line breaks.", code="unsafe_content_id"+ )+ return content_id+++def _decoded_size(content: str) -> int:+ try:+ return len(base64.b64decode(content, validate=True))+ except ValueError:+ raise serializers.ValidationError("The content isn't valid base64.", code="not_base64") from None+++class AttachmentListField(serializers.ListField):+ def __init__(self, **kwargs: Any) -> None:+ super().__init__(+ child=EmailAttachmentSerializer(),+ max_length=MAX_ATTACHMENTS,+ error_messages={"max_length": "Send at most {max_length} attachments."},+ **kwargs,+ )++ def to_internal_value(self, data: Any) -> list[dict[str, str]]:+ attachments = super().to_internal_value(data)+ if sum(_decoded_size(attachment["content"]) for attachment in attachments) > MAX_ATTACHMENTS_BYTES:+ raise serializers.ValidationError(+ f"Send at most {MAX_ATTACHMENTS_BYTES // 1024} KB of attachments in total, counted after decoding.",+ code="attachments_too_large",+ )+ return attachments+++@frozen+class _Reason:+ why: str+ fix: str+++_ADDRESS_REASON = _Reason(+ why="PostHog sends a copy to every address in `cc` and `bcc`, so each one must be a single address.",+ fix="Send one address or a list of up to 10 bare addresses, such as `[email protected]`.",+)+_ATTACHMENT_REASON = _Reason(+ why="PostHog attaches each file as it is sent, so each one needs a file name and base64 content.",+ fix="Send each attachment as `{filename, content}`, with `content` in base64.",+)+_ATTACHMENT_LIMIT_REASON = _Reason(+ why="A transactional email has to arrive fast, and large attachments slow its delivery.",+ fix=f"Send at most {MAX_ATTACHMENTS} files and {MAX_ATTACHMENTS_BYTES // 1024} KB in total, or link to "+ "larger files from the email body.",+)+_COPY_LIMIT_REASON = _Reason(+ why="A transactional email goes to one recipient, with copies for a few others.",+ fix=f"Send at most {MAX_ADDRESSES_PER_FIELD} addresses in each of `cc` and `bcc`. To reach more people, send "+ "each one their own email.",+)+_HEADER_LENGTH_REASONS = {+ field: _Reason(+ why=f"PostHog puts `{field}` into the email's headers, which take at most {limit} characters for it.",+ fix=f"Shorten `{field}` to {limit} characters or fewer.",+ )+ for field, limit in (+ ("filename", MAX_FILENAME_LENGTH),+ ("content_type", SES_ATTACHMENT_HEADER_MAX_LENGTH),+ ("content_id", SES_ATTACHMENT_HEADER_MAX_LENGTH),+ )+}+_LIST_LIMIT_REASONS = {"cc": _COPY_LIMIT_REASON, "bcc": _COPY_LIMIT_REASON, "attachments": _ATTACHMENT_LIMIT_REASON}+_REASONS_BY_CODE = {+ "not_base64": _Reason(+ why="Attachment content travels as base64 text inside the JSON body.",+ fix="Encode the file as standard base64, without line breaks.",+ ),+ "empty_attachment": _Reason(+ why="An empty file gives the recipient nothing to open.", fix="Leave out the empty file."+ ),+ "blocked_file_type": _Reason(+ why="Mailbox providers refuse emails that carry files that can run code, so the email would bounce.",+ fix="Send a different file type, or link to the file from the email body.",+ ),+ "attachments_too_large": _ATTACHMENT_LIMIT_REASON,+ "unsafe_filename": _Reason(+ why="The file name goes into the email's headers, where a path or a line break could change the email.",+ fix="Send only the file name, such as `invoice.pdf`.",+ ),+ "not_mime_type": _Reason(+ why="The MIME type goes into the email's headers, so it must be a type and a subtype only.",+ fix="Send a type such as `application/pdf`, or leave `content_type` out.",+ ),+ "unsafe_content_id": _Reason(+ why="The Content-ID header wraps the ID in angle brackets, so brackets inside the ID break the `cid:` "+ "reference from the HTML.",+ fix="Send the bare ID, such as `logo`, and reference it as `cid:logo` in the HTML.",+ ),+ "field_not_accepted": _Reason(+ why="This PostHog version doesn't take the field yet, so it refused the email instead of sending it "+ "without it.",+ fix="Send the email without this field, or send it again once PostHog takes the field.",+ ),+ "template_key_only": _Reason(+ why="A send with `template_id` takes its recipients and content from the template.",+ fix="Send the email's content with `template_key`, or leave this field out.",+ ),+}+++def field_not_accepted_refusal(field: str) -> serializers.ValidationError:+ return serializers.ValidationError(+ {field: "PostHog doesn't take this field yet, so it didn't send the email."}, code="field_not_accepted"+ )+++def template_send_refusal(field: str) -> serializers.ValidationError:+ return serializers.ValidationError(+ {field: "Only a send with `template_key` takes this field."}, code="template_key_only"+ )+++def with_code_send_reason(body: dict[str, Any]) -> dict[str, Any]:+ path, code = (body.get("attr") or "").split("__"), str(body.get("code") or "")+ if body.get("type") != "validation_error" or (+ path[0] not in CODE_SEND_EXTRA_FIELDS and code != "field_not_accepted"+ ):+ return body+ if path[-1] == api_settings.NON_FIELD_ERRORS_KEY:+ path.pop()+ if code == "max_length" and len(path) == 1:+ reason = _LIST_LIMIT_REASONS[path[0]]+ elif code == "max_length" and path[-1] in _HEADER_LENGTH_REASONS:+ reason = _HEADER_LENGTH_REASONS[path[-1]]+ else:+ reason = _REASONS_BY_CODE.get(code, _ADDRESS_REASON if path[0] in ADDRESS_FIELDS else _ATTACHMENT_REASON)+ attr = "__".join(path)+ return {+ **body,+ "type": "invalid_request",+ "code": "invalid_request",+ "attr": attr,+ "why": reason.why,+ "fix": reason.fix,+ }diff --git a/products/messaging/backend/presentation/views/message_templates.py b/products/messaging/backend/presentation/views/message_templates.pyindex 146a98888f5a..8ecad7f50dc3 100644--- a/products/messaging/backend/presentation/views/message_templates.py+++ b/products/messaging/backend/presentation/views/message_templates.py@@ -61,11 +61,12 @@ 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,+ EmailAttachment,+ FieldNotAccepted,QueuedEmail,TransactionalEmailError,TransactionalEmailStage,@@ -81,6 +82,15 @@ from products.messaging.backend.facade.transactional_email import (sync_transactional_workflow,transactional_email_stage,)+from products.messaging.backend.presentation.views.code_send_fields import (+ CODE_SEND_EXTRA_FIELDS,+ AddressListField,+ AttachmentListField,+ field_not_accepted_refusal,+ template_send_refusal,+ validate_pipeline_address,+ with_code_send_reason,+)from products.messaging.backend.presentation.views.serializers import DesignOperationSerializerfrom products.notifications.backend.facade.api import publish_resource_editedfrom products.workflows.backend.facade.api import WorkflowAccessDenied, WorkflowNotFound@@ -425,16 +435,8 @@ 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(validators=[_validate_pipeline_address], 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,@@ -450,7 +452,16 @@ class SendTransactionalEmailSerializer(TransactionalEmailMessageSerializer):)-CODE_SEND_FIELDS = ("template_key", "subject", "html", "text", "from", "reply_to", "capture_engagement")+CODE_SEND_FIELDS = (+ "template_key",+ "subject",+ "html",+ "text",+ "from",+ "reply_to",+ "capture_engagement",+ *CODE_SEND_EXTRA_FIELDS,+)CODE_BODY_MAX_BYTES = 5 * 1024 * 1024@@ -496,12 +507,33 @@ class SendEmailSerializer(TransactionalEmailMessageSerializer):"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]),+ 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.",)+ cc = AddressListField(+ required=False,+ allow_null=True,+ help_text="Addresses that get a visible copy of the email your code rendered: one address, or a list of up "+ "to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with "+ "`template_id`, which refuses any address here.",+ )+ bcc = AddressListField(+ required=False,+ allow_null=True,+ help_text="Addresses that get a hidden copy of the email your code rendered: one address, or a list of up "+ "to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with "+ "`template_id`, which refuses any address here.",+ )+ attachments = AttachmentListField(+ required=False,+ allow_null=True,+ help_text="Files attached to the email your code rendered: up to 10, and at most 512 KB in total after "+ "decoding. File types mailbox providers block, such as `.exe`, are refused. Doesn't apply to a send with "+ "`template_id`, which refuses any file here.",+ )capture_engagement = serializers.BooleanField(required=False,help_text="Whether the engagement events (sent, delivered, opened, clicked, bounced) of the email your code "@@ -545,7 +577,13 @@ class SendEmailSerializer(TransactionalEmailMessageSerializer):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):+ if extra_field := next((field for field in CODE_SEND_EXTRA_FIELDS if data.get(field)), None):+ raise template_send_refusal(extra_field)+ for field in CODE_SEND_EXTRA_FIELDS:+ data.pop(field, None)+ if code_field := next(+ (field for field in CODE_SEND_FIELDS if field in sent and field not in CODE_SEND_EXTRA_FIELDS), None+ ):raise serializers.ValidationError({code_field: "Only a send with `template_key` takes this field."})return dataunknown = next((field for field in sorted(sent) if field not in self.fields), None)@@ -813,6 +851,9 @@ class TransactionalEmailSendMixin:try:queued = send(idempotency_key)outcome["outcome"] = "replayed" if queued.replayed else "queued"+ except FieldNotAccepted as e:+ outcome.update({"outcome": "rejected", "error_code": e.code})+ raise field_not_accepted_refusal(e.field) from Noneexcept TransactionalEmailError as e:outcome.update({"outcome": "rejected", "error_code": e.code})raise TransactionalEmailRejected(e)@@ -1211,6 +1252,12 @@ class MessagingSendViewSet(TransactionalEmailSendMixin, TeamAndOrgViewSetMixin,def get_throttles(self):return transactional_email_throttles()+ def handle_exception(self, exc: Exception) -> Response:+ response = super().handle_exception(exc)+ if isinstance(response.data, dict):+ response.data = with_code_send_reason(response.data)+ return response+@validated_request(SendEmailSerializer,responses=SEND_RESPONSES,@@ -1261,6 +1308,9 @@ class MessagingSendViewSet(TransactionalEmailSendMixin, TeamAndOrgViewSetMixin,sender=data.get("from"),reply_to=tuple(data.get("reply_to", ())),capture_engagement=data.get("capture_engagement", True),+ cc=tuple(data.get("cc") or ()),+ bcc=tuple(data.get("bcc") or ()),+ attachments=tuple(EmailAttachment(**attachment) for attachment in data.get("attachments") or ()),)return self._queue_send(request,diff --git a/products/messaging/backend/services/transactional_email.py b/products/messaging/backend/services/transactional_email.pyindex a6028fdb4e6c..38fa12990b9f 100644--- a/products/messaging/backend/services/transactional_email.py+++ b/products/messaging/backend/services/transactional_email.py@@ -2,6 +2,7 @@per send, so sends get the workflow's metrics, run history and versions."""import re+import jsonimport timefrom collections.abc import Callable, Iteratorfrom contextlib import contextmanager@@ -26,6 +27,8 @@ from products.messaging.backend.facade.contracts import (CodeEmail,ContentTooLarge,DeliveryUnavailable,+ EmailAttachment,+ FieldNotAccepted,IdempotencyKeyInFlight,IdempotencyKeyReused,InvalidIdempotencyKey,@@ -514,7 +517,7 @@ def send_code_email(distinct_id: str | None,idempotency_key: str | None = None,) -> QueuedEmail:- _check_send_request(to, idempotency_key)+ _check_send_request(to, idempotency_key, (*email.cc, *email.bcc))with transactional_email_stage("workflow_lookup"):accepted_send = _accepted_send(team.id, email)hog_flow_id = _code_email_workflow_id(team.id, email.key)@@ -522,7 +525,7 @@ def send_code_email(return _queue(team.id, hog_flow_id, payload, send_accepted_transactional_email)-def _check_send_request(to: str, idempotency_key: str | None) -> None:+def _check_send_request(to: str, idempotency_key: str | None, copies: tuple[str, ...] = ()) -> 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."@@ -530,6 +533,8 @@ def _check_send_request(to: str, idempotency_key: str | None) -> None:# Defense in depth: the workflow reads the recipient from an event property, which Liquid outputs as typed.if "{" in to or "}" in to:raise InvalidRecipient("The recipient address can't contain { or }.")+ if any("{" in address or "}" in address for address in copies):+ raise InvalidRecipient("A `cc` or `bcc` address can't contain { or }.")def _send_payload(@@ -557,9 +562,26 @@ def _accepted_send(team_id: int, email: CodeEmail) -> dict[str, Any]:}if email.reply_to:accepted["replyTo"] = list(email.reply_to)+ if email.cc:+ accepted["cc"] = list(email.cc)+ if email.bcc:+ accepted["bcc"] = list(email.bcc)+ if email.attachments:+ accepted["attachments"] = [_accepted_attachment(attachment) for attachment in email.attachments]return accepted+def _accepted_attachment(attachment: EmailAttachment) -> dict[str, str]:+ return _without_empty(+ {+ "filename": attachment.filename,+ "content": attachment.content,+ "contentType": attachment.content_type,+ "contentId": attachment.content_id,+ }+ )++def _code_send_sender(team_id: int, address: str | None) -> dict[str, Any]:name, email = parseaddr(address) if address else ("", "")try:@@ -609,6 +631,15 @@ def _queue()if response.status_code != 202:refusal_code = _refusal_code(response)+ unknown_field = _send_field_an_older_pipeline_refused(refusal_code) if response.status_code == 400 else None+ if unknown_field is not None:+ logger.warning(+ "transactional_email_field_not_accepted",+ team_id=team_id,+ hog_flow_id=str(hog_flow_id),+ field=unknown_field,+ )+ raise FieldNotAccepted(unknown_field)refusal = PIPELINE_REFUSALS.get(refusal_code or "")if refusal is None and response.status_code == 400:refusal = PIPELINE_REFUSALS["invalid_request"]@@ -629,6 +660,19 @@ def _queue(return QueuedEmail(message_id=str(body["invocation_id"]), replayed=bool(body.get("replayed", False)))+def _send_field_an_older_pipeline_refused(error: str | None) -> str | None:+ try:+ issues = json.loads(error or "")+ except ValueError:+ return None+ for issue in issues if isinstance(issues, list) else []:+ if isinstance(issue, dict) and issue.get("code") == "unrecognized_keys" and issue.get("path") == ["send"]:+ keys = issue.get("keys")+ if isinstance(keys, list) and keys and isinstance(keys[0], str):+ return keys[0]+ return None++def _refusal_code(response: requests.Response) -> str | None:try:body = response.json()diff --git a/products/messaging/backend/tests/api/test_transactional_email.py b/products/messaging/backend/tests/api/test_transactional_email.pyindex 1e24824f425c..08ba3ab86eae 100644--- a/products/messaging/backend/tests/api/test_transactional_email.py+++ b/products/messaging/backend/tests/api/test_transactional_email.py@@ -37,26 +37,11 @@ from products.messaging.backend.presentation.views.message_templates import ()from products.messaging.backend.services import transactional_emailfrom products.messaging.backend.services.transactional_email import TransactionalEmailStage, make_transactional+from products.messaging.backend.tests.test_code_send_fields import ADDRESS_VERDICTSfrom products.workflows.backend.facade.api import set_default_email_sender_if_unsetfrom products.workflows.backend.facade.models import HogFlowfrom 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),-]-@frozenclass CapturedFirstCodeSend:@@ -648,6 +633,35 @@ class TestTransactionalEmail(APIBaseTest):{"html": "", "text": "Hi"},{"content": {"subject": "Welcome, Jane", "text": "Hi"}, "tracking": {"captureEngagement": True}},),+ (+ "null_copies_and_attachments",+ {"cc": None, "bcc": None, "attachments": None},+ {+ "content": {"subject": "Welcome, Jane", "html": "<p>Hi Jane</p>", "text": "Hi Jane"},+ "tracking": {"captureEngagement": True},+ },+ ),+ (+ "cc_bcc_and_attachments",+ {+ "cc": "[email protected]",+ "bcc": ["[email protected]", "[email protected]"],+ "attachments": [+ {"filename": "a.csv", "content": "YSxi", "content_type": "text/csv", "content_id": "a"},+ {"filename": "notes.txt", "content": "aGk="},+ ],+ },+ {+ "content": {"subject": "Welcome, Jane", "html": "<p>Hi Jane</p>", "text": "Hi Jane"},+ "tracking": {"captureEngagement": True},+ "cc": ["[email protected]"],+ "bcc": ["[email protected]", "[email protected]"],+ "attachments": [+ {"filename": "a.csv", "content": "YSxi", "contentType": "text/csv", "contentId": "a"},+ {"filename": "notes.txt", "content": "aGk="},+ ],+ },+ ),])def test_a_code_send_carries_what_the_caller_set(self, mock_post, _flag, _capture, _name, fields, sent):@@ -680,6 +694,11 @@ class TestTransactionalEmail(APIBaseTest):("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"),+ (+ "liquid_in_a_copy_address",+ {"bcc": ["[email protected]", "{{person.properties.email}}@example.com"]},+ None,+ ),("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"),@@ -696,7 +715,10 @@ class TestTransactionalEmail(APIBaseTest):mock_post.assert_not_called()@parameterized.expand(- [(field, address, accepted) for field in ("to", "reply_to") for address, accepted in ADDRESS_VERDICTS]+ [+ *((field, address, accepted) for field in ("to", "reply_to") for address, accepted in ADDRESS_VERDICTS),+ ("cc", '"jane doe"@example.com', False),+ ])def test_a_code_send_takes_the_addresses_the_pipeline_takes(self, mock_post, _flag, _capture, field, address, accepted@@ -717,11 +739,52 @@ class TestTransactionalEmail(APIBaseTest):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"})+ @parameterized.expand(+ [+ ("subject", "Hi", "validation_error"),+ ("cc", "[email protected]", "invalid_request"),+ ("bcc", ["[email protected]"], "invalid_request"),+ ("attachments", [{"filename": "notes.txt", "content": "aGk="}], "invalid_request"),+ ]+ )+ def test_refuses_code_fields_on_a_template_send(self, mock_post, _flag, _capture, field, value, error_type):+ response = self._send(self._psak_client(["hog_flow:write"]), "send_email", {**self.body, field: value})++ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()+ assert (response.json()["attr"], response.json()["type"]) == (field, error_type)+ mock_post.assert_not_called()++ @parameterized.expand(+ [+ ("empty_lists", {"cc": [], "bcc": [], "attachments": []}),+ ("nulls", {"cc": None, "bcc": None, "attachments": None}),+ ]+ )+ def test_takes_empty_copies_and_attachments_on_a_template_send(self, mock_post, _flag, _capture, _name, fields):+ self._cdp_accepts(mock_post)++ response = self._send(self._psak_client(["hog_flow:write"]), "send_email", {**self.body, **fields})++ assert response.status_code == status.HTTP_202_ACCEPTED, response.json()+ mock_post.assert_called_once()++ def test_a_refused_attachment_explains_itself_without_repeating_its_content(self, mock_post, _flag, _capture):+ content = "c2VjcmV0LWludm9pY2UtYnl0ZXM=" + "!"+ attachments = [{"filename": "invoice.pdf", "content": content}]++ response = self._psak_client(["hog_flow:write"]).post(+ self.send_email_url, self._code_send(attachments=attachments), format="json"+ )assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()- assert response.json()["attr"] == "subject"+ body = response.json()+ assert (body["type"], body["code"], body["attr"]) == (+ "invalid_request",+ "invalid_request",+ "attachments__0__content",+ )+ assert body["why"] and body["fix"]+ assert "c2VjcmV0" not in response.content.decode()mock_post.assert_not_called()@parameterized.expand(@@ -821,6 +884,22 @@ class TestTransactionalEmail(APIBaseTest):else:assert response.json() == {"message_id": "first-send", "replayed": True}+ def test_a_code_send_an_older_pipeline_does_not_take_is_refused_on_that_field(self, mock_post, _flag, capture):+ issues = [{"code": "unrecognized_keys", "keys": ["attachments"], "path": ["send"], "message": "Unrecognized"}]+ mock_post.return_value = MagicMock(status_code=400, json=lambda: {"error": json.dumps(issues)})++ response = self._psak_client(["hog_flow:write"]).post(+ self.send_email_url,+ self._code_send(attachments=[{"filename": "receipt.pdf", "content": "JVBERg=="}]),+ format="json",+ )++ assert response.status_code == status.HTTP_400_BAD_REQUEST, response.json()+ body = response.json()+ assert (body["code"], body["attr"]) == ("invalid_request", "attachments")+ assert body["why"] and body["fix"]+ assert capture.call_args.kwargs["properties"]["error_code"] == "field_not_accepted"+@parameterized.expand([("below_the_key_limit", transactional_email.TRANSACTIONAL_EMAIL_KEY_LIMIT),diff --git a/products/messaging/backend/tests/test_code_send_fields.py b/products/messaging/backend/tests/test_code_send_fields.pynew file mode 100644index 000000000000..0e37331e4c97--- /dev/null+++ b/products/messaging/backend/tests/test_code_send_fields.py@@ -0,0 +1,168 @@+import base64+from typing import Any++from django.test import RequestFactory, SimpleTestCase++from parameterized import parameterized+from rest_framework.exceptions import ValidationError++from posthog.exceptions import exception_handler++from products.messaging.backend.presentation.views.code_send_fields import with_code_send_reason+from products.messaging.backend.presentation.views.message_templates import SendEmailSerializer++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 _attachment(**fields: Any) -> dict[str, str]:+ return {"filename": "invoice.pdf", "content": "JVBERi0xLjQ=", **fields}+++def _code_send(fields: dict[str, Any]) -> SendEmailSerializer:+ return SendEmailSerializer(+ data={"to": "[email protected]", "template_key": "welcome", "subject": "Hi", "text": "Hi", **fields}+ )+++def _refusal(fields: dict[str, Any]) -> dict[str, Any]:+ serializer = _code_send(fields)+ assert not serializer.is_valid()+ response = exception_handler(ValidationError(serializer.errors), {"request": RequestFactory().post("/")})+ assert response is not None+ return with_code_send_reason(response.data)+++class TestCodeSendFieldRefusals(SimpleTestCase):+ @parameterized.expand(+ [+ ("cc_with_a_display_name", {"cc": "Jane <[email protected]>"}, "cc__0"),+ ("cc_with_two_addresses_in_one", {"cc": "[email protected], [email protected]"}, "cc__0"),+ (+ "content_that_is_not_base64",+ {"attachments": [_attachment(content="not base64!")]},+ "attachments__0__content",+ ),+ ("empty_content", {"attachments": [_attachment(content="")]}, "attachments__0__content"),+ ("executable", {"attachments": [_attachment(filename="setup.EXE")]}, "attachments__0__filename"),+ ("registry_file", {"attachments": [_attachment(filename="settings.reg")]}, "attachments__0__filename"),+ (+ "executable_with_a_trailing_dot",+ {"attachments": [_attachment(filename="setup.exe.")]},+ "attachments__0__filename",+ ),+ (+ "filename_with_a_path",+ {"attachments": [_attachment(), _attachment(filename="../invoice.pdf")]},+ "attachments__1__filename",+ ),+ (+ "filename_with_a_line_break",+ {"attachments": [_attachment(filename="invoice\r\n.pdf")]},+ "attachments__0__filename",+ ),+ (+ "content_type_that_is_not_a_mime_type",+ {"attachments": [_attachment(content_type="pdf")]},+ "attachments__0__content_type",+ ),+ (+ "content_id_with_brackets",+ {"attachments": [_attachment(content_id="<logo>")]},+ "attachments__0__content_id",+ ),+ ("attachment_that_is_not_an_object", {"attachments": ["invoice.pdf"]}, "attachments__0"),+ (+ "attachment_with_a_camel_case_key",+ {"attachments": [_attachment(contentId="logo")]},+ "attachments__0__contentId",+ ),+ (+ "attachment_with_an_empty_key",+ {"attachments": [_attachment(**{"": "", "contentId": "logo"})]},+ "attachments__0__",+ ),+ (+ "attachments_too_large",+ {"attachments": [_attachment(content=base64.b64encode(b"x" * 300_000).decode())] * 2},+ "attachments",+ ),+ ]+ )+ def test_refuses_an_extra_field_it_cannot_send(self, _name: str, fields: dict[str, Any], attr: str) -> None:+ refused = _refusal(fields)++ assert (refused["type"], refused["code"], refused["attr"]) == ("invalid_request", "invalid_request", attr)+ assert refused["why"] and refused["fix"]++ @parameterized.expand(+ [+ ("too_many_bcc", {"bcc": [f"user{i}@example.com" for i in range(11)]}, "bcc", "at most 10 addresses"),+ ("too_many_attachments", {"attachments": [_attachment()] * 11}, "attachments", "at most 10 files"),+ (+ "filename_too_long",+ {"attachments": [_attachment(filename="a" * 252 + ".pdf")]},+ "attachments__0__filename",+ "255 characters",+ ),+ (+ "content_type_too_long",+ {"attachments": [_attachment(content_type=f"application/{'x' * 67}")]},+ "attachments__0__content_type",+ "78 characters",+ ),+ (+ "content_id_too_long",+ {"attachments": [_attachment(content_id="x" * 79)]},+ "attachments__0__content_id",+ "78 characters",+ ),+ ]+ )+ def test_explains_the_limit_a_refused_field_passed(+ self, _name: str, fields: dict[str, Any], attr: str, fix: str+ ) -> None:+ refused = _refusal(fields)++ assert (refused["code"], refused["attr"]) == ("invalid_request", attr)+ assert fix in refused["fix"]++ @parameterized.expand(+ [+ ("one_address", {"cc": "[email protected]"}),+ ("empty_lists", {"cc": [], "bcc": [], "attachments": []}),+ ("ten_addresses", {"bcc": [f"user{i}@example.com" for i in range(10)]}),+ (+ "attachments_at_the_size_limit",+ {"attachments": [_attachment(content=base64.b64encode(b"x" * 262_144).decode())] * 2},+ ),+ ]+ )+ def test_accepts_extra_fields_at_their_limits(self, _name: str, fields: dict[str, Any]) -> None:+ serializer = _code_send(fields)++ assert serializer.is_valid(), serializer.errors++ @parameterized.expand(+ [(field, address, accepted) for field in ("cc", "bcc") for address, accepted in ADDRESS_VERDICTS]+ )+ def test_takes_the_copy_addresses_the_pipeline_takes(self, field: str, address: str, accepted: bool) -> None:+ if accepted:+ serializer = _code_send({field: [address]})+ assert serializer.is_valid(), serializer.errors+ assert serializer.validated_data[field] == [address]+ else:+ assert _refusal({field: [address]})["attr"] == f"{field}__0"diff --git a/products/messaging/frontend/generated/api.schemas.ts b/products/messaging/frontend/generated/api.schemas.tsindex a7ad4e5763c2..6777c1ade4c3 100644--- a/products/messaging/frontend/generated/api.schemas.ts+++ b/products/messaging/frontend/generated/api.schemas.ts@@ -88,6 +88,26 @@ export interface TopicPreferencesApi {*/export type SendEmailApiMessageData = { [key: string]: unknown }+export interface EmailAttachmentApi {+ /**+ * File name the recipient sees, such as `invoice.pdf`. No path and no line breaks. A file type mailbox providers block, such as `.exe`, is refused.+ * @maxLength 255+ */+ filename: string+ /** The file's bytes as standard base64, without line breaks. */+ content: string+ /**+ * MIME type of the file, such as `application/pdf`. Without it, the type follows from the file name.+ * @maxLength 78+ */+ content_type?: string+ /**+ * Content ID that the HTML body references as `cid:<content_id>` to show the file inline, such as `logo`. Without `<` or `>`.+ * @maxLength 78+ */+ content_id?: string+}+export interface SendEmailApi {/** Email address of the recipient. */to: string@@ -118,6 +138,16 @@ export interface SendEmailApi {* @maxItems 10*/reply_to?: string[]+ /** Addresses that get a visible copy of the email your code rendered: one address, or a list of up to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with `template_id`, which refuses any address here. */+ cc?: string | string[] | null+ /** Addresses that get a hidden copy of the email your code rendered: one address, or a list of up to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with `template_id`, which refuses any address here. */+ bcc?: string | string[] | null+ /**+ * Files attached to the email your code rendered: up to 10, and at most 512 KB in total after decoding. File types mailbox providers block, such as `.exe`, are refused. Doesn't apply to a send with `template_id`, which refuses any file here.+ * @maxItems 10+ * @nullable+ */+ attachments?: EmailAttachmentApi[] | null/** 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/**diff --git a/products/messaging/frontend/generated/api.zod.ts b/products/messaging/frontend/generated/api.zod.tsindex 1177986e0f31..29fae7004f98 100644--- a/products/messaging/frontend/generated/api.zod.ts+++ b/products/messaging/frontend/generated/api.zod.ts@@ -47,6 +47,18 @@ export const messagingSendEmailCreateBodyDistinctIdMax = 400export const messagingSendEmailCreateBodyReplyToMax = 10+export const messagingSendEmailCreateBodyCcTwoMax = 10++export const messagingSendEmailCreateBodyBccTwoMax = 10++export const messagingSendEmailCreateBodyAttachmentsItemFilenameMax = 255++export const messagingSendEmailCreateBodyAttachmentsItemContentTypeMax = 78++export const messagingSendEmailCreateBodyAttachmentsItemContentIdMax = 78++export const messagingSendEmailCreateBodyAttachmentsMax = 10+export const messagingSendEmailCreateBodyFromMax = 1024export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({@@ -91,6 +103,49 @@ export const MessagingSendEmailCreateBody = /* @__PURE__ */ zod.object({.max(messagingSendEmailCreateBodyReplyToMax).optional().describe('Addresses replies to the email your code rendered go to.'),+ cc: zod+ .union([zod.email(), zod.array(zod.email()).max(messagingSendEmailCreateBodyCcTwoMax), zod.null()])+ .optional()+ .describe(+ "Addresses that get a visible copy of the email your code rendered: one address, or a list of up to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with `template_id`, which refuses any address here."+ ),+ bcc: zod+ .union([zod.email(), zod.array(zod.email()).max(messagingSendEmailCreateBodyBccTwoMax), zod.null()])+ .optional()+ .describe(+ "Addresses that get a hidden copy of the email your code rendered: one address, or a list of up to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with `template_id`, which refuses any address here."+ ),+ attachments: zod+ .array(+ zod.object({+ filename: zod+ .string()+ .max(messagingSendEmailCreateBodyAttachmentsItemFilenameMax)+ .describe(+ 'File name the recipient sees, such as `invoice.pdf`. No path and no line breaks. A file type mailbox providers block, such as `.exe`, is refused.'+ ),+ content: zod.string().describe("The file's bytes as standard base64, without line breaks."),+ content_type: zod+ .string()+ .max(messagingSendEmailCreateBodyAttachmentsItemContentTypeMax)+ .optional()+ .describe(+ 'MIME type of the file, such as `application\/pdf`. Without it, the type follows from the file name.'+ ),+ content_id: zod+ .string()+ .max(messagingSendEmailCreateBodyAttachmentsItemContentIdMax)+ .optional()+ .describe(+ 'Content ID that the HTML body references as `cid:<content_id>` to show the file inline, such as `logo`. Without `<` or `>`.'+ ),+ })+ )+ .max(messagingSendEmailCreateBodyAttachmentsMax)+ .nullish()+ .describe(+ "Files attached to the email your code rendered: up to 10, and at most 512 KB in total after decoding. File types mailbox providers block, such as `.exe`, are refused. Doesn't apply to a send with `template_id`, which refuses any file here."+ ),capture_engagement: zod.boolean().optional()diff --git a/products/workflows/mcp/email_templates.yaml b/products/workflows/mcp/email_templates.yamlindex 9f0c50f108de..d85d9888986c 100644--- a/products/workflows/mcp/email_templates.yaml+++ b/products/workflows/mcp/email_templates.yaml@@ -167,6 +167,9 @@ tools:exclude_params:- template_id- message_data+ - cc+ - bcc+ - attachmentsparam_overrides:template_key:required: truediff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.tsindex 43e317793473..c6327bfdc58b 100644--- a/services/mcp/src/api/generated.ts+++ b/services/mcp/src/api/generated.ts@@ -36818,6 +36818,26 @@ export namespace Schemas {name: string;}+ export interface EmailAttachment {+ /**+ * File name the recipient sees, such as `invoice.pdf`. No path and no line breaks. A file type mailbox providers block, such as `.exe`, is refused.+ * @maxLength 255+ */+ filename: string;+ /** The file's bytes as standard base64, without line breaks. */+ content: string;+ /**+ * MIME type of the file, such as `application/pdf`. Without it, the type follows from the file name.+ * @maxLength 78+ */+ content_type?: string;+ /**+ * Content ID that the HTML body references as `cid:<content_id>` to show the file inline, such as `logo`. Without `<` or `>`.+ * @maxLength 78+ */+ content_id?: string;+ }+/*** * `queued` - Queued* * `failed` - Failed@@ -104629,6 +104649,16 @@ export namespace Schemas {* @maxItems 10*/reply_to?: string[];+ /** Addresses that get a visible copy of the email your code rendered: one address, or a list of up to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with `template_id`, which refuses any address here. */+ cc?: string | string[] | null;+ /** Addresses that get a hidden copy of the email your code rendered: one address, or a list of up to 10. Each is a bare address such as `[email protected]`, with no name. Doesn't apply to a send with `template_id`, which refuses any address here. */+ bcc?: string | string[] | null;+ /**+ * Files attached to the email your code rendered: up to 10, and at most 512 KB in total after decoding. File types mailbox providers block, such as `.exe`, are refused. Doesn't apply to a send with `template_id`, which refuses any file here.+ * @maxItems 10+ * @nullable+ */+ attachments?: EmailAttachment[] | null;/** 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;/**