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]]