diff --git a/.github/scripts/check_strict_types.sh b/.github/scripts/check_strict_types.sh index d1647516b..79d73f5d8 100755 --- a/.github/scripts/check_strict_types.sh +++ b/.github/scripts/check_strict_types.sh @@ -49,7 +49,7 @@ rendered_send: SendEmailResult = emails.send(to="user@example.com", template_key invite_send: SendEmailResult = emails.send(to="user@example.com", template_key="invite", subject="Invite", html="

Invite

", cc="team@example.com", bcc=["audit@example.com"], attachments=[{"filename": "invite.ics", "content": b"BEGIN:VCALENDAR", "content_type": "text/calendar"}, {"filename": "logo.png", "content": "iVBORw0KGgo=", "content_id": "logo"}]) tracked_send: SendEmailResult = emails.send(to="user@example.com", template_key="welcome", subject="Welcome", html="

Hi

", tracking={"clicks": True, "engagement": False}) untracked_send: SendEmailResult = emails.send(to="user@example.com", template_key="welcome", subject="Welcome", html="

Hi

", tracking=False) -not_sensitive_send: SendEmailResult = emails.send(to="user@example.com", template_key="newsletter", subject="News", html="

News

", sensitive=False) +not_sensitive_send: SendEmailResult = emails.send(to="user@example.com", template_key="newsletter", subject="News", html="

News

", sensitive=False, headers={"List-Unsubscribe": ""}) _ = (template_send, rendered_send, invite_send, tracked_send, untracked_send, not_sensitive_send) @@ -112,6 +112,7 @@ Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3 Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", capture_engagement=False) # expected-type-error Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", tracking=False) # expected-type-error Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", sensitive=False) # expected-type-error +Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", headers={"List-Unsubscribe": ""}) # expected-type-error Emails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="

Hi

", tracking={"open": False}) # expected-type-error Emails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="

Hi

", template_data={"name": "Ada"}) # expected-type-error Emails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="

Hi

", attachments=[{"filename": "a.txt", "content": [104, 105]}]) # expected-type-error diff --git a/.sampo/changesets/emails-code-send-headers.md b/.sampo/changesets/emails-code-send-headers.md new file mode 100644 index 000000000..db1cabbe1 --- /dev/null +++ b/.sampo/changesets/emails-code-send-headers.md @@ -0,0 +1,5 @@ +--- +pypi/posthog: minor +--- + +`emails.send`: a code send takes `headers`, such as `List-Unsubscribe` and `List-Unsubscribe-Post` for one-click unsubscribe. The SDK sends them as given, and PostHog refuses a header it doesn't allow. The template form refuses `headers`. diff --git a/posthog/emails.py b/posthog/emails.py index 047119b99..f11999246 100644 --- a/posthog/emails.py +++ b/posthog/emails.py @@ -391,6 +391,11 @@ class CodeEmailArgs(_RecipientArgs): key you leave out keeps its default. Turn clicks on for a sensitive email only when its links are safe to send through PostHog's click tracking. The template form doesn't take it. + headers: Header names and values to send with the email, such as + ``{"List-Unsubscribe": "", + "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"}``. PostHog + refuses a header it doesn't allow, with ``code`` + ``unknown_header``. The template form doesn't take it. distinct_id: The recipient's distinct ID in your product. idempotency_key: 1 to 255 visible ASCII characters. Template sends and code sends share one set of keys: a key already used for @@ -413,6 +418,7 @@ class CodeEmailArgs(_RecipientArgs): capture_engagement: NotRequired[Optional[bool]] sensitive: NotRequired[Optional[bool]] tracking: NotRequired[Optional[Union[bool, EmailTracking]]] + headers: NotRequired[Optional[Mapping[str, str]]] _ATTACHMENT_FIELDS = frozenset(EmailAttachment.__annotations__) @@ -428,6 +434,7 @@ class CodeEmailArgs(_RecipientArgs): "capture_engagement", "sensitive", "tracking", + "headers", } ) @@ -582,6 +589,10 @@ def _sender(args: Mapping[str, Any]) -> dict[str, Any]: sender[flag] = args[flag] if "tracking" in args: sender["tracking"] = _tracking(args["tracking"]) + if "headers" in args: + if not isinstance(args["headers"], Mapping): + raise TypeError("headers must be a dict of header names and values.") + sender["headers"] = dict(args["headers"]) return sender diff --git a/posthog/test/test_emails.py b/posthog/test/test_emails.py index b2690cff0..bbb2add12 100644 --- a/posthog/test/test_emails.py +++ b/posthog/test/test_emails.py @@ -636,6 +636,10 @@ def handler(request: httpx.Request) -> httpx.Response: HTML = "

Reset it here.

" +UNSUBSCRIBE_HEADERS = { + "List-Unsubscribe": "", + "List-Unsubscribe-Post": "List-Unsubscribe=One-Click", +} INVITE = b"BEGIN:VCALENDAR\r\nEND:VCALENDAR\r\n" INVITE_BASE64 = "QkVHSU46VkNBTEVOREFSDQpFTkQ6VkNBTEVOREFSDQo=" @@ -684,6 +688,11 @@ def send_code(emails: Emails, **overrides: Any): {"html": HTML, "reply_to": []}, {"html": HTML}, ), + ( + "headers_as_given", + {"html": HTML, "headers": UNSUBSCRIBE_HEADERS}, + {"html": HTML, "headers": UNSUBSCRIBE_HEADERS}, + ), ( "none_as_left_out", { @@ -692,6 +701,7 @@ def send_code(emails: Emails, **overrides: Any): "from_": None, "reply_to": None, "capture_engagement": None, + "headers": None, "distinct_id": None, }, {"html": HTML}, @@ -928,6 +938,17 @@ def handler(request: httpx.Request) -> httpx.Response: }, TypeError, ), + ( + "headers_on_template_form", + { + "template_id": TEMPLATE_ID, + "template_key": None, + "subject": None, + "headers": UNSUBSCRIBE_HEADERS, + }, + TypeError, + ), + ("headers_not_a_mapping", {"html": HTML, "headers": "x"}, TypeError), ("tracking_not_bool_or_dict", {"html": HTML, "tracking": "off"}, TypeError), ("sensitive_not_bool", {"html": HTML, "sensitive": "yes"}, TypeError), ] diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt index 4b51f85aa..3991583e7 100644 --- a/references/public_api_snapshot.txt +++ b/references/public_api_snapshot.txt @@ -918,6 +918,7 @@ attribute posthog.emails.CodeEmailArgs.bcc: NotRequired[Optional[Union[str, Sequ attribute posthog.emails.CodeEmailArgs.capture_engagement: NotRequired[Optional[bool]] attribute posthog.emails.CodeEmailArgs.cc: NotRequired[Optional[Union[str, Sequence[str]]]] attribute posthog.emails.CodeEmailArgs.from_: NotRequired[Optional[str]] +attribute posthog.emails.CodeEmailArgs.headers: NotRequired[Optional[Mapping[str, str]]] attribute posthog.emails.CodeEmailArgs.html: NotRequired[Optional[str]] attribute posthog.emails.CodeEmailArgs.reply_to: NotRequired[Optional[Union[str, Sequence[str]]]] attribute posthog.emails.CodeEmailArgs.sensitive: NotRequired[Optional[bool]]