Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion .github/scripts/check_strict_types.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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="<p>Reset</p>", from_="Acme <security@example.com>", 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="<p>Hi</p>", tracking={"clicks": True, "engagement": False})
untracked_send: SendEmailResult = emails.send(to="user@example.com", template_key="welcome", subject="Welcome", html="<p>Hi</p>", tracking=False)
not_sensitive_send: SendEmailResult = emails.send(to="user@example.com", template_key="newsletter", subject="News", html="<p>News</p>", sensitive=False)
_ = (template_send, rendered_send, tracked_send, untracked_send)


async def async_email_types() -> None:
Expand Down Expand Up @@ -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="<p>Hi</p>") # 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="<p>Hi</p>", tracking={"open": False}) # expected-type-error
Emails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="<p>Hi</p>", template_data={"name": "Ada"}) # expected-type-error
Emails("phs_example").send(to="user@example.com", template_key="welcome", subject="Hi", html="<p>Hi</p>", cc="team@example.com") # expected-type-error

Expand Down
23 changes: 23 additions & 0 deletions .sampo/changesets/emails-tracking.md
Original file line number Diff line number Diff line change
@@ -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.
78 changes: 69 additions & 9 deletions posthog/emails.py
Original file line number Diff line number Diff line change
Expand Up @@ -131,6 +131,7 @@
"CodeEmailArgs",
"EmailError",
"EmailStatus",
"EmailTracking",
"EmailWarning",
"Emails",
"SendEmailResult",
Expand Down Expand Up @@ -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.

Expand All @@ -260,11 +283,31 @@ class CodeEmailArgs(_RecipientArgs):
without a plain-text part.
from_: A verified sender, such as ``"Acme <hello@example.com>"``.
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
Expand All @@ -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(
Expand All @@ -291,6 +336,8 @@ class CodeEmailArgs(_RecipientArgs):
"from_",
"reply_to",
"capture_engagement",
"sensitive",
"tracking",
}
)

Expand Down Expand Up @@ -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]
Comment thread
Silthus marked this conversation as resolved.
Resolved
if "tracking" in args:
sender["tracking"] = _tracking(args["tracking"])
Comment thread
Silthus marked this conversation as resolved.
Resolved
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(
Expand Down
105 changes: 103 additions & 2 deletions posthog/test/test_emails.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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] = []
Expand Down Expand Up @@ -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):
Expand Down
6 changes: 6 additions & 0 deletions references/public_api_snapshot.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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, ...] = ())
Expand Down
Loading