:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(email): add a shared transactional email task (#120401)
Georgiy Tarasova6edd137b4b1
diff --git a/posthog/settings/base_variables.py b/posthog/settings/base_variables.pyindex c9c04b508f91..02df9f30fe37 100644--- a/posthog/settings/base_variables.py+++ b/posthog/settings/base_variables.py@@ -66,6 +66,10 @@ SERVER_GATEWAY_INTERFACE = get_from_env("SERVER_GATEWAY_INTERFACE", "WSGI", type# GitHub secret alert relay URL - set in US deployment to forward alerts to EUGITHUB_SECRET_ALERT_RELAY_URL: str | None = get_from_env("GITHUB_SECRET_ALERT_RELAY_URL", optional=True)+# PostHog's internal US project is also used by callers running in the EU region.+POSTHOG_PROJECT_ID: int = get_from_env("POSTHOG_PROJECT_ID", 2, type_cast=int)+POSTHOG_HOST: str = get_from_env("POSTHOG_HOST", "https://us.posthog.com")+# Internal team on PostHog Cloud US that receives `$ai_generation` /# `$ai_embedding` events emitted by PostHog products (PostHog Desktop,# background agents, etc). Used by /api/llm_analytics/personal_spend/.diff --git a/posthog/settings/email.py b/posthog/settings/email.pyindex 439b2df1aabd..a6eb274c8c5c 100644--- a/posthog/settings/email.py+++ b/posthog/settings/email.py@@ -1,7 +1,9 @@import osfrom posthog.settings.access import SECRET_KEY-from posthog.settings.utils import get_list+from posthog.settings.utils import get_from_env, get_list++POSTHOG_TRANSACTIONAL_EMAIL_API_KEY: str = get_from_env("POSTHOG_TRANSACTIONAL_EMAIL_API_KEY", "")MESSAGING_HASH_SALT: str = os.getenv("MESSAGING_HASH_SALT") or SECRET_KEYMESSAGING_HASH_SALT_FALLBACKS: list[str] = [diff --git a/posthog/tasks/__init__.py b/posthog/tasks/__init__.pyindex f3984985a550..27563de7eb28 100644--- a/posthog/tasks/__init__.py+++ b/posthog/tasks/__init__.py@@ -25,6 +25,7 @@ from . import (sync_billing,tasks,team_access_cache_tasks,+ transactional_email,usage_report,)@@ -53,5 +54,6 @@ __all__ = ["sync_billing","tasks","team_access_cache_tasks",+ "transactional_email","usage_report",]diff --git a/posthog/tasks/test/__snapshots__/test_task_registration.ambr b/posthog/tasks/test/__snapshots__/test_task_registration.ambrindex d0dd602b2be0..5123f54f83a4 100644--- a/posthog/tasks/test/__snapshots__/test_task_registration.ambr+++ b/posthog/tasks/test/__snapshots__/test_task_registration.ambr@@ -163,6 +163,7 @@'posthog.tasks.team_metadata.refresh_expiring_team_metadata_cache_entries','posthog.tasks.team_metadata.update_related_teams_metadata_cache_task','posthog.tasks.team_metadata.update_team_metadata_cache_task',+ 'posthog.tasks.transactional_email.send_transactional_email_task','posthog.tasks.uploaded_media.sweep_abandoned_media_uploads_task','posthog.tasks.usage_report.capture_report','posthog.tasks.usage_report.send_all_org_usage_reports',diff --git a/posthog/tasks/transactional_email.py b/posthog/tasks/transactional_email.pynew file mode 100644index 000000000000..4acbf1648951--- /dev/null+++ b/posthog/tasks/transactional_email.py@@ -0,0 +1,33 @@+from celery import Task, shared_task++from posthog.celery_queues import CeleryQueue+from posthog.scoping_audit import skip_team_scope_audit+from posthog.transactional_email import TransactionalEmailRetryableError, send_transactional_email+++@shared_task(+ bind=True,+ queue=CeleryQueue.EMAIL.value,+ ignore_result=True,+ autoretry_for=(TransactionalEmailRetryableError,),+ retry_backoff=True,+ max_retries=5,+ # Redelivery after worker loss could duplicate a send the API already accepted.+ acks_late=False,+)+@skip_team_scope_audit+def send_transactional_email_task(+ self: Task,+ template_id: str,+ *,+ to: str,+ distinct_id: str | None = None,+ message_data: dict[str, object] | None = None,+) -> str:+ """Send a transactional email with PostHog."""+ try:+ return send_transactional_email(template_id, to=to, distinct_id=distinct_id, message_data=message_data)+ except TransactionalEmailRetryableError as error:+ if error.retry_after is not None:+ raise self.retry(exc=error, countdown=error.retry_after)+ raisediff --git a/posthog/test/test_transactional_email.py b/posthog/test/test_transactional_email.pynew file mode 100644index 000000000000..f71a4d8c92d5--- /dev/null+++ b/posthog/test/test_transactional_email.py@@ -0,0 +1,163 @@+from unittest.mock import Mock, patch++from django.core.exceptions import ImproperlyConfigured+from django.test import SimpleTestCase, override_settings++import requests+from celery.exceptions import Retry+from parameterized import parameterized++from posthog.tasks.transactional_email import send_transactional_email_task+from posthog.transactional_email import (+ TransactionalEmailDeliveryUncertain,+ TransactionalEmailRejected,+ TransactionalEmailRetryableError,+ send_transactional_email,+)++TEMPLATE_ID = "12345678-1234-5678-9abc-123456789abc"+++@override_settings(+ POSTHOG_HOST="https://us.posthog.com/",+ POSTHOG_PROJECT_ID=2,+ POSTHOG_TRANSACTIONAL_EMAIL_API_KEY="phs_fake_transactional_key",+)+class TestTransactionalEmail(SimpleTestCase):+ def test_task_sends_to_configured_project_and_returns_queue_receipt(self) -> None:+ response = Mock(status_code=202)+ response.json.return_value = {"message_id": "example-message-id"}+ with patch("posthog.transactional_email.requests.post", return_value=response) as post:+ result = send_transactional_email_task.apply(+ args=[TEMPLATE_ID],+ kwargs={+ "to": "[email protected]",+ "distinct_id": "example-user",+ "message_data": {"title": "Example report"},+ },+ throw=True,+ )++ assert result.result == "example-message-id"+ post.assert_called_once_with(+ f"https://us.posthog.com/api/projects/2/messaging_templates/{TEMPLATE_ID}/send/",+ headers={"Authorization": "Bearer phs_fake_transactional_key"},+ json={+ "to": "[email protected]",+ "identifiers": {"distinct_id": "example-user"},+ "message_data": {"title": "Example report"},+ },+ timeout=(3, 10),+ allow_redirects=False,+ )++ @override_settings(POSTHOG_HOST="https://eu.posthog.com", POSTHOG_PROJECT_ID=123)+ def test_supports_a_different_sending_region_without_identifiers(self) -> None:+ response = Mock(status_code=202)+ response.json.return_value = {"message_id": "example-message-id"}+ with patch("posthog.transactional_email.requests.post", return_value=response) as post:+ send_transactional_email(TEMPLATE_ID, to="[email protected]")++ assert post.call_args.args[0].startswith("https://eu.posthog.com/api/projects/123/")+ assert post.call_args.kwargs["json"] == {"to": "[email protected]", "message_data": {}}++ @parameterized.expand(+ [+ ("POSTHOG_TRANSACTIONAL_EMAIL_API_KEY", ""),+ ("POSTHOG_PROJECT_ID", 0),+ ("POSTHOG_HOST", ""),+ ("POSTHOG_HOST", "http://example.com"),+ ("POSTHOG_HOST", "https://example.com/path"),+ ("POSTHOG_HOST", "https://user:[email protected]"),+ ]+ )+ def test_invalid_configuration_does_not_send(self, setting: str, value: str | int) -> None:+ with (+ override_settings(**{setting: value}),+ patch("posthog.transactional_email.requests.post") as post,+ self.assertRaises(ImproperlyConfigured),+ ):+ send_transactional_email(TEMPLATE_ID, to="[email protected]")+ post.assert_not_called()++ def test_invalid_template_does_not_send(self) -> None:+ with patch("posthog.transactional_email.requests.post") as post, self.assertRaises(ImproperlyConfigured):+ send_transactional_email("../different-endpoint", to="[email protected]")+ post.assert_not_called()++ @parameterized.expand([(301,), (400,), (401,), (403,), (404,)])+ def test_confirmed_rejection(self, status_code: int) -> None:+ with (+ patch("posthog.transactional_email.requests.post", return_value=Mock(status_code=status_code)),+ self.assertRaises(TransactionalEmailRejected) as raised,+ ):+ send_transactional_email(TEMPLATE_ID, to="[email protected]")+ assert str(raised.exception) == f"http_{status_code}"++ @parameterized.expand([(200,), (408,), (500,), (503,)])+ def test_unconfirmed_response_is_uncertain(self, status_code: int) -> None:+ with (+ patch("posthog.transactional_email.requests.post", return_value=Mock(status_code=status_code)),+ self.assertRaises(TransactionalEmailDeliveryUncertain),+ ):+ send_transactional_email(TEMPLATE_ID, to="[email protected]")++ @parameterized.expand([(None,), ([],), ({},), ({"message_id": 123},), ({"message_id": ""},)])+ def test_acceptance_without_a_receipt_is_uncertain(self, payload: object) -> None:+ response = Mock(status_code=202)+ response.json.return_value = payload+ with (+ patch("posthog.transactional_email.requests.post", return_value=response),+ self.assertRaises(TransactionalEmailDeliveryUncertain),+ ):+ send_transactional_email(TEMPLATE_ID, to="[email protected]")++ def test_invalid_json_is_uncertain(self) -> None:+ response = Mock(status_code=202)+ response.json.side_effect = ValueError("private response")+ with (+ patch("posthog.transactional_email.requests.post", return_value=response),+ self.assertRaises(TransactionalEmailDeliveryUncertain) as raised,+ ):+ send_transactional_email(TEMPLATE_ID, to="[email protected]")+ assert str(raised.exception) == "invalid_response"+ assert raised.exception.__suppress_context__++ @parameterized.expand([(requests.ReadTimeout,), (requests.ConnectionError,)])+ def test_task_does_not_retry_uncertain_requests(self, error_type: type[requests.RequestException]) -> None:+ with patch("posthog.transactional_email.requests.post", side_effect=error_type("private request")) as post:+ result = send_transactional_email_task.apply(+ args=[TEMPLATE_ID], kwargs={"to": "[email protected]"}, throw=False+ )+ post.assert_called_once()+ assert isinstance(result.result, TransactionalEmailDeliveryUncertain)+ assert str(result.result) == "request_failed"++ @parameterized.expand([("connect_timeout",), ("rate_limited",)])+ def test_task_retries_only_confirmed_non_acceptance(self, failure: str) -> None:+ with patch("posthog.transactional_email.requests.post") as post:+ if failure == "connect_timeout":+ post.side_effect = requests.ConnectTimeout("private request")+ else:+ post.return_value = Mock(status_code=429)+ with self.assertRaises(Retry) as raised:+ send_transactional_email_task.apply(+ args=[TEMPLATE_ID], kwargs={"to": "[email protected]"}, throw=True+ )+ post.assert_called_once()+ assert isinstance(raised.exception.exc, TransactionalEmailRetryableError)+ assert str(raised.exception.exc) == failure++ @parameterized.expand([("60", 60), ("3600", 3600), ("invalid", None), (None, None)])+ def test_rate_limit_retry_uses_server_delay(self, header: str | None, expected: int | None) -> None:+ response = Mock(status_code=429, headers={"Retry-After": header} if header is not None else {})+ with patch("posthog.transactional_email.requests.post", return_value=response) as post:+ with self.assertRaises(Retry) as raised:+ send_transactional_email_task.apply(+ args=[TEMPLATE_ID], kwargs={"to": "[email protected]"}, throw=True+ )+ post.assert_called_once()+ assert isinstance(raised.exception.exc, TransactionalEmailRetryableError)+ assert raised.exception.exc.retry_after == expected+ if expected is not None:+ assert raised.exception.when == expecteddiff --git a/posthog/transactional_email.py b/posthog/transactional_email.pynew file mode 100644index 000000000000..215ae56c4471--- /dev/null+++ b/posthog/transactional_email.py@@ -0,0 +1,104 @@+from urllib.parse import urlsplit+from uuid import UUID++from django.conf import settings+from django.core.exceptions import ImproperlyConfigured++import requests+++class TransactionalEmailRetryableError(Exception):+ """The API did not accept the email, so retrying cannot duplicate it."""++ def __init__(self, message: str, *, retry_after: int | None = None) -> None:+ super().__init__(message)+ self.retry_after = retry_after+++class TransactionalEmailRejected(Exception):+ """The API rejected the email and requires caller intervention."""+++class TransactionalEmailDeliveryUncertain(Exception):+ """The API may have accepted the email; reconcile before retrying."""+++def is_transactional_email_configured() -> bool:+ return bool(+ settings.POSTHOG_HOST and settings.POSTHOG_PROJECT_ID > 0 and settings.POSTHOG_TRANSACTIONAL_EMAIL_API_KEY+ )+++def _send_url(template_id: str) -> str:+ if not is_transactional_email_configured():+ raise ImproperlyConfigured("PostHog transactional email settings are missing")++ host = settings.POSTHOG_HOST.rstrip("/")+ parsed_host = urlsplit(host)+ if (+ parsed_host.scheme != "https"+ or not parsed_host.netloc+ or parsed_host.username+ or parsed_host.password+ or parsed_host.path+ or parsed_host.query+ or parsed_host.fragment+ ):+ raise ImproperlyConfigured("POSTHOG_HOST must be an HTTPS origin")+ try:+ template_uuid = UUID(template_id)+ except ValueError:+ raise ImproperlyConfigured("Transactional email template ID must be a UUID") from None+ return f"{host}/api/projects/{settings.POSTHOG_PROJECT_ID}/messaging_templates/{template_uuid}/send/"+++def send_transactional_email(+ template_id: str,+ *,+ to: str,+ distinct_id: str | None = None,+ message_data: dict[str, object] | None = None,+) -> str:+ """Return the API's message ID after queue acceptance, not mailbox delivery.++ The send API has no idempotency key. Callers must not retry uncertain outcomes.+ """+ url = _send_url(template_id)++ payload: dict[str, object] = {"to": to, "message_data": message_data or {}}+ if distinct_id is not None:+ payload["identifiers"] = {"distinct_id": distinct_id}++ try:+ response = requests.post(+ url,+ headers={"Authorization": f"Bearer {settings.POSTHOG_TRANSACTIONAL_EMAIL_API_KEY}"},+ json=payload,+ timeout=(3, 10),+ allow_redirects=False,+ )+ except requests.ConnectTimeout:+ raise TransactionalEmailRetryableError("connect_timeout") from None+ except requests.RequestException:+ # Request exceptions may retain authorization headers and response bodies.+ raise TransactionalEmailDeliveryUncertain("request_failed") from None++ if response.status_code == 429:+ try:+ retry_after: int | None = max(0, int(response.headers.get("Retry-After", "")))+ except (ValueError, TypeError):+ retry_after = None+ raise TransactionalEmailRetryableError("rate_limited", retry_after=retry_after)+ if 300 <= response.status_code < 500 and response.status_code != 408:+ raise TransactionalEmailRejected(f"http_{response.status_code}")+ if response.status_code != 202:+ raise TransactionalEmailDeliveryUncertain(f"http_{response.status_code}")++ try:+ data = response.json()+ except ValueError:+ raise TransactionalEmailDeliveryUncertain("invalid_response") from None+ message_id = data.get("message_id") if isinstance(data, dict) else None+ if not isinstance(message_id, str) or not message_id:+ raise TransactionalEmailDeliveryUncertain("invalid_response")+ return message_id