diff --git a/.github/scripts/check_strict_types.sh b/.github/scripts/check_strict_types.sh
index 4e41c9e8f..afa3c483d 100755
--- a/.github/scripts/check_strict_types.sh
+++ b/.github/scripts/check_strict_types.sh
@@ -44,7 +44,10 @@ _ = (flag_value, all_flags, enabled, payload, evaluations, active)
emails = Emails("phs_example")
template_send: SendEmailResult = emails.send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", template_data={"name": "Ada"})
rendered_send: SendEmailResult = emails.send(to="user@example.com", template_key="password-reset", subject="Reset", html="
Reset
", from_="Acme ", reply_to=["help@example.com"], capture_engagement=False, max_retries=0)
-_ = (template_send, rendered_send)
+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)
+_ = (template_send, rendered_send, tracked_send, untracked_send)
async def async_email_types() -> None:
@@ -89,6 +92,9 @@ Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3
Emails("phs_example").send(to="user@example.com", template_key="welcome", html="Hi
") # expected-type-error
Emails("phs_example").send(to="user@example.com", template_id="0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b", cc="team@example.com") # expected-type-error
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_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
", cc="team@example.com") # expected-type-error
diff --git a/.sampo/changesets/emails-tracking.md b/.sampo/changesets/emails-tracking.md
new file mode 100644
index 000000000..e1053e63d
--- /dev/null
+++ b/.sampo/changesets/emails-tracking.md
@@ -0,0 +1,23 @@
+---
+pypi/posthog: minor
+---
+
+A send with `template_key` now takes `tracking` and `sensitive`. The template form doesn't take either one.
+
+`tracking` chooses what PostHog tracks for the email. `tracking=True` turns on opens, clicks and engagement events. `tracking=False` turns them all off. A dict such as `{"clicks": True}` or `{"engagement": False}` turns each kind on or off, and a key you leave out keeps its default. Without it, PostHog counts opens, captures engagement events, and counts clicks only when the email isn't sensitive.
+
+`sensitive` marks an email that carries login links, reset tokens or codes. A sensitive email keeps its links as they are unless `tracking` turns clicks on, leaves its subject off engagement events, and keeps its content out of PostHog's logs. Without it, a send whose `template_key` matches a template saved in PostHog follows that template's setting, and any other send is sensitive. A send that sets neither option works exactly as before.
+
+```python
+posthog.emails.send(
+ to="user@example.com",
+ template_key="newsletter",
+ subject="What's new at Acme",
+ html=rendered_html,
+ sensitive=False,
+)
+```
+
+`capture_engagement` is deprecated in favor of `tracking={"engagement": False}`. It keeps working, but PostHog refuses a send that sets both.
+
+`tracking` and `sensitive` need PostHog's API support, which is rolling out. Until it reaches your PostHog instance, PostHog refuses a send that sets either one.
diff --git a/posthog/emails.py b/posthog/emails.py
index 42e70b971..2839a2dd6 100644
--- a/posthog/emails.py
+++ b/posthog/emails.py
@@ -131,6 +131,7 @@
"CodeEmailArgs",
"EmailError",
"EmailStatus",
+ "EmailTracking",
"EmailWarning",
"Emails",
"SendEmailResult",
@@ -241,6 +242,28 @@ class TemplateEmailArgs(_RecipientArgs):
template_data: NotRequired[Optional[Mapping[str, Any]]]
+class EmailTracking(TypedDict, total=False):
+ """Which kinds of tracking a send with ``template_key`` turns on.
+
+ A key you leave out keeps its default.
+
+ Args:
+ opens: Counts opens with PostHog's open pixel. Defaults to ``True``.
+ clicks: Counts clicks by sending the email's links through PostHog's
+ click tracking. Defaults to ``False`` for a sensitive email and
+ ``True`` for any other. Needs ``opens``: PostHog refuses a send
+ with ``opens=False`` and ``clicks=True``.
+ engagement: Captures the email's engagement events (sent,
+ delivered, opened, clicked, bounced) as events of the recipient.
+ Defaults to ``True``. A project whose admin turned engagement
+ capture off captures nothing, whatever the send asks.
+ """
+
+ opens: bool
+ clicks: bool
+ engagement: bool
+
+
class CodeEmailArgs(_RecipientArgs):
"""A send of email content that your code rendered for one recipient, named by a key.
@@ -260,11 +283,31 @@ class CodeEmailArgs(_RecipientArgs):
without a plain-text part.
from_: A verified sender, such as ``"Acme "``.
reply_to: One address or a list of addresses. An empty list sends no reply-to.
- capture_engagement: Capture the email's opens and clicks as events of
- the recipient. Defaults to ``True``. A project whose admin turned
- engagement capture off captures nothing, whatever the send asks. A
- template made in PostHog follows the project's setting, so the
- template form doesn't take it.
+ capture_engagement: Deprecated, use ``tracking={"engagement": False}``.
+ It keeps working, but PostHog refuses a send that sets both
+ ``capture_engagement`` and ``tracking``. Captures the email's
+ engagement events as events of the recipient. Defaults to
+ ``True``. A project whose admin turned engagement capture off
+ captures nothing, whatever the send asks. A template made in
+ PostHog follows the project's setting, so the template form
+ doesn't take it.
+ sensitive: Marks the email as sensitive, such as one that carries
+ login links, reset tokens or codes. A sensitive email keeps its
+ links as they are unless ``tracking`` turns clicks on, leaves its
+ subject off engagement events, and keeps its content out of
+ PostHog's logs. Without it, a send whose ``template_key`` matches
+ a template saved in PostHog follows that template's setting, and
+ any other send is sensitive. The template form doesn't take it.
+ tracking: What PostHog tracks for this email. Without it, PostHog
+ counts opens with its open pixel, captures engagement events, and
+ counts clicks only when the email isn't sensitive. ``True`` turns
+ on opens, clicks and engagement events. ``False`` turns off all
+ tracking, including kinds PostHog adds later: PostHog can't count
+ the email's opens or clicks, and captures no engagement events.
+ An :class:`EmailTracking` dict turns each kind on or off, and a
+ 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.
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
@@ -282,6 +325,8 @@ class CodeEmailArgs(_RecipientArgs):
from_: NotRequired[Optional[str]]
reply_to: NotRequired[Optional[Union[str, Sequence[str]]]]
capture_engagement: NotRequired[Optional[bool]]
+ sensitive: NotRequired[Optional[bool]]
+ tracking: NotRequired[Optional[Union[bool, EmailTracking]]]
_OPTIONAL_CODE_FIELDS = frozenset(
@@ -291,6 +336,8 @@ class CodeEmailArgs(_RecipientArgs):
"from_",
"reply_to",
"capture_engagement",
+ "sensitive",
+ "tracking",
}
)
@@ -406,13 +453,26 @@ def _sender(args: Mapping[str, Any]) -> dict[str, Any]:
reply_to = _addresses("reply_to", args["reply_to"]) if "reply_to" in args else []
if reply_to:
sender["reply_to"] = reply_to
- capture_engagement = args.get("capture_engagement", True)
- if not isinstance(capture_engagement, bool):
- raise TypeError("capture_engagement must be True or False.")
- sender["capture_engagement"] = capture_engagement
+ for flag in ("capture_engagement", "sensitive"):
+ if flag in args:
+ if not isinstance(args[flag], bool):
+ raise TypeError(f"{flag} must be True or False.")
+ sender[flag] = args[flag]
+ if "tracking" in args:
+ sender["tracking"] = _tracking(args["tracking"])
return sender
+def _tracking(value: Any) -> Union[bool, dict[str, Any]]:
+ if isinstance(value, bool):
+ return value
+ if isinstance(value, Mapping):
+ return dict(value)
+ raise TypeError(
+ "tracking must be True, False or a dict of opens, clicks and engagement."
+ )
+
+
def _addresses(field: str, value: Any) -> list[str]:
addresses = [value] if isinstance(value, str) else value
if not isinstance(addresses, Sequence) or not all(
diff --git a/posthog/test/test_emails.py b/posthog/test/test_emails.py
index eaf1c0949..b13b8a0c6 100644
--- a/posthog/test/test_emails.py
+++ b/posthog/test/test_emails.py
@@ -3,9 +3,11 @@
import asyncio
import json
import logging
+import threading
from datetime import datetime, timezone
from decimal import Decimal
-from typing import Any, Optional, Union
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, Iterator, Optional, Union
from unittest import mock
import httpx
@@ -693,11 +695,88 @@ def test_rendered_content_is_posted_as_is(_name, overrides, extra_body):
"to": "user@example.com",
"template_key": "password-reset",
"subject": "Reset your password",
- "capture_engagement": True,
**extra_body,
}
+class _CaptureServer(HTTPServer):
+ received: list[Any]
+
+
+class _CaptureHandler(BaseHTTPRequestHandler):
+ server: _CaptureServer
+
+ def do_POST(self) -> None:
+ body = self.rfile.read(int(self.headers["Content-Length"]))
+ self.server.received.append(json.loads(body))
+ reply = json.dumps({"message_id": "msg_1", "replayed": False}).encode()
+ self.send_response(202)
+ self.send_header("Content-Type", "application/json")
+ self.send_header("Content-Length", str(len(reply)))
+ self.end_headers()
+ self.wfile.write(reply)
+
+ def log_message(self, *args: Any) -> None:
+ pass
+
+
+@pytest.fixture
+def capture_server() -> Iterator[_CaptureServer]:
+ server = _CaptureServer(("127.0.0.1", 0), _CaptureHandler)
+ server.received = []
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
+ thread.start()
+ yield server
+ server.shutdown()
+ server.server_close()
+
+
+@pytest.mark.parametrize(
+ "overrides, extra_body",
+ [
+ pytest.param({}, {}, id="no_tracking_or_sensitive_choice"),
+ pytest.param(
+ {"tracking": None, "capture_engagement": None, "sensitive": None},
+ {},
+ id="none_as_left_out",
+ ),
+ pytest.param({"sensitive": True}, {"sensitive": True}, id="marked_sensitive"),
+ pytest.param(
+ {"sensitive": False}, {"sensitive": False}, id="marked_not_sensitive"
+ ),
+ pytest.param({"tracking": False}, {"tracking": False}, id="all_tracking_off"),
+ pytest.param({"tracking": True}, {"tracking": True}, id="all_tracking_on"),
+ pytest.param(
+ {"tracking": {"opens": True, "clicks": True, "engagement": False}},
+ {"tracking": {"opens": True, "clicks": True, "engagement": False}},
+ id="each_kind_of_tracking_chosen",
+ ),
+ pytest.param(
+ {"capture_engagement": False},
+ {"capture_engagement": False},
+ id="deprecated_capture_engagement",
+ ),
+ ],
+)
+def test_a_code_send_delivers_its_tracking_and_sensitive_choice(
+ capture_server, overrides, extra_body
+):
+ host = f"http://127.0.0.1:{capture_server.server_port}"
+ with Emails(SECRET_KEY, host=host) as emails:
+ result = send_code(emails, html=HTML, **overrides)
+
+ assert result.id == "msg_1"
+ assert capture_server.received == [
+ {
+ "to": "user@example.com",
+ "template_key": "password-reset",
+ "subject": "Reset your password",
+ "html": HTML,
+ **extra_body,
+ }
+ ]
+
+
@pytest.mark.asyncio
async def test_async_client_posts_rendered_content_and_names_the_provider():
seen: list[httpx.Request] = []
@@ -782,6 +861,28 @@ def handler(request: httpx.Request) -> httpx.Response:
},
TypeError,
),
+ (
+ "tracking_on_template_form",
+ {
+ "template_id": TEMPLATE_ID,
+ "template_key": None,
+ "subject": None,
+ "tracking": False,
+ },
+ TypeError,
+ ),
+ (
+ "sensitive_on_template_form",
+ {
+ "template_id": TEMPLATE_ID,
+ "template_key": None,
+ "subject": None,
+ "sensitive": False,
+ },
+ TypeError,
+ ),
+ ("tracking_not_bool_or_dict", {"html": HTML, "tracking": "off"}, TypeError),
+ ("sensitive_not_bool", {"html": HTML, "sensitive": "yes"}, TypeError),
]
)
def test_rejects_a_code_send_that_mixes_or_misses_fields(_name, overrides, error):
diff --git a/references/public_api_snapshot.txt b/references/public_api_snapshot.txt
index bfffd5d64..064d08788 100644
--- a/references/public_api_snapshot.txt
+++ b/references/public_api_snapshot.txt
@@ -892,9 +892,11 @@ attribute posthog.emails.CodeEmailArgs.capture_engagement: NotRequired[Optional[
attribute posthog.emails.CodeEmailArgs.from_: NotRequired[Optional[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]]
attribute posthog.emails.CodeEmailArgs.subject: str
attribute posthog.emails.CodeEmailArgs.template_key: str
attribute posthog.emails.CodeEmailArgs.text: NotRequired[Optional[str]]
+attribute posthog.emails.CodeEmailArgs.tracking: NotRequired[Optional[Union[bool, EmailTracking]]]
attribute posthog.emails.EmailError.code = code
attribute posthog.emails.EmailError.docs_url = docs_url
attribute posthog.emails.EmailError.field = field
@@ -909,6 +911,9 @@ attribute posthog.emails.EmailStatus.id: str
attribute posthog.emails.EmailStatus.reason: Optional[str] = None
attribute posthog.emails.EmailStatus.status: str
attribute posthog.emails.EmailStatus.status_at: datetime
+attribute posthog.emails.EmailTracking.clicks: bool
+attribute posthog.emails.EmailTracking.engagement: bool
+attribute posthog.emails.EmailTracking.opens: bool
attribute posthog.emails.EmailWarning.code: str
attribute posthog.emails.EmailWarning.fix: Optional[str] = None
attribute posthog.emails.EmailWarning.message: str
@@ -1346,6 +1351,7 @@ class posthog.emails.AsyncEmails(secret_key: Optional[str], *, host: Optional[st
class posthog.emails.CodeEmailArgs
class posthog.emails.EmailError(*, name: str, code: str, message: str, status_code: Optional[int] = None, why: Optional[str] = None, fix: Optional[str] = None, docs_url: Optional[str] = None, field: Optional[str] = None, retry_after: Optional[float] = None)
class posthog.emails.EmailStatus(id: str, status: str, created_at: datetime, status_at: datetime, reason: Optional[str] = None)
+class posthog.emails.EmailTracking
class posthog.emails.EmailWarning(code: str, message: str, fix: Optional[str] = None)
class posthog.emails.Emails(secret_key: Optional[str], *, host: Optional[str] = None, timeout: float = 15, max_retries: int = 2, disabled: bool = False, session: Optional[requests.Session] = None, migrated_from: Optional[str] = None)
class posthog.emails.SendEmailResult(id: str, replayed: bool = False, warnings: tuple[EmailWarning, ...] = ())