Skip to content

: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.

feat(email): add a shared transactional email task (#120401)

Georgiy Tarasova6edd137b4b1
diff --git a/posthog/settings/base_variables.py b/posthog/settings/base_variables.py
index 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 EU
GITHUB_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.py
index 439b2df1aabd..a6eb274c8c5c 100644
--- a/posthog/settings/email.py
+++ b/posthog/settings/email.py
@@ -1,7 +1,9 @@
import os
from 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_KEY
MESSAGING_HASH_SALT_FALLBACKS: list[str] = [
diff --git a/posthog/tasks/__init__.py b/posthog/tasks/__init__.py
index 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.ambr
index 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.py
new file mode 100644
index 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)
+ raise
diff --git a/posthog/test/test_transactional_email.py b/posthog/test/test_transactional_email.py
new file mode 100644
index 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={
+ "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={
+ "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 == expected
diff --git a/posthog/transactional_email.py b/posthog/transactional_email.py
new file mode 100644
index 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