feat: configure email sends on the client and document setup

Posthog and AsyncPosthog take app_host, email_request_timeout_seconds and email_request_max_retries, so client.emails works behind a custom host and a job runner can turn retries off. Emails takes a session and AsyncEmails an http_client, which gives tests a supported no-network path. The posthog.emails module docs now hold a setup quickstart: keys and scope, template ID, hosts, retries, errors to expect, cleanup and testing. The release note names client.emails.send().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Generated-By: PostHog Desktop
Task-Id: c62b30cd-eb2e-496c-a73d-2a6e7a52a62e

Author: mayteio

.sampo/changesets/transactional-emails.md

@@ -2,4 +2,4 @@
 pypi/posthog: minor
 ---
 
-Send transactional email from PostHog email templates with `posthog.emails.send()`, or with `Emails` and `AsyncEmails` from `posthog.emails` in a process that only sends email. A send needs a project secret API key, goes to the app host, sends an idempotency key, and retries network errors, rate limits and an unavailable service with the same key. Errors raise `EmailError` with PostHog's error `code` and a Resend-style `name`.
+Send transactional email from PostHog email templates with `client.emails.send()` on `Posthog` and `AsyncPosthog`, or with `Emails` and `AsyncEmails` from `posthog.emails` in a process that only sends email. A send needs a project secret API key, goes to the app host, sends an idempotency key, and retries network errors, rate limits and an unavailable service with the same key. Set `app_host`, `email_request_timeout_seconds` and `email_request_max_retries` on the client to configure sends. Errors raise `EmailError` with PostHog's error `code` and a Resend-style `name`.

posthog/async_client.py

@@ -70,7 +70,7 @@
     try_attach_code_variables_to_frames,
 )
 from .consumer import MAX_MSG_SIZE
-from .emails import AsyncEmails, _client_emails
+from .emails import AsyncEmails, _client_emails, _validate_options
 from .feature_flag_evaluations import (
     FeatureFlagEvaluations,
     _EvaluatedFlagRecord,
@@ -130,6 +130,9 @@ def __init__(
         personal_api_key: Optional[str] = None,
         feature_flags_request_timeout_seconds: int = 3,
         feature_flags_request_max_retries: int = 1,
+        app_host: Optional[str] = None,
+        email_request_timeout_seconds: float = 15,
+        email_request_max_retries: int = 2,
     ) -> None:
         if flush_at <= 0:
             raise ValueError("flush_at must be greater than zero")
@@ -174,6 +177,10 @@ def __init__(
             else resolved_secret_key
         ) or None
         self.personal_api_key = self.secret_key
+        _validate_options(email_request_timeout_seconds, email_request_max_retries)
+        self.app_host = app_host
+        self.email_request_timeout_seconds = email_request_timeout_seconds
+        self.email_request_max_retries = email_request_max_retries
         self.feature_flags_request_timeout_seconds = (
             feature_flags_request_timeout_seconds
         )
@@ -256,9 +263,10 @@ def emails(self) -> AsyncEmails:
         Send transactional email from PostHog email templates.
 
         Needs ``secret_key``, a project secret API key with the ``hog_flow:write``
-        scope, and ``posthog[async]``. Sends go to the PostHog Cloud app host of
-        ``host``. For any other host, create ``posthog.emails.AsyncEmails`` with
-        the app host. A disabled client sends nothing.
+        scope, and ``posthog[async]``. Sends go to ``app_host``, or to the PostHog
+        Cloud app host of ``host``. ``email_request_timeout_seconds`` and
+        ``email_request_max_retries`` configure each send. A disabled or shut-down
+        client sends nothing. See ``posthog.emails`` for setup.
 
         Examples:
             ```python
@@ -276,6 +284,9 @@ def emails(self) -> AsyncEmails:
                 self.host,
                 lambda: self.disabled,
                 self._admit_email_send,
+                app_host=self.app_host,
+                timeout=self.email_request_timeout_seconds,
+                max_retries=self.email_request_max_retries,
             )
         return self._emails
 

posthog/client.py

@@ -52,7 +52,7 @@
     set_context_session as _context_set_context_session,
     tag as _context_tag,
 )
-from posthog.emails import Emails, _client_emails, _no_op
+from posthog.emails import Emails, _client_emails, _no_op, _validate_options
 from posthog.exception_capture import ExceptionCapture
 from posthog._logging import _configure_posthog_logging
 from posthog.exception_utils import (
@@ -722,6 +722,9 @@ def __init__(
         _use_ai_lane=False,
         _enable_multimodal_capture=False,
         traces: Optional[dict] = None,
+        app_host: Optional[str] = None,
+        email_request_timeout_seconds: float = 15,
+        email_request_max_retries: int = 2,
     ):
         """
         Initialize a new PostHog client instance.
@@ -773,6 +776,15 @@ def __init__(
             feature_flags_request_max_retries: Number of retries for feature flag
                 requests after network, transport, or timeout failures. Defaults
                 to 1. Set to 0 to disable retries.
+            app_host: Your PostHog app host, such as ``https://posthog.example.com``.
+                ``emails`` sends there. Needed only when ``host`` is not PostHog
+                Cloud, for example a reverse proxy, which must not receive the
+                secret key.
+            email_request_timeout_seconds: Timeout in seconds for each email send
+                request. Defaults to 15.
+            email_request_max_retries: Number of retries for an email send after a
+                network error, a rate limit, or an unavailable service. Defaults to 2.
+                Set to 0 when a job runner already retries the send.
             super_properties: Properties merged into every captured event.
             enable_exception_autocapture: Automatically capture uncaught
                 exceptions.
@@ -1037,6 +1049,10 @@ def __init__(
             else resolved_secret_key
         ) or None
         self.personal_api_key = self.secret_key
+        _validate_options(email_request_timeout_seconds, email_request_max_retries)
+        self.app_host = app_host
+        self.email_request_timeout_seconds = email_request_timeout_seconds
+        self.email_request_max_retries = email_request_max_retries
         if debug:
             # Ensures that debug level messages are logged when debug mode is on.
             # Otherwise, defaults to WARNING level. See https://docs.python.org/3/howto/logging.html#what-happens-if-no-configuration-is-provided
@@ -1139,9 +1155,10 @@ def emails(self) -> Emails:
         Send transactional email from PostHog email templates.
 
         Needs ``secret_key``, a project secret API key with the ``hog_flow:write``
-        scope. Sends go to the PostHog Cloud app host of ``host``. For any other
-        host, or to send email without capturing events, create
-        ``posthog.emails.Emails`` with the app host. A disabled client sends nothing.
+        scope. Sends go to ``app_host``, or to the PostHog Cloud app host of
+        ``host``. ``email_request_timeout_seconds`` and ``email_request_max_retries``
+        configure each send. A disabled or shut-down client sends nothing. See
+        ``posthog.emails`` for setup.
 
         Examples:
             ```python
@@ -1160,6 +1177,9 @@ def emails(self) -> Emails:
                 self.host,
                 lambda: self.disabled,
                 lambda: None if self._shutdown_requested else _no_op,
+                app_host=self.app_host,
+                timeout=self.email_request_timeout_seconds,
+                max_retries=self.email_request_max_retries,
             )
         return self._emails
 

posthog/emails.py

@@ -1,22 +1,67 @@
 """Transactional email, sent from an email template in PostHog.
 
-Use ``client.emails`` on a client created with a project secret API key, or
-create :class:`Emails` directly in a process that only sends email:
+Setup:
+
+1. In PostHog, open the email template under Workflows, make it transactional,
+   and copy its ID. ``template_id`` is that UUID.
+2. Create a project secret API key (``phs_...``) with Workflow write access
+   (``hog_flow:write``) in your project settings. The project API key
+   (``phc_...``) captures events but cannot send email.
+3. Send from the client you already use, or from :class:`Emails` in a process
+   that only sends email:
 
 ```python
-from posthog.emails import Emails
+from posthog import Posthog
 
-emails = Emails("phs_...")
-result = emails.send(
+posthog = Posthog("phc_...", secret_key="phs_...", host="https://eu.i.posthog.com")
+result = posthog.emails.send(
     to="user@example.com",
     template_id="<template UUID>",
-    template_data={"name": "Ada"},
+    template_data={"name": "Ada"},  # fills {{ variables.name }}
     distinct_id="user_123",
     idempotency_key="welcome:user_123",
 )
+print(result.id)  # the queued email
 ```
 
-A result means PostHog queued the email. It does not mean the email was delivered.
+``posthog.emails`` above is the client's property. For async code, use
+``AsyncPosthog`` or :class:`AsyncEmails` with ``posthog[async]`` installed.
+
+Where sends go: a client on PostHog Cloud sends to its region's app host,
+``us.posthog.com`` or ``eu.posthog.com``. For any other ``host``, such as a
+reverse proxy, set ``app_host`` on the client, because the proxy must not
+receive the secret key. :class:`Emails` takes the app host as ``host``.
+
+What a result means: PostHog queued the email. Delivery happens later, and the
+template's workflow in PostHog shows its sends, deliveries and failures.
+
+Timeouts and retries: each request times out after 15 seconds. A send retries
+network errors, rate limits and an unavailable service twice, waiting about 1
+and then 2 seconds, or the server's ``Retry-After`` if that is longer. A
+``Retry-After`` over 30 seconds raises at once. Every attempt sends the same
+idempotency key, so a retry never sends twice. Set
+``email_request_max_retries=0`` on the client, or ``max_retries=0`` on
+:class:`Emails`, when a job runner already retries the send, and pass an
+``idempotency_key`` that names the email, such as ``welcome:user_123``.
+
+Errors: a send that is not queued raises :class:`EmailError`. Branch on
+``code``. The ones a setup usually hits:
+
+- ``missing_secret_key``: the client has no ``secret_key``.
+- ``app_host_required``: the client's ``host`` is not PostHog Cloud. Set ``app_host``.
+- ``authentication_failed`` (401) or ``permission_denied`` (403): the key is
+  wrong, or it lacks ``hog_flow:write``.
+- ``not_found`` (404): the template ID is wrong, or transactional email is not
+  enabled for the project.
+- ``client_closed``: the client is shut down.
+
+Cleanup: ``shutdown()`` on the client closes its email connections. Close a
+standalone :class:`Emails` with ``close()`` or a ``with`` block.
+
+Testing without network calls: pass your own transport, ``session`` to
+:class:`Emails` or ``http_client`` to :class:`AsyncEmails`, with a fake adapter
+or ``httpx.MockTransport``. Any library that mocks ``requests`` or ``httpx``
+works too. A disabled client returns a result with ``id=None`` and sends nothing.
 """
 
 from __future__ import annotations
@@ -362,7 +407,9 @@ class Emails(_EmailsBase):
 
     Each send retries network errors, rate limits and an unavailable service up
     to ``max_retries`` times, with the same idempotency key. Set
-    ``max_retries=0`` when a job runner already retries the send.
+    ``max_retries=0`` when a job runner already retries the send. ``timeout``
+    is in seconds, per request. Pass ``session`` to send through your own
+    ``requests.Session``, for example a test double.
     """
 
     def __init__(
@@ -373,6 +420,7 @@ def __init__(
         timeout: float = 15,
         max_retries: int = 2,
         disabled: bool = False,
+        session: Optional[requests.Session] = None,
     ) -> None:
         super().__init__(
             secret_key,
@@ -381,7 +429,8 @@ def __init__(
             max_retries=max_retries,
             disabled=disabled,
         )
-        self._session: Optional[requests.Session] = None
+        self._session: Optional[requests.Session] = session
+        self._owns_session = session is None
         self._session_lock = threading.Lock()
 
     def send(
@@ -482,9 +531,9 @@ def _deliver(self, prepared: _PreparedSend) -> SendEmailResult:
         raise AssertionError("unreachable")
 
     def close(self) -> None:
-        """Close the client's HTTP connections."""
+        """Close the HTTP connections this client opened. A ``session`` you passed in stays open."""
         with self._session_lock:
-            if self._session is not None:
+            if self._session is not None and self._owns_session:
                 self._session.close()
                 self._session = None
 
@@ -510,7 +559,11 @@ def _get_session(self) -> requests.Session:
 
 
 class AsyncEmails(_EmailsBase):
-    """The async counterpart of :class:`Emails`. Needs ``posthog[async]``."""
+    """The async counterpart of :class:`Emails`. Needs ``posthog[async]``.
+
+    Pass ``http_client`` to send through your own ``httpx.AsyncClient``, for
+    example one with an ``httpx.MockTransport`` in tests.
+    """
 
     def __init__(
         self,
@@ -520,6 +573,7 @@ def __init__(
         timeout: float = 15,
         max_retries: int = 2,
         disabled: bool = False,
+        http_client: Any = None,
     ) -> None:
         super().__init__(
             secret_key,
@@ -528,7 +582,8 @@ def __init__(
             max_retries=max_retries,
             disabled=disabled,
         )
-        self._client: Any = None
+        self._client: Any = http_client
+        self._owns_client = http_client is None
 
     async def send(
         self,
@@ -600,8 +655,8 @@ async def _deliver(self, prepared: _PreparedSend) -> SendEmailResult:
         raise AssertionError("unreachable")
 
     async def aclose(self) -> None:
-        """Close the client's HTTP connections."""
-        if self._client is not None:
+        """Close the HTTP connections this client opened. An ``http_client`` you passed in stays open."""
+        if self._client is not None and self._owns_client:
             client, self._client = self._client, None
             await client.aclose()
 
@@ -639,15 +694,31 @@ def _client_emails(
     client_host: Optional[str],
     is_disabled: Callable[[], bool],
     admit: Callable[[], Optional[Callable[[], None]]],
+    *,
+    app_host: Optional[str],
+    timeout: float,
+    max_retries: int,
 ) -> _EmailsT:
-    app_host = determine_app_host(client_host)
-    is_cloud = app_host in (US_APP_ENDPOINT, EU_APP_ENDPOINT)
-    emails = factory(secret_key, host=app_host if is_cloud else None)
+    if app_host:
+        emails = factory(
+            secret_key, host=app_host, timeout=timeout, max_retries=max_retries
+        )
+        emails._parent_disabled = is_disabled
+        emails._admit = admit
+        return emails
+    inferred_host = determine_app_host(client_host)
+    is_cloud = inferred_host in (US_APP_ENDPOINT, EU_APP_ENDPOINT)
+    emails = factory(
+        secret_key,
+        host=inferred_host if is_cloud else None,
+        timeout=timeout,
+        max_retries=max_retries,
+    )
     if not is_cloud:
         # A custom host is often an ingestion proxy, which must not receive the secret key.
         emails._host_error = (
             "The client's host is not PostHog Cloud, so the client can't tell where to send email. "
-            "Create posthog.emails.Emails(secret_key, host=<your PostHog app host>) instead."
+            "Set app_host to your PostHog app host on the client."
         )
     emails._parent_disabled = is_disabled
     emails._admit = admit