Send transactional email, such as a password reset or a receipt, and read its status.

An email goes out in one of two forms:

• A template made in PostHog, sent by its ID with :template_id and :template_data.
• Content your code rendered, named by :template_key, with :subject and :html, :text or both. To send a React email, render it to HTML in your app, for example with @react-email/render, and pass the result as :html. The SDK adds no rendering.

Setup

1. In PostHog, open the email template under Workflows, make it transactional, and copy its ID. :template_id is that UUID. The code form needs no template.

2. Create a project secret API key (phs_...) with the "Send transactional email" preset (transactional_email:write) in your project settings. Add transactional_email:read too if you read email statuses with a key that can't send. Keys made with hog_flow:write still work. The project API key (phc_...) captures events but cannot send email.

3. Set it as :secret_key in your PostHog config:

   config :posthog,
     api_host: "https://eu.i.posthog.com",
     api_key: "phc_...",
     secret_key: "phs_..."

Examples

Send a template made in PostHog:

{:ok, %PostHog.Emails.SendResult{id: message_id}} =
  PostHog.Emails.send(
    to: "user@example.com",
    template_id: "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b",
    template_data: %{name: "Ada"},
    distinct_id: "user_123",
    idempotency_key: "welcome:user_123"
  )

Send content your code rendered:

PostHog.Emails.send(
  to: "user@example.com",
  template_key: "password-reset",
  subject: "Reset your password",
  html: rendered_html,
  distinct_id: "user_123",
  idempotency_key: "password-reset:#{reset.id}"
)

Read what happened to it:

{:ok, %PostHog.Emails.Status{status: status}} = PostHog.Emails.get(message_id)

Always pass :distinct_id. Without it, the email's events go to a person whose distinct ID is the email address, not to your user. The SDK never takes it from PostHog.set_context/2.

What a result means

{:ok, result} means PostHog queued the email. Delivery happens later: read it with get/2, or in the template's workflow in PostHog.

Where requests go

A client on PostHog Cloud sends to its region's app host, https://us.posthog.com or https://eu.posthog.com. For any other :api_host, such as a reverse proxy, set :app_host in the config, because email requests must not send the secret key to the proxy. Without it, a send returns the error missing_app_host.

:secret_key also turns on local feature flag evaluation, which fetches flag definitions from :api_host with that key. When :api_host is a proxy that must not see the key, set enable_local_evaluation: false as well.

Timeouts, retries and idempotency

Each request times out after :email_request_timeout_ms (15 seconds by default). A send retries network errors, rate limits, an idempotency key still in flight and an unavailable service :email_request_max_retries times (2 by default), waiting about 1 and then 2 seconds, or the server's Retry-After when it is longer. A Retry-After over 30 seconds fails at once with :retry_after_ms set. A monthly quota is never retried.

Every attempt sends the same idempotency key, so a retry never sends twice. Without :idempotency_key, the SDK makes a UUID for the call. When a job runner such as Oban already retries the send, pass max_retries: 0 and an :idempotency_key that names the email, such as "welcome:user_123". A generated key doesn't survive a job retry.

Sends and status reads block the calling process until they finish. The SDK keeps no email queue.

Errors

Every failure returns {:error, %PostHog.Emails.Error{}}. Branch on :code. The ones a setup usually hits:

• missing_secret_key: the config has no :secret_key.
• missing_app_host: the :api_host is not PostHog Cloud. Set :app_host.
• authentication_failed (401) or permission_denied (403): the key is wrong, or it lacks transactional_email:write.
• not_found (404): the template ID is wrong, or transactional email is not enabled for the project.
• client_disabled: the PostHog instance is not running or has no :api_key, so it sends nothing.
• client_closed: the PostHog instance stopped while a call waited to retry, so the retry was not sent.

An option the SDK refuses returns an error with an invalid_* code, such as invalid_template_id, and the name :validation_error, before any request.

Testing

Requests go through the configured :api_client_module, so a Mox mock of PostHog.API.Client sees every email request without network calls.