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 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.py
index 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, field
from datetime import datetime
from typing import Any
from 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 | None
reply_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.py
index 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.py
new file mode 100644
index 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.py
index 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 DesignOperationSerializer
from products.notifications.backend.facade.api import publish_resource_edited
from 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 data
unknown = 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 None
except 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.py
index 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 json
import time
from collections.abc import Callable, Iterator
from 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.py
index 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_email
from products.messaging.backend.services.transactional_email import TransactionalEmailStage, make_transactional
+from products.messaging.backend.tests.test_code_send_fields import ADDRESS_VERDICTS
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),
-]
-
@frozen
class 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",
+ {
+ "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]"],
+ "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.py
new file mode 100644
index 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.ts
index 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.ts
index 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 = 400
export 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 = 1024
export 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.yaml
index 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
+ - attachments
param_overrides:
template_key:
required: true
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 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;
/**