Skip to content

Transactional email SDK contract for posthog-python and posthog-node #120921

Open

Description

@Silthus

Note

🤖 Claude Opus 5.5 writing on behalf of Michael

One HTTP contract for sending transactional email from the server SDKs, so posthog-python and posthog-node behave the same.

The decisions come from the grilling in Silthus#525, the architecture in Silthus#526, and Michael and Harley's huddle on 2026-10-21 (follow-up notes). Origin: Slack thread.

TL;DR

  • send takes flat parameters in one of two forms: a template sent by template_id with template_data, or code content named by template_key with subject, html and text. No content helpers.
  • One send endpoint, POST /api/projects/@current/messaging/send/email/, on the app host, authenticated with the project secret key. Until it lands, template sends use /messaging_templates/{id}/send/.
  • A successful send returns the message_id. It means PostHog stored the send in its queue for delivery, not that the email was delivered.
  • The checks that would skip a send later run before the 202, and a failed check returns an error with why and fix. No silent skips.
  • Every send has an idempotency key. The client makes one when the caller gives none, and retries with the same key. Callers can turn retries off.
  • Always pass distinct_id. Without it, the email's engagement events land on a person keyed by the email address, not on the app's user.

Client setup

What Contract
Client The existing PostHog client, sync and async (AsyncPosthog in Python). Email is a namespace on it, posthog.emails, not a new client.
Auth New client option secret_key / secretKey: a project secret API key (phs_). Send needs hog_flow:write. Read needs hog_flow:read. Without it, the call fails with missing_secret_key.
App host New client option app_host / appHost, not api_host, because posthog-js uses that name for the ingestion host. When host is PostHog Cloud (us.i.posthog.com, us.posthog.com and the eu ones), the SDK derives the app host. Any other host may be a reverse proxy for ingestion, so the secret key never goes there: without app_host the call fails with missing_app_host. Self-hosted instances set app_host.
Retries New client option max_retries / maxRetries, default 2 (3 attempts in total). 0 turns retries off. A send can override it.
Migration Client option migrated_from / migratedFrom, such as "resend". Sent as X-PostHog-Migrated-From on every emails request.
Request context Never used. The recipient is never the person of the current request context.

Client interface (both SDKs)

Both SDKs expose this interface. Names follow each language: snake_case in Python, camelCase in Node. Python types the keyword arguments with a TypedDict and Unpack, the way capture does, with one @overload per form and a runtime check that exactly one form is passed.

emails.send(...) -> message_id, warnings      # Python returns them, or raises. Node returns { data, error }
emails.get(id)   -> EmailStatusRecord         # later PR, with the status record

send(
  to:                  string               # one address
  distinct_id?:        string               # always pass it in docs and examples. Absent: the address
  idempotency_key?:    string               # absent: the SDK makes a UUID v4. Derive it from the email's
                                            # purpose ("welcome:user_123") when a job runner retries
  capture_engagement?: bool                 # code form only, default true. False turns it off for this send
  max_retries?:        int                  # overrides the client option

  exactly one form:
    # Template form. Templates made in PostHog have no key, so they are sent by id.
    template_id:       string               # the template's UUID
    template_data?:    map                  # fills {{ variables.* }}. Sent as message_data

    # Code form. Michael's send API.
    template_key:      string               # names the email, so its metrics, logs and status group under it
    subject:           string
    html?:             string               # at least one of html and text
    text?:             string               # absent: the server derives it from html
    from?:             string               # a verified sender. Absent: the project's default sender, else its only verified sender
    reply_to?:         string | string[]
    cc?:               string | string[]    # at most 10 bare addresses, such as "jane@example.com"
    bcc?:              string | string[]    # at most 10. Never shown to the other recipients
    headers?:          map<string, string>  # at most 10 custom headers, such as { "X-Entity-Ref-ID": "order-123" }
    tags?:             { name, value }[]    # at most 10. Added to the email's engagement events as $email_tags
    attachments?:      attachment[]         # at most 10 files and 512 KB in total, after decoding
    template_data?:    map                  # absent: rendered content, sent as is and never stored.
                                            # present: a local template. The SDK uploads it by hash when needed
)

warning = { code, message, fix }
error   = { name, code, message, why?, fix?, status_code?, docs_url?, field?, retry_after? }
status  = queued | waiting | unknown | skipped | failed | sent | delivered | bounced | complained
attachment = { filename, content, content_type?, content_id? }
                                            # content: bytes (Python), Buffer or base64 string (Node)
                                            # content_id: shows the file inline, as <img src="cid:...">

How the parameters map to the request:

Parameter Request
to to
distinct_id identifiers.distinct_id, left out when absent
template_id Path /messaging_templates/{id}/send/ today, template: { id } on /messaging/send/email/
template_data message_data
template_key, subject, html, text Rendered content: the same names on /messaging/send/email/
Code form with template_data Local template: template: { key: template_key, hash } plus message_data. The hash is #118924's content_hash v1. On 409 template_outdated the SDK uploads by key with if_code_managed: true and if_not_superseded: true and sends again once, with the same idempotency key. The caller never calls an upload.
from, reply_to from, reply_to (a string becomes a one-item list)
cc, bcc cc, bcc (a string becomes a one-item list)
headers, tags headers, tags, as is
attachments attachments[] of { filename, content, content_type, content_id }. The SDK base64-encodes content when it is bytes or a Buffer, and leaves a string as is
capture_engagement capture_engagement on the code form, always sent: true when absent. Never sent with template_id
idempotency_key Idempotency-Key header

cc, bcc, headers, tags, attachments and capture_engagement work with both code-form cases, rendered content and a local template. With template_id the server refuses them, because a template made in PostHog sends with its own settings. The SDK refuses them before any request.

The template form moves from /messaging_templates/{id}/send/ to /messaging/send/email/ inside the SDK once #118924 lands, with no caller change.

Behavior both SDKs share

  • Errors. The same fields in both SDKs. Node returns { data, error } like Resend's Node SDK. Python raises typed exceptions that carry the same fields, like Resend's Python SDK.
  • Retries. Network errors, the in-flight 409, 429 throttled and 503, with the same idempotency key every time. 429 quota_limited is never retried, because waiting doesn't fix a monthly quota. Retries wait 1 s and then 2 s with jitter, or Retry-After when it is longer. A Retry-After over 30 s fails the send at once, with the wait in retry_after (seconds in Python, retryAfterMs in Node), because a retry before it would break the rate limit. get never retries.
  • SDK error codes. When PostHog did not answer with a code, code is one of missing_secret_key, missing_app_host, client_disabled, client_closed, network_error, api_error (an answer without a code) or unexpected_error. A disabled client sends nothing and fails with client_disabled. A send after shutdown() fails with client_closed. Their name is service_unavailable for network_error, missing_api_key for missing_secret_key, the name of its status for api_error (see Errors), and application_error for the others.
  • Local checks. The SDK checks the form, ids, keys and the idempotency key before any request. A failed check has name validation_error and a code such as invalid_form, invalid_template_id, invalid_template_key, invalid_idempotency_key or invalid_message_id. Type checks only: the server holds the limits.
  • Suppression covers every recipient. When to, a cc or a bcc address is suppressed, PostHog refuses the whole send with 422 recipient_suppressed, and each address uses one unit of the project's sending cap. A spam complaint alone doesn't suppress an address for transactional email, because the recipient needs mail such as receipts and password resets. A bounce, a manual entry, or a complaint from an address that also bounces still suppresses it.
  • Attachment content is never logged and never repeated in an error. The SDK encodes it once, before the retry loop.
  • User-Agent. posthog-python/<version> or posthog-node/<version>. The server reads it as source: sdk. Send attribution in feat(messaging): attribute transactional sends to their source #120628 has to add posthog-python/.
  • Engagement capture. On the code form, capture_engagement defaults to true, so a send captures opens and clicks unless the code passes false. A template sent by template_id follows the project's setting. A project whose admin turned engagement capture off captures nothing, whatever the send asks.
  • No events from the client. The SDK captures no event for a send. The send and its engagement events come from the server only, so nothing is counted twice.
  • Warnings are logged. A send with warnings logs each one once through the client's logger, and returns them.

Errors

Every error body is { type, code, detail, attr, why, fix, docs_url }. code is PostHog's stable code to branch on. name follows Resend's error names, so migrated code that branches on it keeps working.

Status code name Retried
202 Queued. A replayed key returns the first 202 with the same message_id. - -
400 Invalid field, or a check on the request failed: invalid_recipient, sender_not_verified, sender_not_allowed, sender_required, template_not_transactional, transactional_email_paused validation_error No
401 Missing or invalid key, and the SDK's missing_secret_key missing_api_key No
403 The key lacks the scope invalid_permission No
404 No template with this id, or the API is not enabled for the project not_found No
409 template_outdated: PostHog doesn't hold this local template's content, including a key it doesn't know yet. Nothing was sent validation_error The SDK uploads, then sends once more
409 The same idempotency key is still in flight concurrent_idempotent_requests Yes
409 A local-template upload to a key whose content was edited in PostHog. Nothing was sent validation_error No
422 The email can't go out: sending_suspended (the project), sending_paused (this transactional email), recipient_suppressed, recipient_unreachable (the domain takes no email) validation_error No
422 idempotency_key_reused: the key was used with another request. A template send and a code send never share a key invalid_idempotent_request No
429 throttled: rate limited rate_limit_exceeded Yes
429 quota_limited: the project is over its email quota monthly_quota_exceeded No
503 The idempotency store or the email pipeline is down, or the pipeline did not confirm the send. The email may still go out, so retry only with the same idempotency key. service_unavailable Yes
5xx Anything else, and the SDK's unexpected_error application_error No

An answer without a code, such as an HTML 503 from a proxy, is the SDK's api_error. It takes the name and retry of its status in this table, so a 503 is service_unavailable and is retried with the same idempotency key. A status the table doesn't list is application_error, not retried.

A field error names the field in attr, such as cc, headers, tags__0__name or attachments__0__filename, and detail says how to fix it. The server refuses:

  • a cc or bcc entry that is not a bare address (no display name, no quotes, no commas), or more than 10;
  • a header PostHog sets itself (From, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, MIME-Version, Sender, Return-Path, Auto-Submitted, any Content-*, X-PostHog-* or X-SES-*), a header name with spaces or colons, a value with line breaks or non-ASCII characters, a name set twice in another case, or more than 10 headers;
  • a tag name or value with characters other than ASCII letters, numbers, _ and -, a name that starts with ph_, a name used twice, or more than 10 tags;
  • an attachment whose content is not base64 or is empty, more than 10 files or more than 512 KB in total, a file type mailbox providers block (such as .exe), a filename with a path or line break, a content_type that is not a MIME type, or a content_id with < or >.

invalid_recipient, recipient_suppressed and recipient_unreachable let a caller skip a rejected recipient and still send to the others. Every refusal carries why and fix.

Idempotency

  • The store is the one in feat(cdp): add a shared idempotency key store for workflows #120446, used by feat(messaging): add an idempotency key to the transactional email api #120392 and feat(cdp): accept an idempotency key on the transactional email route #120510. There is no second store.
  • Scope transactional-email, shared by template sends and code sends.
  • The fingerprint covers template_id or template_key, to, the distinct ID, message_data and the code content.
  • A template send replays on either URL, /messaging_templates/{id}/send/ or /messaging/send/email/, because both carry the same request. A key first used for a template send and then for a code send, or the other way round, answers 422 idempotency_key_reused.
  • A replay returns the stored 202 before any check runs. This covers a workflow paused since the first send, and a changed default sender when the caller named none. A deleted template, a local template whose content changed, or a project that no longer has a default sender still answers 404, 409 or 400.
  • A caller whose job runner already retries passes max_retries=0 and an idempotency key derived from the email's purpose. A generated UUID doesn't survive a job retry, and the docs say so.

Read (later PR)

GET /api/projects/@current/messaging/emails/{message_id}/ (proposed in the spec, Silthus#531) returns { id, status, created_at, status_at, reason? }.

  • status is one of the values above. It is not Resend's last_event.
  • Unknown ids, and ids in the first seconds after a send, return 404 not_found. No retries.
  • Needs hog_flow:read. Reads have the same rates as sends, in their own buckets, so polling for status can't use up the send budget.

Code sends (decided in spec Silthus#531)

  • Two cases, told apart by template_data. Rendered content travels in the queued job and is never stored as a template version. A local template keeps the code as the source of truth: the SDK sends its hash, and uploads it only when PostHog doesn't hold that content.
  • Workflow per key. A template_key that names a template uses that template's transactional workflow. Any other key gets one workflow on its first send, made under a lock so two first sends make one. Metrics, logs and status group by the key.
  • Changes to feat(messaging): upload, send and lock code-managed email templates #118924's answers: a key PostHog doesn't know yet answers 409 template_outdated, not 404, so the first send of a new local template uploads it. An upload with if_code_managed: true refuses a template edited in PostHog with 409, where an upload today adopts it. An upload without the flag behaves as before.
  • Sensitive by default. A key without a template makes a sensitive workflow, so a send's content stays out of the saved run history and a rerun skips it with a log line instead of sending it again. A key that names a template follows that template's sensitivity setting. The send API has no sensitive field (feat(messaging): send an email with inline html from code #127123).
  • Text. When only html is present, the server derives text. HTML with no text to derive, such as a single image, sends without a text part.
  • Storing rendered HTML as a message asset follows feat(messaging): protect sensitive data on transactional email templates #120520.

Open

Language extras, not part of parity

  • A Python extra needs a line here first, so the two SDKs don't drift.

Not in this contract

Restricted keys limited to senders, the email lookup by address, React content (render it to html in your code), and more than one to address. Each comes as its own PR after the send.

Changes

Activity

  1. posthog commented on Oct 21, 2026

    @posthog
    Contributor

    PostHog self-driving picked up this issue and researched it. Somebody may already be working on it, so ask before you start a fix.

    Report (team access only): https://us.posthog.com/project/2/inbox/reports/01a15dbf-e9de-7228-9c1c-52eb2489380e?link_source=github_comment

  2. mayteio commented on Oct 21, 2026

    @mayteio
    Contributor

    Follow-up notes on the client interface

    Agreed

    • Flat parameters, not content helpers. send takes plain keyword arguments, like Resend's Python SDK, SendGrid and Postmark. html(), text() and library_template() are dropped.
    • Who builds what:
      • posthog-python template sends: Harley, now, starting with standard retries and error handling.
      • The send API for code content (html, text, from, reply_to and the rest) and posthog-node: Michael.

    Proposed for posthog-python

    • Keyword arguments typed with a TypedDict and Unpack, the way capture already works. One @overload per form (template or code content), plus a runtime check that exactly one form is passed. No Pydantic at runtime.

    • Errors raise typed exceptions that carry the same name and code as the contract. Resend's Python SDK raises too. Node keeps { data, error }.

    • A successful send returns the message_id and means the email is queued, not delivered. Docs should say so.

    • v1 takes a single to:

      posthog.emails.send(
          to="user@example.com",
          template_id="<uuid>",
          template_data={...},  # sent as message_data
          distinct_id=user.distinct_id,
          idempotency_key="welcome:user_123",
      )
      
    • v1 sends to the existing /messaging_templates/{id}/send/ by UUID. It moves to /messaging/send/email/ inside the SDK once feat(messaging): upload, send and lock code-managed email templates #118924 lands, with no caller change.

    • AsyncPosthog gets emails too, with an awaitable send.

    Changes to the contract

    1. Retry 429s by code, not status. quota_limited must not be retried. Waiting doesn't fix a monthly quota.
    2. Add an option to turn off SDK retries (for example max_retries=0) for callers whose job runner already retries. The docs should tell those callers to pass an idempotency key derived from the email's purpose. A generated UUID doesn't survive a job retry.
    3. Add a host override for the app host. A host that is a reverse proxy for ingestion is not self-hosted, and it shouldn't receive the secret key. Don't call it api_host, because posthog-js uses that name for the ingestion host.
    4. Send by template_id. Templates created in the UI have no key.
    5. Rename the code-content key to template_key. Next to idempotency_key, a bare key is ambiguous.
    6. Always pass distinct_id in docs and examples. Without it, the send's billed engagement events go to a person keyed by the email address, not the app's user.
    7. Keep invalid_recipient in the 400 list, so callers can skip a rejected recipient and still send to the others.
    8. Add posthog-python/ to send attribution in feat(messaging): attribute transactional sends to their source #120628.

    Open

  3. Silthus commented on Nov 3, 2026

    @Silthus
    ContributorAuthor

    Note

    🤖 Claude Opus 5.5 writing on behalf of Michael

    Contract change approved by Michael on 2026-11-03: a batch section for emails.batch, and a 128 KiB content cap on every send form. The batch builds on the single send and ships behind the same workflows-email-from-code flag.

    New section, after Read (later PR)

    Email batch

    emails.batch(emails) sends up to 100 separate transactional emails in one call. It is not a broadcast: each email is a full single send, in either form, with its own to.

    emails.batch(emails, max_retries?) -> results          # Python returns a list, or raises. Node returns { data: { results }, error }
    
    emails: 1 to 100 send parameter sets, each exactly what send takes except max_retries
    result: what send returns for that email, or the error it would have raised (Python: an EmailError value; Node: { data, error })
    

    Request. POST /api/projects/@current/messaging/send/email_batch/ with { "emails": [ … ] }. Each email is the single send's body. Its idempotency key goes in the email as idempotency_key, not in a header. A batch request with an Idempotency-Key header answers 400 idempotency_key_per_email.

    Answer. When the checks on the whole call pass, the batch answers 200 with { "results": [ … ] }: one result per email, in request order. A queued email's result is the single send's 202 body, { message_id, replayed }. A refused email's result is { "error": { status, type, code, detail, attr } }, the single send's error body for that email plus its HTTP status. A batch where every email is refused still answers 200.

    Errors for the whole call. These queue nothing:

    Status code When
    400 a field code, with attr such as emails__3__to emails is empty or has more than 100 emails, or an email has a field the single send refuses
    400 content_too_large, with attr emails__<i> An email has more than 128 KiB of content
    400 duplicate_idempotency_key Two emails share an idempotency key. detail names both positions
    400 idempotency_key_per_email The request has an Idempotency-Key header
    401, 403 as on send The key is missing or invalid, is not a project secret key, or lacks the scope
    404 not_found The API is not enabled for the project, or not for a form the batch uses
    413 batch_too_large The request body is over 8 MiB
    429 throttled, with Retry-After The batch would cross the send rate limit

    Limits. 100 emails, one to each, 128 KiB of content per email, 8 MiB per request, no attachments.

    Rate. A batch of N emails uses N units of the send rate limits, per key and per project. A batch that doesn't fit answers 429 as a whole and uses none. An email refused later, or replayed, still uses its unit, as a single send does.

    Idempotency. Each email has its own key, with no batch key and no keys from positions. One key dedupes across single sends and batches. The SDK makes a UUID v4 for each email without a key, before the first attempt, and keeps it across retries.

    SDK behavior.

    • error in Node, and a raised EmailError in Python, mean the batch has no result per email. When PostHog answered the whole call with one of the errors above, nothing was queued. After a network error, a timeout or a 503, some emails may have been queued: retry with the same keys. A failed email is a value in its result. Code that checks only error misses failed emails.
    • The SDK's own keys last for one batch call. To retry a failed email or batch in a new call, pass your own stable keys.
    • The SDK retries the whole call only, under send's retry rules, with the same keys. It never retries one email's 503: retry that email yourself with its key.
    • An email whose result is 503 delivery_unavailable may still go out when its detail says so. Retry it only with the same key.
    • The SDK waits at least 45 seconds for a batch, because a batch can take about 30 seconds when the pipeline is slow.
    • The SDK checks each email as send does, and names the email's position in a local error.

    Fields. A batch email takes the fields the single send takes today, in either form, and refuses any other field with its position in attr. A field the single send gains later, such as scheduled_at, reaches the batch when this contract says so. A batch refuses attachments.

    Status. Read each email with emails.get(message_id).

    Edits to existing sections

    • Errors table, the 400 row: add content_too_large to the codes.
    • Errors, after the field-error list: "Every send refuses an email with more than 128 KiB of content with 400 content_too_large. The size is the email as you send it, JSON-encoded, without attachments: subject, html, text, template_data, and later headers and tags. Gmail clips emails over about 102 KB."
    • Errors table, a new row: 413 | batch_too_large: an email batch over 8 MiB | validation_error | No.
    • Changes, a new entry on top: "2026-11-03: emails.batch sends up to 100 separate emails in one call, with one result per email in a 200 (see Email batch). Every send form refuses more than 128 KiB of content per email with 400 content_too_large, attachments left out."
  4. Silthus commented on Nov 3, 2026

    @Silthus
    ContributorAuthor

    Note

    🤖 Claude Opus 5.5 writing on behalf of Michael

    Contract change approved by Michael on 2026-11-03: scheduled sends. send takes scheduled_at up to 30 days ahead, and emails.update, emails.cancel and emails.list manage the waiting emails. It ships behind its own flag, on top of the single send and the batch.

    New section, after Read (later PR)

    Scheduled sends

    send takes scheduled_at to send the email later, up to 30 days after the call. Both forms take it.

    send(..., scheduled_at?: datetime | Date | string)   # ISO 8601 with an offset, such as 2026-12-01T09:00:00Z
    emails.update(id, scheduled_at) -> { id, status, scheduled_at }
    emails.cancel(id)               -> { id, status: "canceled" }
    emails.list(status="scheduled", cursor?, limit?) -> { results: [{ id, to, scheduled_at, created_at }], next }
    

    Send. A time at or before now sends at once. A later time answers 202 with status: "scheduled" and the accepted scheduled_at. A time more than 30 days after the call answers 400 invalid_scheduled_at. A time without an offset answers 400 on scheduled_at; Python refuses a naive datetime before any request.

    Checks. Every check of a send now runs when you schedule. Suppression, pause, suspension, the recipient and the sender are checked again at the send time. A check that fails then fails the email, with its reason in the status. A paused email is not held until the unpause.

    Content and sender. A code send keeps its content, its sender and any from address or name you gave; a part of from you left out comes from the sender at the send time. A template_id send takes its content and sender from the template at the send time.

    Status. GET messaging/emails/{id}/ shows scheduled until the outcome, and canceled after a cancel. It has no scheduled_at; the list has it. An email is readable for 60 days after the call.

    Update. PATCH /api/projects/@current/messaging/emails/{id}/ with { scheduled_at } moves a waiting email. Only the time changes. The limit stays 30 days after the first call; a time at or before now sends at once. 409 already_sending once PostHog has started sending it; 409 canceled after a cancel.

    Cancel. POST /api/projects/@current/messaging/emails/{id}/cancel/ stops a waiting email before PostHog starts sending it: 200, or 409 already_sending. A repeat cancel answers 200 while PostHog can still tell, else 404. Once an email has gone out, cancel and update answer 409 for a few seconds, then 404. A manual rerun of the workflow's run history can send a canceled email again.

    List. GET /api/projects/@current/messaging/emails/?status=scheduled lists waiting emails in send-time order, 100 a page. Needs transactional_email:read. Update and cancel need transactional_email:write. A hog_flow key works for each, as on send.

    Idempotency. scheduled_at is part of the fingerprint: the same key with another time answers 422 idempotency_key_reused. A replay returns the first 202; read the status for the current state. Update and cancel take no key; the SDK retries them like a send. get and list never retry.

    SDK versions. Use an SDK version that takes scheduled_at. From the code-form releases on, an SDK refuses a field it doesn't know before any request. Earlier posthog-node releases drop scheduledAt and send at once.

    Batch. Each email of emails.batch takes scheduled_at as send does.

    Edits to existing sections

    • Client interface, send(...): add scheduled_at?: datetime | Date | string # at most 30 days ahead, ISO 8601 with an offset.
    • Client interface, status: add scheduled and canceled.
    • Errors table, the 400 row: add invalid_scheduled_at. The 409 rows: add already_sending and canceled (cancel and update only), name validation_error, not retried.
    • Changes, a new entry on top: "2026-11-03: send takes scheduled_at, up to 30 days ahead, and emails.update, emails.cancel and emails.list manage waiting emails (see Scheduled sends). Status reads cover 60 days."
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions