Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend): send Postmark email deliveries, opens, clicks and bounces to PostHog (#15850)

Krzysztof Czerwinski046a4472b6b4
diff --git a/autogpt_platform/backend/.env.default b/autogpt_platform/backend/.env.default
index d97d56ad78..41d2748a93 100644
--- a/autogpt_platform/backend/.env.default
+++ b/autogpt_platform/backend/.env.default
@@ -260,6 +260,9 @@ [email protected]
OPS_SENDER_EMAIL=AutoGPT Platform <[email protected]>
POSTMARK_TRANSACTIONAL_STREAM=outbound
+# Track opens and clicks in notification emails (never in auth emails), so the
+# Postmark webhook can send email_opened / email_clicked to PostHog.
+POSTMARK_TRACK_OPENS_AND_CLICKS=false
# Hero art and the logo are hosted images: Outlook does not render inline SVG
# and Gmail does not display data-URI images. The logo is served from this
diff --git a/autogpt_platform/backend/backend/api/features/postmark/analytics.py b/autogpt_platform/backend/backend/api/features/postmark/analytics.py
new file mode 100644
index 0000000000..0156827e92
--- /dev/null
+++ b/autogpt_platform/backend/backend/api/features/postmark/analytics.py
@@ -0,0 +1,121 @@
+"""PostHog events for what Postmark reports about an email we sent.
+
+The webhook handler finds the user the email went to and calls
+:func:`track_email_event`. The recipient address itself never reaches PostHog:
+the user id is the distinct id, and a clicked link keeps only its scheme, host
+and path, with any path segment that isn't a plain lower-case word replaced
+by ``:id``.
+"""
+
+import hashlib
+import logging
+import re
+from datetime import datetime
+from urllib.parse import urlsplit
+
+from backend.util.posthog_events import PostHogEvent
+from backend.util.product_analytics import track
+
+from .models import (
+ PostmarkBounceWebhook,
+ PostmarkClickWebhook,
+ PostmarkDeliveryWebhook,
+ PostmarkOpenWebhook,
+)
+
+logger = logging.getLogger(__name__)
+
+EmailWebhook = (
+ PostmarkDeliveryWebhook
+ | PostmarkOpenWebhook
+ | PostmarkClickWebhook
+ | PostmarkBounceWebhook
+)
+
+ID_SEGMENT = ":id"
+
+# The path segments a link keeps: lower-case words and slugs. Anything else
+# (an email address, a capitalised or percent-encoded token) becomes ``:id``.
+_PLAIN_SEGMENT_RE = re.compile(r"[a-z0-9._-]*")
+# A plain segment this long with a digit in it is an id or a code (a UUID),
+# and one longer still is a token whatever it holds.
+_ID_LIKE_RE = re.compile(r"(?=.*\d).{16,}")
+_ID_LIKE_MIN_ANY = 32
+
+
+def track_email_event(
+ user_id: str,
+ event: PostHogEvent,
+ webhook: EmailWebhook,
+ *,
+ occurred_at: str,
+ properties: dict[str, object] | None = None,
+) -> None:
+ """Send *event* for one Postmark webhook, at the time Postmark reports.
+
+ Keyed on the message, the record type and that time, plus a hash of the
+ link for a click, so a webhook Postmark redelivers is merged with the
+ first one rather than counted twice.
+ """
+ dedup_key = f"{webhook.MessageID}:{webhook.RecordType}:{occurred_at}"
+ if isinstance(webhook, PostmarkClickWebhook):
+ link_hash = hashlib.sha256(webhook.OriginalLink.encode()).hexdigest()
+ dedup_key = f"{dedup_key}:{link_hash[:16]}"
+ track(
+ user_id,
+ event,
+ {
+ # The tag the email was sent with: its notification type.
+ "email_type": webhook.Tag or None,
+ "message_stream": webhook.MessageStream,
+ "message_id": webhook.MessageID,
+ **(properties or {}),
+ },
+ dedup_key=dedup_key,
+ timestamp=parse_postmark_time(occurred_at),
+ )
+
+
+def parse_postmark_time(value: str) -> datetime | None:
+ """Postmark's ISO 8601 times (``2019-11-05T16:33:54.9070259Z``), or None
+ when one can't be read, so the event takes the time it was received."""
+ try:
+ return datetime.fromisoformat(value)
+ except ValueError:
+ logger.warning("Unreadable Postmark timestamp %r", value)
+ return None
+
+
+def safe_link(url: str) -> str | None:
+ """The clicked link without anything that could identify a person or
+ carry a secret: no query string, fragment, credentials, ids or any path
+ segment that isn't a plain lower-case word.
+
+ Only web links keep a host and path; any other scheme keeps just its
+ name, since a ``mailto:`` link's path is an email address.
+ """
+ try:
+ parts = urlsplit(url.strip())
+ host = parts.hostname
+ port = parts.port
+ except ValueError:
+ return None
+ scheme = parts.scheme.lower()
+ if scheme not in ("http", "https"):
+ return f"{scheme}:" if scheme else None
+ if not host:
+ return None
+ netloc = f"{host}:{port}" if port else host
+ path = "/".join(
+ segment if _is_plain(segment) else ID_SEGMENT
+ for segment in parts.path.split("/")
+ )
+ return f"{scheme}://{netloc}{path}"
+
+
+def _is_plain(segment: str) -> bool:
+ return (
+ bool(_PLAIN_SEGMENT_RE.fullmatch(segment))
+ and len(segment) < _ID_LIKE_MIN_ANY
+ and not _ID_LIKE_RE.fullmatch(segment)
+ )
diff --git a/autogpt_platform/backend/backend/api/features/postmark/postmark.py b/autogpt_platform/backend/backend/api/features/postmark/postmark.py
index 6567cb866f..ca708285f0 100644
--- a/autogpt_platform/backend/backend/api/features/postmark/postmark.py
+++ b/autogpt_platform/backend/backend/api/features/postmark/postmark.py
@@ -1,5 +1,6 @@
import logging
-from typing import Annotated
+from types import TracebackType
+from typing import Annotated, Self
from fastapi import APIRouter, Body, Query, Security
from fastapi.responses import JSONResponse
@@ -10,8 +11,10 @@ from backend.data.user import (
set_user_email_verification,
unsubscribe_user_by_token,
)
+from backend.util.posthog_events import PostHogEvent
from backend.util.settings import Settings
+from .analytics import safe_link, track_email_event
from .models import (
PostmarkBounceEnum,
PostmarkBounceWebhook,
@@ -52,18 +55,65 @@ async def postmark_webhook_handler(
Body(discriminator="RecordType"),
]
):
- logger.info(f"Received webhook from Postmark: {webhook}")
+ # The payload holds the recipient's address; keep it out of the logs.
+ logger.info(
+ "Received %s webhook from Postmark for message %s",
+ webhook.RecordType,
+ webhook.MessageID,
+ )
+ with _RetryOnFailure(webhook) as boundary:
+ await _handle(webhook)
+ if boundary.failed:
+ return JSONResponse(status_code=503, content={"status": "retry"})
+
+
+class _RetryOnFailure:
+ """Turns any failure while handling a webhook into a retry, without the
+ failure reaching Sentry.
+
+ Neither re-raised nor logged with its traceback: Sentry would send every
+ frame's locals, and the webhook in them holds the recipient's address.
+ Only the record type, message id and error type are logged; Postmark
+ retries anything but a 200. Cancellation still propagates.
+ """
+
+ def __init__(self, webhook: PostmarkWebhook):
+ self.webhook = webhook
+ self.failed = False
+
+ def __enter__(self) -> Self:
+ return self
+
+ def __exit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc: BaseException | None,
+ tb: TracebackType | None,
+ ) -> bool:
+ if exc_type is None or not issubclass(exc_type, Exception):
+ return False
+ logger.error(
+ "Postmark %s webhook for message %s failed: %s",
+ self.webhook.RecordType,
+ self.webhook.MessageID,
+ exc_type.__name__,
+ )
+ self.failed = True
+ return True
+
+
+async def _handle(webhook: PostmarkWebhook) -> None:
match webhook:
case PostmarkDeliveryWebhook():
- delivery_handler(webhook)
+ await delivery_handler(webhook)
case PostmarkBounceWebhook():
await bounce_handler(webhook)
case PostmarkSpamComplaintWebhook():
spam_handler(webhook)
case PostmarkOpenWebhook():
- open_handler(webhook)
+ await open_handler(webhook)
case PostmarkClickWebhook():
- click_handler(webhook)
+ await click_handler(webhook)
case PostmarkSubscriptionChangeWebhook():
subscription_handler(webhook)
case _:
@@ -71,52 +121,79 @@ async def postmark_webhook_handler(
"Unhandled Postmark webhook type %s. Update handler mappings.",
type(webhook),
)
- return
+
+
+async def _user_id_for(recipient: str, message_id: str) -> str | None:
+ """The user an email went to, or None for an address with no account,
+ such as the internal Ops inbox."""
+ user = await get_user_by_email(recipient)
+ if not user:
+ logger.info("Postmark message %s went to no known user", message_id)
+ return None
+ return user.id
async def bounce_handler(event: PostmarkBounceWebhook):
- logger.info(f"Bounce handler {event=}")
+ user_id = await _user_id_for(event.Email, event.MessageID)
+ if not user_id:
+ return
+ track_email_event(
+ user_id,
+ PostHogEvent.EMAIL_BOUNCED,
+ event,
+ occurred_at=event.BouncedAt,
+ properties={"bounce_type": event.Type},
+ )
if event.TypeCode in [
PostmarkBounceEnum.Transient,
PostmarkBounceEnum.SoftBounce,
PostmarkBounceEnum.DnsError,
]:
logger.info(
- f"Softish bounce: {event.TypeCode} for {event.Email}, not setting email verification to false"
+ "Softish bounce %s for user %s, not setting email verification to false",
+ event.TypeCode,
+ user_id,
)
return
- logger.info(f"{event.Email=}")
- user = await get_user_by_email(event.Email)
- if not user:
- logger.warning(
- "Received bounce for unknown email %s. Ensure user records are current.",
- event.Email,
- )
- return
- await set_user_email_verification(user.id, False)
- logger.debug(f"Setting email verification to false for user: {user.id}")
+ await set_user_email_verification(user_id, False)
+ logger.debug(f"Setting email verification to false for user: {user_id}")
def spam_handler(event: PostmarkSpamComplaintWebhook):
logger.info("Spam handler")
- pass
-def delivery_handler(event: PostmarkDeliveryWebhook):
- logger.info("Delivery handler")
- pass
+async def delivery_handler(event: PostmarkDeliveryWebhook):
+ if user_id := await _user_id_for(event.Recipient, event.MessageID):
+ track_email_event(
+ user_id,
+ PostHogEvent.EMAIL_DELIVERED,
+ event,
+ occurred_at=event.DeliveredAt,
+ )
-def open_handler(event: PostmarkOpenWebhook):
- logger.info("Open handler")
- pass
+async def open_handler(event: PostmarkOpenWebhook):
+ if user_id := await _user_id_for(event.Recipient, event.MessageID):
+ track_email_event(
+ user_id,
+ PostHogEvent.EMAIL_OPENED,
+ event,
+ occurred_at=event.ReceivedAt,
+ properties={"first_open": event.FirstOpen},
+ )
-def click_handler(event: PostmarkClickWebhook):
- logger.info("Click handler")
- pass
+async def click_handler(event: PostmarkClickWebhook):
+ if user_id := await _user_id_for(event.Recipient, event.MessageID):
+ track_email_event(
+ user_id,
+ PostHogEvent.EMAIL_CLICKED,
+ event,
+ occurred_at=event.ReceivedAt,
+ properties={"link": safe_link(event.OriginalLink)},
+ )
def subscription_handler(event: PostmarkSubscriptionChangeWebhook):
logger.info("Subscription handler")
- pass
diff --git a/autogpt_platform/backend/backend/api/features/postmark/webhook_test.py b/autogpt_platform/backend/backend/api/features/postmark/webhook_test.py
new file mode 100644
index 0000000000..ad87db732d
--- /dev/null
+++ b/autogpt_platform/backend/backend/api/features/postmark/webhook_test.py
@@ -0,0 +1,327 @@
+"""Postmark's delivery, open, click and bounce webhooks become PostHog events
+for the user the email went to, without the address and without link secrets."""
+
+from datetime import UTC, datetime
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock
+
+import fastapi
+import fastapi.testclient
+import pytest
+
+from backend.util import posthog_client
+
+from . import postmark
+from .analytics import parse_postmark_time, safe_link
+
+TOKEN = "test-webhook-token"
+USER_ID = "3e53486c-cf57-477e-ba2a-cb02dc828e1a"
+RECIPIENT = "[email protected]"
+MESSAGE_ID = "883953f4-6105-42a2-a16a-77a8eac79483"
+
+app = fastapi.FastAPI()
+app.include_router(postmark.router)
+client = fastapi.testclient.TestClient(app)
+
+
[email protected](autouse=True)
+def webhook_token(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(postmark.postmark_api_key_auth, "expected_token", TOKEN)
+
+
+def posthog(monkeypatch: pytest.MonkeyPatch) -> Mock:
+ posthog = Mock()
+ monkeypatch.setattr(posthog_client, "get_posthog_client", lambda: posthog)
+ monkeypatch.setattr(posthog_client, "_environment", lambda: "local")
+ return posthog
+
+
+def lookup(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
+ lookup = AsyncMock(return_value=SimpleNamespace(id=USER_ID))
+ monkeypatch.setattr(postmark, "get_user_by_email", lookup)
+ return lookup
+
+
+def unverify(monkeypatch: pytest.MonkeyPatch) -> AsyncMock:
+ unverify = AsyncMock()
+ monkeypatch.setattr(postmark, "set_user_email_verification", unverify)
+ return unverify
+
+
+def test_a_delivery_is_sent_for_the_recipients_user(posthog: Mock, lookup: AsyncMock):
+ _post(_delivery())
+
+ lookup.assert_awaited_once_with(RECIPIENT)
+ call = posthog.capture.call_args.kwargs
+ assert call["distinct_id"] == USER_ID
+ assert call["event"] == "email_delivered"
+ assert call["timestamp"] == datetime(2019, 11, 5, 16, 33, 54, 907025, tzinfo=UTC)
+ properties = call["properties"]
+ assert properties["email_type"] == "briefing"
+ assert properties["message_stream"] == "outbound"
+ assert properties["message_id"] == MESSAGE_ID
+ assert RECIPIENT not in str(call)
+
+
+def test_an_open_carries_whether_it_was_the_first(posthog: Mock, lookup: AsyncMock):
+ _post(_open())
+
+ call = posthog.capture.call_args.kwargs
+ assert call["event"] == "email_opened"
+ assert call["properties"]["first_open"] is True
+ assert "Geo" not in str(call) and "188.2.95.4" not in str(call)
+ assert RECIPIENT not in str(call)
+
+
+def test_a_click_keeps_only_the_links_scheme_host_and_path(
+ posthog: Mock, lookup: AsyncMock
+):
+ _post(
+ _click(
+ "https://platform.agpt.co/library/agents/"
+ "8f14e45f-ceea-467a-9575-0d7e1b2c3a4f?executionId=1#top"
+ )
+ )
+
+ call = posthog.capture.call_args.kwargs
+ assert call["event"] == "email_clicked"
+ assert call["properties"]["link"] == "https://platform.agpt.co/library/agents/:id"
+
+
+def test_a_hard_bounce_is_sent_and_unverifies_the_address(
+ posthog: Mock, lookup: AsyncMock, unverify: AsyncMock
+):
+ _post(_bounce(type_name="HardBounce", type_code=1))
+
+ call = posthog.capture.call_args.kwargs
+ assert call["event"] == "email_bounced"
+ assert call["properties"]["bounce_type"] == "HardBounce"
+ assert RECIPIENT not in str(call)
+ unverify.assert_awaited_once_with(USER_ID, False)
+
+
+def test_a_soft_bounce_is_sent_but_keeps_the_address_verified(
+ posthog: Mock, lookup: AsyncMock, unverify: AsyncMock
+):
+ _post(_bounce(type_name="SoftBounce", type_code=4096))
+
+ assert posthog.capture.call_args.kwargs["properties"]["bounce_type"] == (
+ "SoftBounce"
+ )
+ unverify.assert_not_awaited()
+
+
[email protected]("record_type", ["Delivery", "Open", "Click", "Bounce"])
+def test_an_address_with_no_account_sends_nothing(
+ record_type: str, posthog: Mock, lookup: AsyncMock, unverify: AsyncMock
+):
+ lookup.return_value = None
+ payload = {
+ "Delivery": _delivery,
+ "Open": _open,
+ "Click": lambda: _click("https://platform.agpt.co/copilot"),
+ "Bounce": lambda: _bounce(type_name="HardBounce", type_code=1),
+ }[record_type]()
+
+ _post(payload)
+
+ posthog.capture.assert_not_called()
+ unverify.assert_not_awaited()
+
+
+def test_a_redelivered_webhook_is_the_same_event(posthog: Mock, lookup: AsyncMock):
+ _post(_open())
+ _post(_open())
+ _post(_open(received_at="2019-11-05T16:40:00.0000000Z"))
+
+ first, retry, later = (c.kwargs for c in posthog.capture.call_args_list)
+ assert first["uuid"] == retry["uuid"]
+ assert first["timestamp"] == retry["timestamp"]
+ assert later["uuid"] != first["uuid"]
+
+
[email protected]("failing", ["lookup", "unverify"])
+def test_a_failure_asks_postmark_to_retry_without_the_address(
+ failing: str,
+ posthog: Mock,
+ lookup: AsyncMock,
+ unverify: AsyncMock,
+ caplog: pytest.LogCaptureFixture,
+):
+ """Not raised: Sentry would send the frames' locals, which hold the
+ webhook and so the address."""
+ error = RuntimeError(f"connection reset while reading {RECIPIENT}")
+ (lookup if failing == "lookup" else unverify).side_effect = error
+
+ response = client.post(
+ "/",
+ json=_bounce(type_name="HardBounce", type_code=1),
+ headers={"X-Postmark-Webhook-Token": TOKEN},
+ )
+
+ assert response.status_code == 503
+ assert RECIPIENT not in response.text
+ failures = [r for r in caplog.records if r.levelname == "ERROR"]
+ assert len(failures) == 1
+ assert failures[0].exc_info is None
+ assert MESSAGE_ID in failures[0].getMessage()
+ assert RECIPIENT not in caplog.text
+
+
+def test_two_links_clicked_at_once_are_two_events(posthog: Mock, lookup: AsyncMock):
+ _post(_click("https://platform.agpt.co/copilot"))
+ _post(_click("https://platform.agpt.co/library"))
+
+ first, second = (c.kwargs for c in posthog.capture.call_args_list)
+ assert first["uuid"] != second["uuid"]
+ assert "platform.agpt.co" not in first["properties"]["$insert_id"]
+
+
+def test_an_untagged_email_sends_no_email_type(posthog: Mock, lookup: AsyncMock):
+ _post({**_delivery(), "Tag": ""})
+
+ assert "email_type" not in posthog.capture.call_args.kwargs["properties"]
+
+
[email protected]("headers", [{}, {"X-Postmark-Webhook-Token": "wrong"}])
+def test_a_request_without_the_webhook_token_is_refused(
+ headers: dict[str, str], posthog: Mock, lookup: AsyncMock
+):
+ response = client.post("/", json=_open(), headers=headers)
+
+ assert response.status_code == 401
+ lookup.assert_not_awaited()
+ posthog.capture.assert_not_called()
+
+
+ "url,expected",
+ [
+ ("https://platform.agpt.co/copilot", "https://platform.agpt.co/copilot"),
+ (
+ "https://platform.agpt.co/settings/account?f=weekly",
+ "https://platform.agpt.co/settings/account",
+ ),
+ (
+ "https://platform.agpt.co/api/email/unsubscribe?token=abc",
+ "https://platform.agpt.co/api/email/unsubscribe",
+ ),
+ (
+ "https://platform.agpt.co/reset-password/Kq8sPzLmWvTnRbYxHdJcFgAe",
+ "https://platform.agpt.co/reset-password/:id",
+ ),
+ (
+ "https://platform.agpt.co/reset-password/kqsplmwvtnrbyxhdjcfgaeqwertyuiop",
+ "https://platform.agpt.co/reset-password/:id",
+ ),
+ (
+ "https://platform.agpt.co/marketplace/agent/autogpt/blog-writer",
+ "https://platform.agpt.co/marketplace/agent/autogpt/blog-writer",
+ ),
+ (
+ "https://example.com/members/[email protected]/profile",
+ "https://example.com/members/:id/profile",
+ ),
+ (
+ "https://example.com/members/alice%40example.com",
+ "https://example.com/members/:id",
+ ),
+ ("https://example.com/Tok", "https://example.com/:id"),
+ (
+ "HTTPS://user:[email protected]:8443/x",
+ "https://platform.agpt.co:8443/x",
+ ),
+ ("mailto:[email protected]", "mailto:"),
+ ("not a link", None),
+ ("https://[::1", None),
+ ],
+)
+def test_safe_link(url: str, expected: str | None):
+ assert safe_link(url) == expected
+
+
+def test_an_unreadable_postmark_time_falls_back_to_now():
+ assert parse_postmark_time("yesterday") is None
+
+
+def _post(payload: dict) -> None:
+ response = client.post(
+ "/", json=payload, headers={"X-Postmark-Webhook-Token": TOKEN}
+ )
+ assert response.status_code == 200, response.text
+
+
+def _delivery() -> dict:
+ return {
+ "RecordType": "Delivery",
+ "ServerID": 23,
+ "MessageStream": "outbound",
+ "MessageID": MESSAGE_ID,
+ "Recipient": RECIPIENT,
+ "Tag": "briefing",
+ "DeliveredAt": "2019-11-05T16:33:54.9070259Z",
+ "Details": "Test delivery webhook details",
+ "Metadata": {},
+ }
+
+
+def _engagement(received_at: str) -> dict:
+ return {
+ "MessageStream": "outbound",
+ "Metadata": {},
+ "Recipient": RECIPIENT,
+ "MessageID": MESSAGE_ID,
+ "ReceivedAt": received_at,
+ "Platform": "WebMail",
+ "Tag": "alert",
+ "UserAgent": "Mozilla/5.0",
+ "OS": {"Name": "OS X 10.7 Lion", "Family": "OS X 10", "Company": "Apple"},
+ "Client": {"Name": "Chrome 35.0", "Family": "Chrome", "Company": "Google"},
+ "Geo": {"Country": "Serbia", "City": "Novi Sad", "IP": "188.2.95.4"},
+ }
+
+
+def _open(received_at: str = "2019-11-05T16:33:54.9070259Z") -> dict:
+ return {
+ **_engagement(received_at),
+ "RecordType": "Open",
+ "FirstOpen": True,
+ "ReadSeconds": 5,
+ }
+
+
+def _click(link: str) -> dict:
+ return {
+ **_engagement("2019-11-05T16:35:00.0000000Z"),
+ "RecordType": "Click",
+ "ClickLocation": "HTML",
+ "OriginalLink": link,
+ }
+
+
+def _bounce(*, type_name: str, type_code: int) -> dict:
+ return {
+ "RecordType": "Bounce",
+ "ID": 42,
+ "Type": type_name,
+ "TypeCode": type_code,
+ "Tag": "trial_update",
+ "MessageID": MESSAGE_ID,
+ "Details": "Test bounce details",
+ "Email": RECIPIENT,
+ "From": "[email protected]",
+ "BouncedAt": "2019-11-05T16:33:54.9070259Z",
+ "Inactive": True,
+ "DumpAvailable": False,
+ "CanActivate": True,
+ "Subject": "Your trial",
+ "ServerID": 23,
+ "MessageStream": "outbound",
+ "Content": "",
+ "Name": "Hard bounce",
+ "Description": "The server was unable to deliver your message.",
+ "Metadata": {},
+ }
diff --git a/autogpt_platform/backend/backend/data/user.py b/autogpt_platform/backend/backend/data/user.py
index f1d1e51ec1..00b17bc490 100644
--- a/autogpt_platform/backend/backend/data/user.py
+++ b/autogpt_platform/backend/backend/data/user.py
@@ -375,7 +375,8 @@ async def get_user_by_email(email: str) -> Optional[User]:
user = await prisma.user.find_unique(where={"email": email})
return User.from_db(user) if user else None
except Exception as e:
- raise DatabaseError(f"Failed to get user by email {email}: {e}") from e
+ # Not the address: this message reaches logs and Sentry.
+ raise DatabaseError(f"Failed to get user by email: {e}") from e
async def search_users(query: str, limit: int = 20) -> list[tuple[str, str | None]]:
diff --git a/autogpt_platform/backend/backend/notifications/email.py b/autogpt_platform/backend/backend/notifications/email.py
index b85379db12..733345f0ae 100644
--- a/autogpt_platform/backend/backend/notifications/email.py
+++ b/autogpt_platform/backend/backend/notifications/email.py
@@ -5,10 +5,18 @@ Everything goes out on a transactional stream, separate from marketing mail
changelog are MailerLite's). Every message carries a plain-text MIME part built
from the same data model. Product notifications carry one-click
List-Unsubscribe headers; billing, auth and internal Ops mail do not.
+
+Each message is tagged with what it is (the notification type, or ``auth``).
+Postmark echoes the tag in its delivery, open, click and bounce webhooks,
+which ``api/features/postmark`` turns into PostHog events. Every message also
+says whether Postmark tracks its opens and clicks, so the stream's own default
+never decides: notification mail follows ``postmark_track_opens_and_clicks``,
+and auth mail is never tracked, since its links carry sign-in tokens.
"""
import asyncio
import logging
+from typing import Any
from postmarker.core import PostmarkClient
from postmarker.models.emails import EmailManager
@@ -29,6 +37,9 @@ settings = Settings()
# Bounds how long one send can hold a thread-pool worker.
POSTMARK_TIMEOUT_SECONDS = 30
+# Postmark tag for Better Auth's emails, which are not notifications.
+AUTH_EMAIL_TAG = "auth"
+
class TypedPostmarkClient(PostmarkClient):
"""Workaround so the type checker sees `emails`; the Postmark library ships
@@ -86,6 +97,7 @@ class EmailSender:
stream = get_delivery_stream(notification_type)
await self._send(
user_email=user_email,
+ tag=notification_type.value.lower(),
sender=_sender_for(stream),
reply_to=_reply_to_for(stream),
subject=email.subject,
@@ -110,11 +122,16 @@ class EmailSender:
HtmlBody=body,
TextBody=text_body,
MessageStream=settings.config.postmark_transactional_stream,
+ Tag=AUTH_EMAIL_TAG,
+ # A reset or verification link holds a token; link tracking would
+ # route it through Postmark's redirect and into the click webhook.
+ **_tracking(False),
)
async def _send(
self,
user_email: str,
+ tag: str,
sender: str,
subject: str,
html_body: str,
@@ -138,9 +155,20 @@ class EmailSender:
TextBody=text_body,
MessageStream=settings.config.postmark_transactional_stream,
Headers=headers,
+ Tag=tag,
+ **_tracking(settings.config.postmark_track_opens_and_clicks),
)
+def _tracking(enabled: bool) -> dict[str, Any]:
+ """Postmark's per-message tracking fields. Links are rewritten in the
+ HTML part only: a rewritten link in the plain-text part is a long opaque
+ redirect a reader can't check before following."""
+ if enabled:
+ return {"TrackOpens": True, "TrackLinks": "HtmlOnly"}
+ return {"TrackOpens": False, "TrackLinks": "None"}
+
+
def _sender_for(stream: DeliveryStream) -> str:
return {
DeliveryStream.BILLING: settings.config.billing_sender_email,
diff --git a/autogpt_platform/backend/backend/notifications/email_test.py b/autogpt_platform/backend/backend/notifications/email_test.py
index 57d1eb54ff..629ca9da19 100644
--- a/autogpt_platform/backend/backend/notifications/email_test.py
+++ b/autogpt_platform/backend/backend/notifications/email_test.py
@@ -48,6 +48,7 @@ async def test_reply_to_preserves_configured_sender_and_stream(
assert envelope["MessageStream"] == "service"
assert envelope["HtmlBody"] == message.html
assert envelope["TextBody"] == message.text
+ assert envelope["Tag"] == notification_type.value.lower()
if notification_type == NotificationType.PAYMENT_FAILED:
assert not envelope["Headers"]
else:
@@ -80,6 +81,44 @@ def test_auth_delivery_includes_text_without_unsubscribe(monkeypatch):
assert envelope["TextBody"] == "Verify: https://example.org/verify?token=abc"
assert not envelope.get("Headers")
assert not envelope.get("ReplyTo")
+ assert envelope["Tag"] == "auth"
+
+
[email protected]("enabled", [True, False])
+async def test_notification_tracking_follows_the_setting(monkeypatch, enabled):
+ monkeypatch.setattr(
+ delivery.settings.config, "postmark_track_opens_and_clicks", enabled
+ )
+ sender = delivery.EmailSender.__new__(delivery.EmailSender)
+ sender.postmark = MagicMock()
+
+ await sender._deliver(
+ NotificationType.BRIEFING,
+ RenderedEmail(subject="Brief", preheader="Brief", html="<p>B</p>", text="B"),
+ build_urls("https://example.org/unsubscribe"),
+ )
+
+ envelope = sender.postmark.emails.send.call_args.kwargs
+ assert envelope["TrackOpens"] is enabled
+ assert envelope["TrackLinks"] == ("HtmlOnly" if enabled else "None")
+
+
+def test_auth_mail_is_never_tracked(monkeypatch):
+ """Its links carry sign-in tokens, which link tracking would hand to the
+ click webhook."""
+ monkeypatch.setattr(
+ delivery.settings.config, "postmark_track_opens_and_clicks", True
+ )
+ sender = delivery.EmailSender.__new__(delivery.EmailSender)
+ sender.postmark = MagicMock()
+
+ sender.send_email_or_raise("[email protected]", "Reset", "<p>Reset</p>")
+
+ envelope = sender.postmark.emails.send.call_args.kwargs
+ assert envelope["TrackOpens"] is False
+ assert envelope["TrackLinks"] == "None"
@pytest.mark.asyncio
diff --git a/autogpt_platform/backend/backend/util/funnel_analytics_test.py b/autogpt_platform/backend/backend/util/funnel_analytics_test.py
index 26e74e0aa8..5796ffa2a2 100644
--- a/autogpt_platform/backend/backend/util/funnel_analytics_test.py
+++ b/autogpt_platform/backend/backend/util/funnel_analytics_test.py
@@ -19,6 +19,7 @@ def test_captures_to_posthog_with_the_user_as_distinct_id():
distinct_id="user-1",
properties={"template_id": "tpl-1", "environment": "dev", "source": "platform"},
uuid=None,
+ timestamp=None,
)
diff --git a/autogpt_platform/backend/backend/util/metrics.py b/autogpt_platform/backend/backend/util/metrics.py
index 758cdeeff5..a5cf8b9014 100644
--- a/autogpt_platform/backend/backend/util/metrics.py
+++ b/autogpt_platform/backend/backend/util/metrics.py
@@ -92,7 +92,7 @@ _SENTRY_SENSITIVE_FIELDS = sorted(
# A user is known to Sentry by their id only, so their email and IP address are
# filtered wherever else they turn up, such as in extras or a frame's locals.
# Exact names only: keys like ``email_verified`` stay readable.
-_SENTRY_PERSONAL_FIELDS = ("email", "user_email", "ip", "ip_address")
+_SENTRY_PERSONAL_FIELDS = ("email", "user_email", "recipient", "ip", "ip_address")
# Matched case-insensitively against every key in the event, as sentry's
# EventScrubber does (with its PII list, since send_default_pii is off).
_SENTRY_SENSITIVE_KEYS = frozenset(
diff --git a/autogpt_platform/backend/backend/util/metrics_test.py b/autogpt_platform/backend/backend/util/metrics_test.py
index d0ea9bdd5d..830c2cac56 100644
--- a/autogpt_platform/backend/backend/util/metrics_test.py
+++ b/autogpt_platform/backend/backend/util/metrics_test.py
@@ -633,10 +633,11 @@ def test_before_send_filters_emails_and_ips_from_extras_and_frame_vars() -> None
def notify_user():
user_email = "[email protected]"
+ recipient = "[email protected]"
ip = "203.0.113.7"
ip_address = "198.51.100.4"
email_count = 1
- if email and user_email and ip and ip_address and email_count:
+ if email and user_email and recipient and ip and ip_address and email_count:
raise RuntimeError("could not send the notification")
try:
@@ -664,7 +665,7 @@ def test_before_send_filters_emails_and_ips_from_extras_and_frame_vars() -> None
}
assert body["extra"]["ip_address"] == "[Filtered]"
frame_vars = body["exception"]["values"][0]["stacktrace"]["frames"][-1]["vars"]
- for name in ("email", "user_email", "ip", "ip_address"):
+ for name in ("email", "user_email", "recipient", "ip", "ip_address"):
assert frame_vars[name] == "[Filtered]", name
# Keys that only mention an email or IP stay readable for debugging.
assert frame_vars["email_count"] == "1"
diff --git a/autogpt_platform/backend/backend/util/posthog_client.py b/autogpt_platform/backend/backend/util/posthog_client.py
index 0777222b4a..5702635aa4 100644
--- a/autogpt_platform/backend/backend/util/posthog_client.py
+++ b/autogpt_platform/backend/backend/util/posthog_client.py
@@ -14,6 +14,7 @@ import asyncio
import atexit
import logging
from collections.abc import Callable, Iterable, Mapping
+from datetime import datetime
from functools import cache
from threading import Lock
from typing import Any
@@ -124,6 +125,7 @@ def capture(
*,
source: str = "platform",
dedup_key: str | None = None,
+ timestamp: datetime | None = None,
client: Posthog | None = None,
) -> bool:
"""Send one event for *distinct_id* with the base properties, on
@@ -137,7 +139,10 @@ def capture(
``dedup_key`` is an idempotency key for a redelivery or requeue that can
send the same event twice; it is carried both as ``$insert_id`` and as a
deterministic event uuid, because PostHog's ingestion keys on the uuid,
- which the client otherwise randomises per call.
+ which the client otherwise randomises per call. ``timestamp`` is when the
+ action happened, for an event reported after the fact, such as by a
+ webhook. PostHog only merges duplicates that fall on the same day, so a
+ redelivery needs the sender's own time as well as ``dedup_key``.
"""
if not distinct_id:
return False
@@ -166,6 +171,7 @@ def capture(
event=event_name,
properties=payload,
uuid=event_uuid,
+ timestamp=timestamp,
)
return queued is not None
except Exception:
diff --git a/autogpt_platform/backend/backend/util/posthog_client_test.py b/autogpt_platform/backend/backend/util/posthog_client_test.py
index 047a4a0a87..0b2a0fc7f4 100644
--- a/autogpt_platform/backend/backend/util/posthog_client_test.py
+++ b/autogpt_platform/backend/backend/util/posthog_client_test.py
@@ -131,6 +131,7 @@ def test_capture_adds_the_base_properties_last(monkeypatch: pytest.MonkeyPatch)
"source": "chat_copilot",
},
uuid=None,
+ timestamp=None,
)
diff --git a/autogpt_platform/backend/backend/util/posthog_events.py b/autogpt_platform/backend/backend/util/posthog_events.py
index 5900a20748..ebc06166cc 100644
--- a/autogpt_platform/backend/backend/util/posthog_events.py
+++ b/autogpt_platform/backend/backend/util/posthog_events.py
@@ -86,6 +86,13 @@ class PostHogEvent(StrEnum):
LISTING_ADDED_TO_LIBRARY = "listing_added_to_library"
LISTING_DOWNLOADED = "listing_downloaded"
+ # Email (SECRT-2735): backend/api/features/postmark/, from Postmark's
+ # webhooks for the mail the platform sends itself.
+ EMAIL_DELIVERED = "email_delivered"
+ EMAIL_OPENED = "email_opened"
+ EMAIL_CLICKED = "email_clicked"
+ EMAIL_BOUNCED = "email_bounced"
+
class PlannedPostHogEvent(StrEnum):
"""Planned in the tracking plan and NOT emitted yet.
diff --git a/autogpt_platform/backend/backend/util/posthog_events_test.py b/autogpt_platform/backend/backend/util/posthog_events_test.py
index 5bcf395b40..68ce5a31b4 100644
--- a/autogpt_platform/backend/backend/util/posthog_events_test.py
+++ b/autogpt_platform/backend/backend/util/posthog_events_test.py
@@ -51,6 +51,10 @@ LIVE_EVENT_NAMES = {
"subscription_ended",
"listing_added_to_library",
"listing_downloaded",
+ "email_delivered",
+ "email_opened",
+ "email_clicked",
+ "email_bounced",
}
PLANNED_EVENT_NAMES: set[str] = set()
diff --git a/autogpt_platform/backend/backend/util/product_analytics.py b/autogpt_platform/backend/backend/util/product_analytics.py
index f5ff2df680..7d0f3642ea 100644
--- a/autogpt_platform/backend/backend/util/product_analytics.py
+++ b/autogpt_platform/backend/backend/util/product_analytics.py
@@ -104,6 +104,7 @@ def track(
properties: dict[str, Any] | None = None,
*,
dedup_key: str | None = None,
+ timestamp: datetime | None = None,
) -> None:
"""Send one event for *user_id*, dropping unset properties. Silently
no-ops when analytics is off or there is no user."""
@@ -112,6 +113,7 @@ def track(
event,
{k: v for k, v in (properties or {}).items() if v is not None},
dedup_key=dedup_key,
+ timestamp=timestamp,
)
diff --git a/autogpt_platform/backend/backend/util/settings.py b/autogpt_platform/backend/backend/util/settings.py
index 41cdd1034f..8118e50595 100644
--- a/autogpt_platform/backend/backend/util/settings.py
+++ b/autogpt_platform/backend/backend/util/settings.py
@@ -704,6 +704,17 @@ class Config(UpdateTrackingModel["Config"], BaseSettings):
"Must be a transactional stream, separate from marketing mail."
),
)
+ # Off until the privacy policy names email tracking. Auth mail is never
+ # tracked: its links carry sign-in tokens.
+ postmark_track_opens_and_clicks: bool = Field(
+ default=False,
+ description=(
+ "Ask Postmark to track opens (a tracking pixel) and clicks (links "
+ "rewritten through Postmark) in notification emails. Postmark "
+ "reports them to the webhook, which sends email_opened and "
+ "email_clicked to PostHog. Overrides the stream's own setting."
+ ),
+ )
email_asset_base_url: str = Field(
default="https://platform.agpt.co/email",
description=(
diff --git a/docs/engineering/tracking-plan.md b/docs/engineering/tracking-plan.md
index 618f5c9948..5b09ea94c9 100644
--- a/docs/engineering/tracking-plan.md
+++ b/docs/engineering/tracking-plan.md
@@ -309,6 +309,49 @@ sent or dropped this way, not while it is held.
Return visits are `$pageview`; account-level retention is computed in
`retention_task_weekly` and `user_lifecycle`, not sent as events.
+### Email
+
+Postmark's webhooks for the mail the platform sends itself
+(`api/features/postmark/`). MailerLite's mail (the onboarding tour, the
+changelog) is not covered.
+
+| Event | Sender | Status | Required properties | Fires when |
+| --- | --- | --- | --- | --- |
+| `email_delivered` | backend | live | `email_type`, `message_stream`, `message_id` | The receiving mail server accepts the email (Postmark's Delivery webhook). |
+| `email_opened` | backend | live | `email_type`, `message_stream`, `message_id`, `first_open` | The email's tracking pixel loads (Open webhook). Mail apps that preload images, such as Apple Mail, report opens nobody made, so read it as an upper bound. |
+| `email_clicked` | backend | live | `email_type`, `message_stream`, `message_id`, `link` | A link in the email is followed (Click webhook). |
+| `email_bounced` | backend | live | `email_type`, `message_stream`, `message_id`, `bounce_type` | The email bounces (Bounce webhook), soft bounces included. A hard bounce also marks the address unverified. |
+
+- **`email_type`** is the Postmark tag the email was sent with: the
+ notification type in lower case (`briefing`, `alert`, `verdict`, `ops`,
+ `subscription_welcome`, `payment_failed`, `payment_final_notice`,
+ `subscription_cancelled`, `subscription_resumed`, `subscription_ended`,
+ `trial_update`), or `auth` for Better Auth's verification and password
+ emails. Unset for mail sent before tags were added.
+- **`message_stream`** is the Postmark stream (`POSTMARK_TRANSACTIONAL_STREAM`)
+ and **`message_id`** Postmark's message id, which ties the events of one
+ email together.
+- **`link`** is the clicked link's scheme, host and path only: the query
+ string and fragment are dropped, and a path segment that isn't a plain
+ lower-case word, or that looks like an id or a token, becomes `:id`
+ (`https://platform.agpt.co/library/agents/:id`). A link that is not
+ `http(s)` keeps only its scheme (`mailto:`).
+- **`bounce_type`** is Postmark's bounce type (`HardBounce`, `SoftBounce`,
+ `Transient`, `SpamNotification`, ...).
+- **`first_open`** is whether Postmark counts it as the first open of that
+ email.
+- **Who it is for.** The recipient address is looked up among users, and the
+ user id is the `distinct_id`. An address with no account (such as the Ops
+ inbox) sends nothing. The address is never sent or logged.
+- **When.** The event carries Postmark's own time, not the time the webhook
+ arrived, and is deduplicated on message id, record type and that time (and
+ the link, for a click), so a webhook Postmark redelivers counts once.
+- **Opens and clicks need tracking on.** Each notification email asks
+ Postmark to track opens and to rewrite links in its HTML part only when
+ `POSTMARK_TRACK_OPENS_AND_CLICKS` is true (off by default). Auth email is
+ never tracked, since its links carry sign-in tokens. Postmark only calls the
+ webhook for the record types ticked on the stream's webhook.
+
## LLM analytics
AutoPilot's LLM calls, tool calls and the ratings of its replies, in
@@ -580,8 +623,11 @@ line:
`artifact_created`, `file_produced` and `answer_only` do not.
- **Plan events we do not send yet** (`signup_started`, `chat_session_started`,
`chat_response_completed`, `chat_blocked`, `screen_viewed`,
- `screen_engaged`, `milestone_reached`, the builder, library and email
- families, ...) come with the plan's phases, not with this list.
+ `screen_engaged`, `milestone_reached`, the builder and library families,
+ `email_sent`, ...) come with the plan's phases, not with this list.
+- **`email_delivered` instead of the plan's `email_sent`.** Postmark's
+ webhook reports that the receiving server accepted the email, which is
+ delivery, not sending. `email_sent` stays free for the send itself.
- **Events the plan has no name for keep their own**, e.g.
`integration_connected`, `schedule_created`, `hire_started`,
`billing_portal_opened`, `marketing_opted_out`, `tour_*`,