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, ...] = ())