From 0584866b17b17b7e7fa048a8755ca86da0f8122a Mon Sep 17 00:00:00 2001 From: Harley Alexander <43975092+mayteio@users.noreply.github.com> Date: Thu, 29 Oct 2026 12:17:53 +0000 Subject: [PATCH 1/4] feat: add the emails capability spec Adds the canonical contract for server-side transactional email: send from a template and read an email's status. Derived from posthog-node and posthog-python. Includes the archived add-emails change, an acceptance feature, and the README index row. Co-Authored-By: Claude Opus 5.5 Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be --- README.md | 1 + acceptance/public/emails.feature | 110 ++++++++ .../2026-10-29-add-emails/.openspec.yaml | 2 + .../archive/2026-10-29-add-emails/design.md | 40 +++ .../archive/2026-10-29-add-emails/proposal.md | 21 ++ .../specs/emails/spec.md | 196 ++++++++++++++ .../archive/2026-10-29-add-emails/tasks.md | 18 ++ openspec/project.md | 2 +- openspec/specs/emails/spec.md | 250 ++++++++++++++++++ 9 files changed, 639 insertions(+), 1 deletion(-) create mode 100644 acceptance/public/emails.feature create mode 100644 openspec/changes/archive/2026-10-29-add-emails/.openspec.yaml create mode 100644 openspec/changes/archive/2026-10-29-add-emails/design.md create mode 100644 openspec/changes/archive/2026-10-29-add-emails/proposal.md create mode 100644 openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md create mode 100644 openspec/changes/archive/2026-10-29-add-emails/tasks.md create mode 100644 openspec/specs/emails/spec.md diff --git a/README.md b/README.md index 335abe90..a127a7c5 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ capability-driven selection. | Capture Exception | [`openspec/specs/capture-exception/spec.md`](openspec/specs/capture-exception/spec.md) | public API | Canonical | | Create Person Profile | [`openspec/specs/create-person-profile/spec.md`](openspec/specs/create-person-profile/spec.md) | public API | Canonical | | Debug | [`openspec/specs/debug/spec.md`](openspec/specs/debug/spec.md) | public API | Canonical | +| Emails | [`openspec/specs/emails/spec.md`](openspec/specs/emails/spec.md) | public API (server) | Canonical | | Exception Steps | [`openspec/specs/exception-steps/spec.md`](openspec/specs/exception-steps/spec.md) | public API | Canonical | | Flush | [`openspec/specs/flush/spec.md`](openspec/specs/flush/spec.md) | public API | Canonical | | Get Anonymous ID | [`openspec/specs/get-anonymous-id/spec.md`](openspec/specs/get-anonymous-id/spec.md) | public API | Canonical | diff --git a/acceptance/public/emails.feature b/acceptance/public/emails.feature new file mode 100644 index 00000000..7473522b --- /dev/null +++ b/acceptance/public/emails.feature @@ -0,0 +1,110 @@ +@public @canonical_behavior @acceptance @emails @server +Feature: Emails + Canonical contract: openspec/specs/emails/spec.md + These scenarios require email harness bindings before integration selection. + + Background: + Given an isolated SDK instance + And the mock PostHog server is reset + + # Requirement: Send request + + Scenario: A send posts the template and its data to the app host + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will accept the next email send with message ID "msg_1" + When the caller sends to "user@example.com" with template ID "0190F6D2-7C1E-7B3A-9F5E-1C2D3E4F5A6B", template data {"name":"Ada"} and distinct ID "user_123" + Then the mock server should receive 1 email send request to "https://us.posthog.com/api/projects/@current/messaging/send/email/" + And the request header "Authorization" should equal "Bearer phs_test" + And the request body should equal JSON {"template":{"id":"0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b"},"to":"user@example.com","message_data":{"name":"Ada"},"identifiers":{"distinct_id":"user_123"}} + And the send result should have ID "msg_1" and replayed false + + # Requirement: Custom host refusal + + Scenario: A custom host without an app host never receives the secret key + Given the SDK is initialized with token "test-token", host "https://proxy.example.com" and secret key "phs_test" + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" + Then the send should fail with error code "missing_app_host" + And the mock server should receive no requests + + # Requirement: Secret key + + Scenario: A client without a secret key sends nothing + Given the SDK is initialized with token "test-token" and host "https://us.i.posthog.com" + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" + Then the send should fail with error code "missing_secret_key" + And the mock server should receive no requests + + # Requirements: Idempotency key, Retryable responses + + Scenario: Retries reuse the generated idempotency key + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will fail the next email send with status 503 + And the mock server will accept the next email send with message ID "msg_1" + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" + Then the mock server should receive 2 email send requests + And both requests should carry the same "Idempotency-Key", which is a UUID v4 + And the send result should have ID "msg_1" + + Scenario Outline: Only responses that waiting can fix are retried + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will fail the next email send with status and code "" + And the mock server will accept the next email send with message ID "msg_1" + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" + Then the mock server should receive email send requests + + Examples: + | status | code | requests | + | 503 | delivery_unavailable | 2 | + | 429 | throttled | 2 | + | 409 | idempotency_key_in_flight | 2 | + | 429 | quota_limited | 1 | + | 422 | recipient_suppressed | 1 | + + # Requirement: Retry timing + + Scenario: A Retry-After over 30 seconds fails at once + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will fail the next email send with status 429, code "throttled" and header "Retry-After: 60" + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" + Then the mock server should receive 1 email send request + And the send should fail with error code "throttled" and a retry-after of 60 seconds + + # Requirements: Error fields, Error names + + Scenario Outline: Errors keep PostHog's code and carry a Resend-style name + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will fail the next email send with status and code "" + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" and a per-send retry limit of 0 + Then the send should fail with error code "", name "" and status + + Examples: + | status | code | name | + | 401 | authentication_failed | missing_api_key | + | 404 | not_found | not_found | + | 422 | idempotency_key_reused | invalid_idempotent_request | + | 422 | recipient_suppressed | validation_error | + | 429 | quota_limited | monthly_quota_exceeded | + + # Requirements: Status read request, Status record + + Scenario: A status read returns the email's status + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will return the email status {"id":"01a18356-c56c-0001-e494-7666bc915188","status":"bounced","created_at":"2026-10-28T16:27:44.364000Z","status_at":"2026-10-28T16:30:02.100000Z","reason":"hard"} + When the caller reads the status of message ID "01A18356-C56C-0001-E494-7666BC915188" + Then the mock server should receive 1 request "GET https://us.posthog.com/api/projects/@current/messaging/emails/01a18356-c56c-0001-e494-7666bc915188/" + And the status record should have status "bounced", reason "hard" and both times + + Scenario: An unknown message ID is not retried + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will fail the next email status read with status 404 and code "not_found" + When the caller reads the status of message ID "01a18356-c56c-0001-e494-7666bc915188" + Then the mock server should receive 1 email status request + And the status read should fail with error code "not_found" + + # Requirement: Disabled client + + Scenario: A disabled client sends nothing + Given the SDK is initialized disabled with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" + Then the send should fail with error code "client_disabled" + And the mock server should receive no requests diff --git a/openspec/changes/archive/2026-10-29-add-emails/.openspec.yaml b/openspec/changes/archive/2026-10-29-add-emails/.openspec.yaml new file mode 100644 index 00000000..5c99d6d7 --- /dev/null +++ b/openspec/changes/archive/2026-10-29-add-emails/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-29 diff --git a/openspec/changes/archive/2026-10-29-add-emails/design.md b/openspec/changes/archive/2026-10-29-add-emails/design.md new file mode 100644 index 00000000..899c68ca --- /dev/null +++ b/openspec/changes/archive/2026-10-29-add-emails/design.md @@ -0,0 +1,40 @@ +## Context + +Sources, in priority order: + +1. The shipped SDKs: posthog-node `packages/node/src/emails/` (`emails.ts`, `errors.ts`, `types.ts`) in PostHog/posthog-js#5418, and posthog-python `posthog/emails.py` in PostHog/posthog-python#1093. +2. The backend: PostHog/posthog `products/messaging/backend/presentation/views/message_templates.py` (`MessagingSendViewSet`, the send serializers and `TransactionalEmailRejected`) and `transactional_email_status.py` (`MessagingEmailsViewSet`). +3. The shared contract in the PostHog/posthog#120921 comment thread, which named the template form, the idempotency key default, and the per-send retry override. + +## Goals / Non-Goals + +**Goals:** + +- One contract every server SDK implements for sending a transactional email and reading its status. +- A retry policy that never sends an email twice and never retries what waiting can't fix. +- Errors that keep PostHog's stable `code`, so a new server code needs no SDK change. + +**Non-Goals:** + +- Client SDKs. The send and status APIs take a secret key, which must stay on a server. +- The code-content form and `capture_engagement`. The send API does not accept them yet. + +## Decisions + +- **Error channel follows the language.** posthog-node returns `{ data, error }` and does not reject, which matches its other awaited methods and the Resend shape. posthog-python raises `EmailError`. Both are idiomatic, so the spec requires the platform's idiomatic channel and forbids both at once, rather than forcing one shape. +- **Local argument checks follow the language.** posthog-node returns a `validation_error` with an `invalid_*` code, and posthog-python raises `TypeError` or `ValueError`. The spec requires the check to happen before any request and allows either channel. +- **Per-send `max_retries` is canonical.** The shared contract named it. posthog-node has it and posthog-python does not, so posthog-python is the SDK to change. +- **The custom-host refusal is canonical.** Both SDKs refuse to send the secret key to a host that is not PostHog Cloud unless the caller names the app host, because a custom host is often an ingestion proxy. +- **The status record keeps native types.** posthog-python returns datetimes and posthog-node returns ISO 8601 strings. The spec requires the timestamps and allows either representation. + +## Conformance at the time of writing + +| Requirement | posthog-node | posthog-python | +| --- | --- | --- | +| Public surface | Pass | Pass | +| Per-send `max_retries` | Pass | Fail: no per-send override | +| All other requirements | Pass | Pass | + +## Risks / Trade-offs + +- Both SDKs had not published when this was written. The contract describes the merged code in the two PRs, and a change before release means a delta here. diff --git a/openspec/changes/archive/2026-10-29-add-emails/proposal.md b/openspec/changes/archive/2026-10-29-add-emails/proposal.md new file mode 100644 index 00000000..c0c8cc87 --- /dev/null +++ b/openspec/changes/archive/2026-10-29-add-emails/proposal.md @@ -0,0 +1,21 @@ +## Why + +Transactional email ships in posthog-node (`posthog.emails`) and posthog-python (`client.emails`, `Emails`, `AsyncEmails`). The two SDKs share a contract that so far lives only in a comment on PostHog/posthog#120921. They agree on the request, the retry policy and the error codes, but they differ in how they report an error, in local argument checks, and in per-send retry overrides. Other server SDKs have no contract to implement against except these two implementations, and the weekly compliance audit does not track email at all. + +This change records one contract for sending a transactional email from a template and reading its status, before more SDKs add it. + +## What Changes + +- New capability spec `emails` for server SDKs, covering: the public surface (`send` and `get`), authentication with a secret key, the app host and the refusal to send the key to a custom host, the send request, the idempotency key, the retry policy, the send result and its warnings, structured errors with PostHog's code and a Resend-style name, the status read, disabled and shut-down clients, and shutdown draining. +- New acceptance feature `acceptance/public/emails.feature`. +- Not in scope: the code-content form (subject and body in the call), the `capture_engagement` send option, and client SDKs. The send API does not accept the first two yet, and a secret key must never reach a client. + +## Capabilities + +### New Capabilities + +- `emails`: server-side transactional email. Sends one email from a transactional template to one recipient, with a stable idempotency key across retries, and reads the email's delivery status by its message ID. + +### Modified Capabilities + +None. diff --git a/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md b/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md new file mode 100644 index 00000000..4c3c7e42 --- /dev/null +++ b/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md @@ -0,0 +1,196 @@ +## ADDED Requirements + +### Requirement: Public surface + +A server SDK SHALL expose transactional email on its client as `emails`, with two operations: `send`, which queues one email from a transactional template, and `get`, which reads the status of an email that `send` queued. An SDK MAY also offer a standalone emails client that does not capture events. + +#### Scenario: The client exposes send and get +- **GIVEN** a server SDK client created with a secret key +- **WHEN** the caller reads `emails` on the client +- **THEN** it offers `send` and `get` + +### Requirement: Email options + +The client SHALL take an optional app host, a per-request timeout with a default of 15 seconds, and a maximum number of retries with a default of 2. `send` SHALL take a per-send maximum number of retries that overrides the client's for that call. + +#### Scenario: Defaults apply when the client sets no email options +- **GIVEN** a client created with a secret key and no email options +- **WHEN** the caller sends an email and every attempt fails with a `503` +- **THEN** the SDK makes 3 attempts in total + +#### Scenario: A per-send retry limit overrides the client's +- **GIVEN** a client whose maximum number of retries is 2 +- **WHEN** the caller sends an email with a per-send maximum of 0 and the first attempt fails with a `503` +- **THEN** the SDK makes 1 attempt and reports the error + +### Requirement: Secret key + +The SDK SHALL authenticate every email request with the client's trimmed secret key, sent as `Authorization: Bearer `. A client without a secret key SHALL report the error `missing_secret_key` without sending a request. The SDK SHALL never put the secret key or the request body in an error message or a log line. + +#### Scenario: A client without a secret key sends nothing +- **GIVEN** a client created without a secret key +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `missing_secret_key` +- **AND** no request is made + +### Requirement: App host + +The SDK SHALL send email requests to the PostHog app host, not the ingestion host. A caller-set app host SHALL win, except that a PostHog Cloud host maps to its region's app host. Without one, `us.i.posthog.com`, `us.posthog.com` and `app.posthog.com` SHALL map to `https://us.posthog.com`, and `eu.i.posthog.com` and `eu.posthog.com` SHALL map to `https://eu.posthog.com`. + +#### Scenario: An ingestion host maps to its region's app host +- **GIVEN** a client whose host is `https://eu.i.posthog.com` and that sets no app host +- **WHEN** the caller sends an email +- **THEN** the request goes to `https://eu.posthog.com/api/projects/@current/messaging/send/email/` + +### Requirement: Custom host refusal + +For a client host that is not PostHog Cloud and no caller-set app host, the SDK SHALL report the error `missing_app_host` without sending a request. A custom host is often an ingestion proxy, which must not receive the secret key. + +#### Scenario: A custom host without an app host is refused +- **GIVEN** a client whose host is `https://proxy.example.com` and that sets no app host +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `missing_app_host` +- **AND** no request is made + +### Requirement: Send request + +`send` SHALL send `POST {app host}/api/projects/@current/messaging/send/email/` with a JSON body holding `template.id` (the template ID in lowercase), `to`, `message_data` (the template data, or an empty object), and `identifiers.distinct_id` only when the caller passed a distinct ID. + +#### Scenario: The template and its data reach the send route +- **WHEN** the caller sends to `user@example.com` with template ID `0190F6D2-7C1E-7B3A-9F5E-1C2D3E4F5A6B`, template data `{"name": "Ada"}` and distinct ID `user_123` +- **THEN** the body is `{"template": {"id": "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b"}, "to": "user@example.com", "message_data": {"name": "Ada"}, "identifiers": {"distinct_id": "user_123"}}` + +### Requirement: Send request headers + +A send SHALL carry `Content-Type: application/json`, `Accept: application/json`, the `Idempotency-Key`, and the SDK's user agent. The SDK SHALL NOT take the distinct ID from a request context. + +#### Scenario: A send without a distinct ID ignores the request context +- **GIVEN** a request context whose distinct ID is `context_user` +- **WHEN** the caller sends an email without a distinct ID +- **THEN** the body has no `identifiers` + +### Requirement: Argument checks + +Before any request, the SDK SHALL check that `to` is one nonempty string, the template ID is a UUID, template data is a mapping, a distinct ID is a nonempty string, an idempotency key is 1 to 255 visible ASCII characters, and a retry limit is a nonnegative integer. A failed check SHALL send no request. + +#### Scenario: A template ID that is not a UUID sends nothing +- **WHEN** the caller sends an email with template ID `welcome` +- **THEN** the SDK reports an argument error +- **AND** no request is made + +### Requirement: Argument error channel + +The SDK MAY report a failed argument check as a validation error with an `invalid_*` code, such as `invalid_template_id`, or raise the language's argument error. It SHALL follow the channel of "Error channel". + +#### Scenario: posthog-node reports an invalid template ID as a validation error +- **GIVEN** posthog-node +- **WHEN** the caller sends an email with template ID `welcome` +- **THEN** the promise resolves to an error with code `invalid_template_id` and name `validation_error` + +### Requirement: Idempotency key + +Every send SHALL carry an `Idempotency-Key`. When the caller passes none, the SDK SHALL generate a UUID v4 for that call. Every attempt of one call, retries included, SHALL send the same key. + +#### Scenario: Retries reuse the generated key +- **GIVEN** a send without an idempotency key +- **WHEN** the first attempt fails with a `503` and the retry succeeds +- **THEN** both attempts send the same `Idempotency-Key` +- **AND** the key is a UUID v4 + +### Requirement: Retryable responses + +The SDK SHALL retry, up to the retry limit, only a network error or timeout, a `409` with code `idempotency_key_in_flight`, a `429` whose code is not `quota_limited`, and a `503`. It SHALL NOT retry any other response, including a `2xx` without a message ID. + +#### Scenario: A monthly quota is not retried +- **WHEN** the first attempt fails with a `429` and code `quota_limited` +- **THEN** the SDK makes 1 attempt and reports the error code `quota_limited` + +### Requirement: Retry timing + +Before retry `n`, counting from 0, the SDK SHALL wait about `2^n` seconds with jitter, at most 30 seconds, or the server's `Retry-After` when that is longer. When `Retry-After` is longer than 30 seconds, the SDK SHALL report the error at once instead of waiting. + +#### Scenario: A long Retry-After fails at once +- **WHEN** the first attempt fails with a `429`, code `throttled` and `Retry-After: 60` +- **THEN** the SDK makes 1 attempt and reports the error with a retry-after of 60 seconds + +### Requirement: Send result + +A `2xx` response SHALL produce a result with the message ID from `message_id`, `replayed` (true only when the response says `true`), and the response's warnings, each with a code, a message and an optional fix. The SDK SHALL log each warning. A result means PostHog queued the email, not that it was delivered. + +#### Scenario: A replay returns the first send's ID +- **WHEN** the response is `202` with `{"message_id": "msg_1", "replayed": true}` +- **THEN** the result has ID `msg_1` and `replayed` true + +### Requirement: Error fields + +An error from a PostHog response SHALL carry the response's `code` unchanged, or `api_error` when it has none. It SHALL carry a message from `detail`, the HTTP status, the field from `attr`, `why`, `fix` and `docs_url` when present, and the server's retry-after. An SDK error without a response, such as `missing_app_host`, SHALL use the same fields with no status. + +#### Scenario: A suppressed recipient keeps PostHog's code +- **WHEN** the response is `422` with `{"code": "recipient_suppressed", "detail": "Nope."}` +- **THEN** the error has code `recipient_suppressed`, message `Nope.` and status 422 + +### Requirement: Error names + +An error SHALL carry a Resend-style `name`, so code that branches on Resend's names keeps working. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. + +#### Scenario: A quota error has the Resend quota name +- **WHEN** the response is `429` with code `quota_limited` +- **THEN** the error name is `monthly_quota_exceeded` + +#### Scenario: A reused idempotency key has the Resend idempotency name +- **WHEN** the response is `422` with code `idempotency_key_reused` +- **THEN** the error name is `invalid_idempotent_request` + +### Requirement: Error channel + +The SDK SHALL report an email error through the language's idiomatic channel and only that channel. An SDK whose awaited methods do not reject, such as posthog-node, SHALL resolve to `{ data, error }` with exactly one of the two set. An SDK that raises errors, such as posthog-python, SHALL raise one email error type. An SDK that resolves instead of raising SHALL report an unexpected internal failure as code `unexpected_error`. + +#### Scenario: posthog-node never rejects a send +- **GIVEN** posthog-node +- **WHEN** a send fails with a `404` +- **THEN** the promise resolves to `{ data: null, error }` with error code `not_found` + +### Requirement: Status read request + +`get` SHALL check that the message ID is a UUID before any request, then send `GET {app host}/api/projects/@current/messaging/emails/{message ID in lowercase}/`. It SHALL use the authentication, host rules and retry policy of a send, with no body and no idempotency key. + +#### Scenario: An unknown message ID is not retried +- **WHEN** the response is `404` with code `not_found` +- **THEN** the SDK makes 1 attempt and reports the error code `not_found` + +### Requirement: Status record + +A `200` from the status read SHALL produce a record with the ID, the status passed through unchanged, the time PostHog queued the email, the time it reached its status, and the reason or null. A response without an ID, a status or either time SHALL produce an `api_error`. The times MAY be native date-times or ISO 8601 strings. + +#### Scenario: A bounced email returns its status and reason +- **WHEN** the response is `200` with `{"id": "01a18356-c56c-0001-e494-7666bc915188", "status": "bounced", "created_at": "2026-10-28T16:27:44.364000Z", "status_at": "2026-10-28T16:30:02.100000Z", "reason": "hard"}` +- **THEN** the record has status `bounced`, reason `hard`, and both times + +#### Scenario: A status the SDK doesn't know passes through +- **WHEN** the response is `200` with a valid record whose status is `archived` +- **THEN** the record has status `archived` + +### Requirement: Disabled client + +A disabled client SHALL send no email request and SHALL report the error `client_disabled`. + +#### Scenario: A disabled client sends nothing +- **GIVEN** a disabled client with a secret key +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `client_disabled` +- **AND** no request is made + +### Requirement: Shutdown + +After the client shuts down, it SHALL send no email request and SHALL report the error `client_closed`. Shutdown SHALL wait for email requests in flight, retries included, to settle before it finishes. + +#### Scenario: Shutdown waits for a send in its retry backoff +- **GIVEN** a send whose first attempt failed with a `503` and that waits to retry +- **WHEN** the caller shuts the client down +- **THEN** shutdown finishes only after the retry settles + +#### Scenario: A shut-down client sends nothing +- **GIVEN** a client that has shut down +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `client_closed` +- **AND** no request is made diff --git a/openspec/changes/archive/2026-10-29-add-emails/tasks.md b/openspec/changes/archive/2026-10-29-add-emails/tasks.md new file mode 100644 index 00000000..ab0ad7a9 --- /dev/null +++ b/openspec/changes/archive/2026-10-29-add-emails/tasks.md @@ -0,0 +1,18 @@ +## 1. Verification + +- [x] 1.1 Inventory posthog-node and posthog-python email behavior from source: surface, options, request, idempotency, retries, errors, status read, shutdown +- [x] 1.2 Check the request and response shapes against the backend send and status views +- [x] 1.3 List the differences between the two SDKs and pick the canonical behavior for each + +## 2. Spec delta + +- [x] 2.1 Write the `emails` delta +- [x] 2.2 Review the delta: every requirement has at least one scenario, and scenarios use WHEN/THEN + +## 3. Acceptance feature + +- [x] 3.1 Add `acceptance/public/emails.feature` with server scenarios for the request, idempotency, retries, host refusal, errors and the status read + +## 4. Archive + +- [x] 4.1 Archive the change, add the Purpose, Applicability and Public surface sections to `openspec/specs/emails/spec.md`, and add the capability to the README table diff --git a/openspec/project.md b/openspec/project.md index d18305a7..f6bfe5d3 100644 --- a/openspec/project.md +++ b/openspec/project.md @@ -20,7 +20,7 @@ Specs now cover three groups of canonical SDK behavior: - **Public SDK APIs** such as capture, capture_ai, identify, groups, feature-flag getters, opt-in/out, session-replay controls, setup, flush, shutdown, property registration, and - server-side AI datasets, AI scorers, and offline evaluation uploads. + server-side AI datasets, AI scorers, offline evaluation uploads, and transactional email. - **Internal SDK components** such as lifecycle handling, autocapture, batching, retry queues, persistent storage, remote config, feature-flag caches/evaluators, exception-event metadata, session management, surveys, consent gating, replay privacy, and client/server tracing-header diff --git a/openspec/specs/emails/spec.md b/openspec/specs/emails/spec.md new file mode 100644 index 00000000..2f99dd34 --- /dev/null +++ b/openspec/specs/emails/spec.md @@ -0,0 +1,250 @@ +# Emails Specification + +## Purpose + +Send one transactional email, such as a password reset or a receipt, from a transactional template in PostHog to one recipient, and read the email's delivery status by its message ID. A send never goes out twice for one call, and an error keeps PostHog's stable code. + +## Applicability + +Server SDKs only. Both operations need a secret key (a project secret API key), which must never reach a client. The reference surfaces are `posthog.emails` in posthog-node and `client.emails`, `Emails` and `AsyncEmails` in posthog-python's `posthog.emails`. Other SDKs can use native names, async conventions, and error channels, as the requirements allow. + +Not covered: the code-content form (subject and body in the call) and the `capture_engagement` send option, which the send API does not accept yet. + +## Public surface + +Names below use posthog-node spelling, then posthog-python spelling. + +| Operation | Inputs and defaults | Result | +|---|---|---| +| `send` | Required `to`, `templateId` / `template_id`; optional `templateData` / `template_data`, `distinctId` / `distinct_id`, `idempotencyKey` / `idempotency_key` (default: a UUID v4 for the call), `maxRetries` (default: the client's) | Send result: `id`, `replayed`, `warnings` | +| `get` | Message ID from a send result | Status record: `id`, `status`, `createdAt` / `created_at`, `statusAt` / `status_at`, `reason` | + +| Client option | posthog-node | posthog-python | Default | +|---|---|---|---| +| Secret key | `secretKey` | `secret_key` | none | +| App host | `appHost` | `app_host` | derived from a PostHog Cloud host | +| Request timeout | `emailRequestTimeoutMs` | `email_request_timeout_seconds` | 15 seconds | +| Maximum retries | `emailRequestMaxRetries` | `email_request_max_retries` | 2 | + +## HTTP mapping + +| Operation | Request | Success | +|---|---|---| +| `send` | `POST {app host}/api/projects/@current/messaging/send/email/` with `{"template": {"id"}, "to", "message_data", "identifiers": {"distinct_id"}}` | `2xx` with `{"message_id", "replayed", "warnings"}` | +| `get` | `GET {app host}/api/projects/@current/messaging/emails/{message_id}/` | `200` with `{"id", "status", "created_at", "status_at", "reason"}` | + +The status is one of `queued`, `sent`, `failed`, `delivered`, `bounced`, or `complained` today, and new statuses can appear. + +## Error names + +| Response | Name | +|---|---| +| `missing_secret_key`, or `401` | `missing_api_key` | +| `400` | `validation_error` | +| `403` | `invalid_permission` | +| `404` | `not_found` | +| `409` with `template_outdated` | `validation_error` | +| Other `409` | `concurrent_idempotent_requests` | +| `422` with `idempotency_key_reused` | `invalid_idempotent_request` | +| Other `422` | `validation_error` | +| `429` with `quota_limited` | `monthly_quota_exceeded` | +| Other `429` | `rate_limit_exceeded` | +| `503`, or a network error | `service_unavailable` | +| Anything else | `application_error` | + +## Requirements + +### Requirement: Public surface + +A server SDK SHALL expose transactional email on its client as `emails`, with two operations: `send`, which queues one email from a transactional template, and `get`, which reads the status of an email that `send` queued. An SDK MAY also offer a standalone emails client that does not capture events. + +#### Scenario: The client exposes send and get +- **GIVEN** a server SDK client created with a secret key +- **WHEN** the caller reads `emails` on the client +- **THEN** it offers `send` and `get` + +### Requirement: Email options + +The client SHALL take an optional app host, a per-request timeout with a default of 15 seconds, and a maximum number of retries with a default of 2. `send` SHALL take a per-send maximum number of retries that overrides the client's for that call. + +#### Scenario: Defaults apply when the client sets no email options +- **GIVEN** a client created with a secret key and no email options +- **WHEN** the caller sends an email and every attempt fails with a `503` +- **THEN** the SDK makes 3 attempts in total + +#### Scenario: A per-send retry limit overrides the client's +- **GIVEN** a client whose maximum number of retries is 2 +- **WHEN** the caller sends an email with a per-send maximum of 0 and the first attempt fails with a `503` +- **THEN** the SDK makes 1 attempt and reports the error + +### Requirement: Secret key + +The SDK SHALL authenticate every email request with the client's trimmed secret key, sent as `Authorization: Bearer `. A client without a secret key SHALL report the error `missing_secret_key` without sending a request. The SDK SHALL never put the secret key or the request body in an error message or a log line. + +#### Scenario: A client without a secret key sends nothing +- **GIVEN** a client created without a secret key +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `missing_secret_key` +- **AND** no request is made + +### Requirement: App host + +The SDK SHALL send email requests to the PostHog app host, not the ingestion host. A caller-set app host SHALL win, except that a PostHog Cloud host maps to its region's app host. Without one, `us.i.posthog.com`, `us.posthog.com` and `app.posthog.com` SHALL map to `https://us.posthog.com`, and `eu.i.posthog.com` and `eu.posthog.com` SHALL map to `https://eu.posthog.com`. + +#### Scenario: An ingestion host maps to its region's app host +- **GIVEN** a client whose host is `https://eu.i.posthog.com` and that sets no app host +- **WHEN** the caller sends an email +- **THEN** the request goes to `https://eu.posthog.com/api/projects/@current/messaging/send/email/` + +### Requirement: Custom host refusal + +For a client host that is not PostHog Cloud and no caller-set app host, the SDK SHALL report the error `missing_app_host` without sending a request. A custom host is often an ingestion proxy, which must not receive the secret key. + +#### Scenario: A custom host without an app host is refused +- **GIVEN** a client whose host is `https://proxy.example.com` and that sets no app host +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `missing_app_host` +- **AND** no request is made + +### Requirement: Send request + +`send` SHALL send `POST {app host}/api/projects/@current/messaging/send/email/` with a JSON body holding `template.id` (the template ID in lowercase), `to`, `message_data` (the template data, or an empty object), and `identifiers.distinct_id` only when the caller passed a distinct ID. + +#### Scenario: The template and its data reach the send route +- **WHEN** the caller sends to `user@example.com` with template ID `0190F6D2-7C1E-7B3A-9F5E-1C2D3E4F5A6B`, template data `{"name": "Ada"}` and distinct ID `user_123` +- **THEN** the body is `{"template": {"id": "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b"}, "to": "user@example.com", "message_data": {"name": "Ada"}, "identifiers": {"distinct_id": "user_123"}}` + +### Requirement: Send request headers + +A send SHALL carry `Content-Type: application/json`, `Accept: application/json`, the `Idempotency-Key`, and the SDK's user agent. The SDK SHALL NOT take the distinct ID from a request context. + +#### Scenario: A send without a distinct ID ignores the request context +- **GIVEN** a request context whose distinct ID is `context_user` +- **WHEN** the caller sends an email without a distinct ID +- **THEN** the body has no `identifiers` + +### Requirement: Argument checks + +Before any request, the SDK SHALL check that `to` is one nonempty string, the template ID is a UUID, template data is a mapping, a distinct ID is a nonempty string, an idempotency key is 1 to 255 visible ASCII characters, and a retry limit is a nonnegative integer. A failed check SHALL send no request. + +#### Scenario: A template ID that is not a UUID sends nothing +- **WHEN** the caller sends an email with template ID `welcome` +- **THEN** the SDK reports an argument error +- **AND** no request is made + +### Requirement: Argument error channel + +The SDK MAY report a failed argument check as a validation error with an `invalid_*` code, such as `invalid_template_id`, or raise the language's argument error. It SHALL follow the channel of "Error channel". + +#### Scenario: posthog-node reports an invalid template ID as a validation error +- **GIVEN** posthog-node +- **WHEN** the caller sends an email with template ID `welcome` +- **THEN** the promise resolves to an error with code `invalid_template_id` and name `validation_error` + +### Requirement: Idempotency key + +Every send SHALL carry an `Idempotency-Key`. When the caller passes none, the SDK SHALL generate a UUID v4 for that call. Every attempt of one call, retries included, SHALL send the same key. + +#### Scenario: Retries reuse the generated key +- **GIVEN** a send without an idempotency key +- **WHEN** the first attempt fails with a `503` and the retry succeeds +- **THEN** both attempts send the same `Idempotency-Key` +- **AND** the key is a UUID v4 + +### Requirement: Retryable responses + +The SDK SHALL retry, up to the retry limit, only a network error or timeout, a `409` with code `idempotency_key_in_flight`, a `429` whose code is not `quota_limited`, and a `503`. It SHALL NOT retry any other response, including a `2xx` without a message ID. + +#### Scenario: A monthly quota is not retried +- **WHEN** the first attempt fails with a `429` and code `quota_limited` +- **THEN** the SDK makes 1 attempt and reports the error code `quota_limited` + +### Requirement: Retry timing + +Before retry `n`, counting from 0, the SDK SHALL wait about `2^n` seconds with jitter, at most 30 seconds, or the server's `Retry-After` when that is longer. When `Retry-After` is longer than 30 seconds, the SDK SHALL report the error at once instead of waiting. + +#### Scenario: A long Retry-After fails at once +- **WHEN** the first attempt fails with a `429`, code `throttled` and `Retry-After: 60` +- **THEN** the SDK makes 1 attempt and reports the error with a retry-after of 60 seconds + +### Requirement: Send result + +A `2xx` response SHALL produce a result with the message ID from `message_id`, `replayed` (true only when the response says `true`), and the response's warnings, each with a code, a message and an optional fix. The SDK SHALL log each warning. A result means PostHog queued the email, not that it was delivered. + +#### Scenario: A replay returns the first send's ID +- **WHEN** the response is `202` with `{"message_id": "msg_1", "replayed": true}` +- **THEN** the result has ID `msg_1` and `replayed` true + +### Requirement: Error fields + +An error from a PostHog response SHALL carry the response's `code` unchanged, or `api_error` when it has none. It SHALL carry a message from `detail`, the HTTP status, the field from `attr`, `why`, `fix` and `docs_url` when present, and the server's retry-after. An SDK error without a response, such as `missing_app_host`, SHALL use the same fields with no status. + +#### Scenario: A suppressed recipient keeps PostHog's code +- **WHEN** the response is `422` with `{"code": "recipient_suppressed", "detail": "Nope."}` +- **THEN** the error has code `recipient_suppressed`, message `Nope.` and status 422 + +### Requirement: Error names + +An error SHALL carry a Resend-style `name`, so code that branches on Resend's names keeps working. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. + +#### Scenario: A quota error has the Resend quota name +- **WHEN** the response is `429` with code `quota_limited` +- **THEN** the error name is `monthly_quota_exceeded` + +#### Scenario: A reused idempotency key has the Resend idempotency name +- **WHEN** the response is `422` with code `idempotency_key_reused` +- **THEN** the error name is `invalid_idempotent_request` + +### Requirement: Error channel + +The SDK SHALL report an email error through the language's idiomatic channel and only that channel. An SDK whose awaited methods do not reject, such as posthog-node, SHALL resolve to `{ data, error }` with exactly one of the two set. An SDK that raises errors, such as posthog-python, SHALL raise one email error type. An SDK that resolves instead of raising SHALL report an unexpected internal failure as code `unexpected_error`. + +#### Scenario: posthog-node never rejects a send +- **GIVEN** posthog-node +- **WHEN** a send fails with a `404` +- **THEN** the promise resolves to `{ data: null, error }` with error code `not_found` + +### Requirement: Status read request + +`get` SHALL check that the message ID is a UUID before any request, then send `GET {app host}/api/projects/@current/messaging/emails/{message ID in lowercase}/`. It SHALL use the authentication, host rules and retry policy of a send, with no body and no idempotency key. + +#### Scenario: An unknown message ID is not retried +- **WHEN** the response is `404` with code `not_found` +- **THEN** the SDK makes 1 attempt and reports the error code `not_found` + +### Requirement: Status record + +A `200` from the status read SHALL produce a record with the ID, the status passed through unchanged, the time PostHog queued the email, the time it reached its status, and the reason or null. A response without an ID, a status or either time SHALL produce an `api_error`. The times MAY be native date-times or ISO 8601 strings. + +#### Scenario: A bounced email returns its status and reason +- **WHEN** the response is `200` with `{"id": "01a18356-c56c-0001-e494-7666bc915188", "status": "bounced", "created_at": "2026-10-28T16:27:44.364000Z", "status_at": "2026-10-28T16:30:02.100000Z", "reason": "hard"}` +- **THEN** the record has status `bounced`, reason `hard`, and both times + +#### Scenario: A status the SDK doesn't know passes through +- **WHEN** the response is `200` with a valid record whose status is `archived` +- **THEN** the record has status `archived` + +### Requirement: Disabled client + +A disabled client SHALL send no email request and SHALL report the error `client_disabled`. + +#### Scenario: A disabled client sends nothing +- **GIVEN** a disabled client with a secret key +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `client_disabled` +- **AND** no request is made + +### Requirement: Shutdown + +After the client shuts down, it SHALL send no email request and SHALL report the error `client_closed`. Shutdown SHALL wait for email requests in flight, retries included, to settle before it finishes. + +#### Scenario: Shutdown waits for a send in its retry backoff +- **GIVEN** a send whose first attempt failed with a `503` and that waits to retry +- **WHEN** the caller shuts the client down +- **THEN** shutdown finishes only after the retry settles + +#### Scenario: A shut-down client sends nothing +- **GIVEN** a client that has shut down +- **WHEN** the caller sends an email +- **THEN** the SDK reports the error code `client_closed` +- **AND** no request is made From 5c21a934a0c02451787d92a6aebd8c3c0bffe967 Mon Sep 17 00:00:00 2001 From: Harley Alexander <43975092+mayteio@users.noreply.github.com> Date: Thu, 29 Oct 2026 12:22:56 +0000 Subject: [PATCH 2/4] docs: describe the email error name as a category Co-Authored-By: Claude Opus 5.5 Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be --- acceptance/public/emails.feature | 2 +- openspec/changes/archive/2026-10-29-add-emails/design.md | 2 +- openspec/changes/archive/2026-10-29-add-emails/proposal.md | 2 +- .../archive/2026-10-29-add-emails/specs/emails/spec.md | 6 +++--- openspec/specs/emails/spec.md | 6 +++--- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/acceptance/public/emails.feature b/acceptance/public/emails.feature index 7473522b..079cb1df 100644 --- a/acceptance/public/emails.feature +++ b/acceptance/public/emails.feature @@ -71,7 +71,7 @@ Feature: Emails # Requirements: Error fields, Error names - Scenario Outline: Errors keep PostHog's code and carry a Resend-style name + Scenario Outline: Errors keep PostHog's code and carry a category name Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" And the mock server will fail the next email send with status and code "" When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" and a per-send retry limit of 0 diff --git a/openspec/changes/archive/2026-10-29-add-emails/design.md b/openspec/changes/archive/2026-10-29-add-emails/design.md index 899c68ca..d0c42255 100644 --- a/openspec/changes/archive/2026-10-29-add-emails/design.md +++ b/openspec/changes/archive/2026-10-29-add-emails/design.md @@ -21,7 +21,7 @@ Sources, in priority order: ## Decisions -- **Error channel follows the language.** posthog-node returns `{ data, error }` and does not reject, which matches its other awaited methods and the Resend shape. posthog-python raises `EmailError`. Both are idiomatic, so the spec requires the platform's idiomatic channel and forbids both at once, rather than forcing one shape. +- **Error channel follows the language.** posthog-node returns `{ data, error }` and does not reject, which matches its other awaited methods. posthog-python raises `EmailError`. Both are idiomatic, so the spec requires the platform's idiomatic channel and forbids both at once, rather than forcing one shape. - **Local argument checks follow the language.** posthog-node returns a `validation_error` with an `invalid_*` code, and posthog-python raises `TypeError` or `ValueError`. The spec requires the check to happen before any request and allows either channel. - **Per-send `max_retries` is canonical.** The shared contract named it. posthog-node has it and posthog-python does not, so posthog-python is the SDK to change. - **The custom-host refusal is canonical.** Both SDKs refuse to send the secret key to a host that is not PostHog Cloud unless the caller names the app host, because a custom host is often an ingestion proxy. diff --git a/openspec/changes/archive/2026-10-29-add-emails/proposal.md b/openspec/changes/archive/2026-10-29-add-emails/proposal.md index c0c8cc87..428be36b 100644 --- a/openspec/changes/archive/2026-10-29-add-emails/proposal.md +++ b/openspec/changes/archive/2026-10-29-add-emails/proposal.md @@ -6,7 +6,7 @@ This change records one contract for sending a transactional email from a templa ## What Changes -- New capability spec `emails` for server SDKs, covering: the public surface (`send` and `get`), authentication with a secret key, the app host and the refusal to send the key to a custom host, the send request, the idempotency key, the retry policy, the send result and its warnings, structured errors with PostHog's code and a Resend-style name, the status read, disabled and shut-down clients, and shutdown draining. +- New capability spec `emails` for server SDKs, covering: the public surface (`send` and `get`), authentication with a secret key, the app host and the refusal to send the key to a custom host, the send request, the idempotency key, the retry policy, the send result and its warnings, structured errors with PostHog's code and a category name, the status read, disabled and shut-down clients, and shutdown draining. - New acceptance feature `acceptance/public/emails.feature`. - Not in scope: the code-content form (subject and body in the call), the `capture_engagement` send option, and client SDKs. The send API does not accept the first two yet, and a secret key must never reach a client. diff --git a/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md b/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md index 4c3c7e42..e1696f5c 100644 --- a/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md +++ b/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md @@ -131,13 +131,13 @@ An error from a PostHog response SHALL carry the response's `code` unchanged, or ### Requirement: Error names -An error SHALL carry a Resend-style `name`, so code that branches on Resend's names keeps working. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. +An error SHALL carry a `name`, a coarse category for callers that branch on the kind of failure rather than the exact code. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. -#### Scenario: A quota error has the Resend quota name +#### Scenario: A quota error has the quota name - **WHEN** the response is `429` with code `quota_limited` - **THEN** the error name is `monthly_quota_exceeded` -#### Scenario: A reused idempotency key has the Resend idempotency name +#### Scenario: A reused idempotency key has the idempotency name - **WHEN** the response is `422` with code `idempotency_key_reused` - **THEN** the error name is `invalid_idempotent_request` diff --git a/openspec/specs/emails/spec.md b/openspec/specs/emails/spec.md index 2f99dd34..ce83b75c 100644 --- a/openspec/specs/emails/spec.md +++ b/openspec/specs/emails/spec.md @@ -185,13 +185,13 @@ An error from a PostHog response SHALL carry the response's `code` unchanged, or ### Requirement: Error names -An error SHALL carry a Resend-style `name`, so code that branches on Resend's names keeps working. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. +An error SHALL carry a `name`, a coarse category for callers that branch on the kind of failure rather than the exact code. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. -#### Scenario: A quota error has the Resend quota name +#### Scenario: A quota error has the quota name - **WHEN** the response is `429` with code `quota_limited` - **THEN** the error name is `monthly_quota_exceeded` -#### Scenario: A reused idempotency key has the Resend idempotency name +#### Scenario: A reused idempotency key has the idempotency name - **WHEN** the response is `422` with code `idempotency_key_reused` - **THEN** the error name is `invalid_idempotent_request` From e5bb7dfb7bf6ac3114a01572c0dd0ae63736b602 Mon Sep 17 00:00:00 2001 From: Harley Alexander <43975092+mayteio@users.noreply.github.com> Date: Thu, 29 Oct 2026 12:38:20 +0000 Subject: [PATCH 3/4] fix: address review on the emails spec - Name a local invalid_* argument error validation_error. - Keep native argument exceptions alongside the single raised email error type. - Bound email draining by the remaining shutdown timeout. - Treat a 2xx without a message ID as api_error, without a retry. Co-Authored-By: Claude Opus 5.5 Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be --- acceptance/public/emails.feature | 9 +++++++ .../specs/emails/spec.md | 25 +++++++++++++----- openspec/specs/emails/spec.md | 26 ++++++++++++++----- 3 files changed, 48 insertions(+), 12 deletions(-) diff --git a/acceptance/public/emails.feature b/acceptance/public/emails.feature index 079cb1df..5d961056 100644 --- a/acceptance/public/emails.feature +++ b/acceptance/public/emails.feature @@ -60,6 +60,15 @@ Feature: Emails | 429 | quota_limited | 1 | | 422 | recipient_suppressed | 1 | + # Requirement: Send response without a message ID + + Scenario: An acceptance without a message ID is an error and is not retried + Given the SDK is initialized with token "test-token", host "https://us.i.posthog.com" and secret key "phs_test" + And the mock server will answer the next email send with status 202 and body {} + When the caller sends to "user@example.com" with template ID "0190f6d2-7c1e-7b3a-9f5e-1c2d3e4f5a6b" + Then the mock server should receive 1 email send request + And the send should fail with error code "api_error" and status 202 + # Requirement: Retry timing Scenario: A Retry-After over 30 seconds fails at once diff --git a/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md b/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md index e1696f5c..edf84773 100644 --- a/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md +++ b/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md @@ -115,12 +115,20 @@ Before retry `n`, counting from 0, the SDK SHALL wait about `2^n` seconds with j ### Requirement: Send result -A `2xx` response SHALL produce a result with the message ID from `message_id`, `replayed` (true only when the response says `true`), and the response's warnings, each with a code, a message and an optional fix. The SDK SHALL log each warning. A result means PostHog queued the email, not that it was delivered. +A `2xx` response with a nonempty string `message_id` SHALL produce a result with that message ID, `replayed` (true only when the response says `true`), and the response's warnings, each with a code, a message and an optional fix. The SDK SHALL log each warning. A result means PostHog queued the email, not that it was delivered. #### Scenario: A replay returns the first send's ID - **WHEN** the response is `202` with `{"message_id": "msg_1", "replayed": true}` - **THEN** the result has ID `msg_1` and `replayed` true +### Requirement: Send response without a message ID + +A `2xx` response whose body is not JSON, or whose `message_id` is missing, empty or not a string, SHALL produce the error `api_error` with the response's HTTP status, and SHALL NOT be retried. + +#### Scenario: An acceptance without a message ID is an error +- **WHEN** the response is `202` with `{}` +- **THEN** the SDK makes 1 attempt and reports the error code `api_error` with status 202 + ### Requirement: Error fields An error from a PostHog response SHALL carry the response's `code` unchanged, or `api_error` when it has none. It SHALL carry a message from `detail`, the HTTP status, the field from `attr`, `why`, `fix` and `docs_url` when present, and the server's retry-after. An SDK error without a response, such as `missing_app_host`, SHALL use the same fields with no status. @@ -131,7 +139,7 @@ An error from a PostHog response SHALL carry the response's `code` unchanged, or ### Requirement: Error names -An error SHALL carry a `name`, a coarse category for callers that branch on the kind of failure rather than the exact code. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. +An error SHALL carry a `name`, a coarse category for callers that branch on the kind of failure rather than the exact code. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. A local argument error with an `invalid_*` code and no HTTP status SHALL be named `validation_error`. #### Scenario: A quota error has the quota name - **WHEN** the response is `429` with code `quota_limited` @@ -143,7 +151,7 @@ An error SHALL carry a `name`, a coarse category for callers that branch on the ### Requirement: Error channel -The SDK SHALL report an email error through the language's idiomatic channel and only that channel. An SDK whose awaited methods do not reject, such as posthog-node, SHALL resolve to `{ data, error }` with exactly one of the two set. An SDK that raises errors, such as posthog-python, SHALL raise one email error type. An SDK that resolves instead of raising SHALL report an unexpected internal failure as code `unexpected_error`. +The SDK SHALL report an email error through the language's idiomatic channel only. An SDK whose awaited methods do not reject, such as posthog-node, SHALL resolve to `{ data, error }` with exactly one set, and SHALL report an unexpected internal failure as `unexpected_error`. An SDK that raises, such as posthog-python, SHALL raise one email error type for request and SDK failures, and MAY keep argument errors as native exceptions. #### Scenario: posthog-node never rejects a send - **GIVEN** posthog-node @@ -182,13 +190,18 @@ A disabled client SHALL send no email request and SHALL report the error `client ### Requirement: Shutdown -After the client shuts down, it SHALL send no email request and SHALL report the error `client_closed`. Shutdown SHALL wait for email requests in flight, retries included, to settle before it finishes. +After the client shuts down, it SHALL send no email request and SHALL report the error `client_closed`. Shutdown SHALL wait for email requests in flight, retries included, to settle. Where shutdown takes a timeout, it SHALL wait for them only within the remaining timeout. #### Scenario: Shutdown waits for a send in its retry backoff -- **GIVEN** a send whose first attempt failed with a `503` and that waits to retry -- **WHEN** the caller shuts the client down +- **GIVEN** a send whose first attempt failed with a `503` and that waits about 1 second to retry +- **WHEN** the caller shuts the client down with a timeout of 30 seconds - **THEN** shutdown finishes only after the retry settles +#### Scenario: Shutdown keeps to its timeout during a retry backoff +- **GIVEN** a send whose first attempt failed with a `503` and that waits about 1 second to retry +- **WHEN** the caller shuts the client down with a timeout of 100 milliseconds +- **THEN** shutdown finishes within about 100 milliseconds + #### Scenario: A shut-down client sends nothing - **GIVEN** a client that has shut down - **WHEN** the caller sends an email diff --git a/openspec/specs/emails/spec.md b/openspec/specs/emails/spec.md index ce83b75c..1f35e1bc 100644 --- a/openspec/specs/emails/spec.md +++ b/openspec/specs/emails/spec.md @@ -50,6 +50,7 @@ The status is one of `queued`, `sent`, `failed`, `delivered`, `bounced`, or `com | `429` with `quota_limited` | `monthly_quota_exceeded` | | Other `429` | `rate_limit_exceeded` | | `503`, or a network error | `service_unavailable` | +| A local `invalid_*` argument error, with no HTTP status | `validation_error` | | Anything else | `application_error` | ## Requirements @@ -169,12 +170,20 @@ Before retry `n`, counting from 0, the SDK SHALL wait about `2^n` seconds with j ### Requirement: Send result -A `2xx` response SHALL produce a result with the message ID from `message_id`, `replayed` (true only when the response says `true`), and the response's warnings, each with a code, a message and an optional fix. The SDK SHALL log each warning. A result means PostHog queued the email, not that it was delivered. +A `2xx` response with a nonempty string `message_id` SHALL produce a result with that message ID, `replayed` (true only when the response says `true`), and the response's warnings, each with a code, a message and an optional fix. The SDK SHALL log each warning. A result means PostHog queued the email, not that it was delivered. #### Scenario: A replay returns the first send's ID - **WHEN** the response is `202` with `{"message_id": "msg_1", "replayed": true}` - **THEN** the result has ID `msg_1` and `replayed` true +### Requirement: Send response without a message ID + +A `2xx` response whose body is not JSON, or whose `message_id` is missing, empty or not a string, SHALL produce the error `api_error` with the response's HTTP status, and SHALL NOT be retried. + +#### Scenario: An acceptance without a message ID is an error +- **WHEN** the response is `202` with `{}` +- **THEN** the SDK makes 1 attempt and reports the error code `api_error` with status 202 + ### Requirement: Error fields An error from a PostHog response SHALL carry the response's `code` unchanged, or `api_error` when it has none. It SHALL carry a message from `detail`, the HTTP status, the field from `attr`, `why`, `fix` and `docs_url` when present, and the server's retry-after. An SDK error without a response, such as `missing_app_host`, SHALL use the same fields with no status. @@ -185,7 +194,7 @@ An error from a PostHog response SHALL carry the response's `code` unchanged, or ### Requirement: Error names -An error SHALL carry a `name`, a coarse category for callers that branch on the kind of failure rather than the exact code. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. +An error SHALL carry a `name`, a coarse category for callers that branch on the kind of failure rather than the exact code. The name SHALL follow the mapping in the Error names table of this spec, which keys on the HTTP status and, for `409`, `422` and `429`, on the code. A local argument error with an `invalid_*` code and no HTTP status SHALL be named `validation_error`. #### Scenario: A quota error has the quota name - **WHEN** the response is `429` with code `quota_limited` @@ -197,7 +206,7 @@ An error SHALL carry a `name`, a coarse category for callers that branch on the ### Requirement: Error channel -The SDK SHALL report an email error through the language's idiomatic channel and only that channel. An SDK whose awaited methods do not reject, such as posthog-node, SHALL resolve to `{ data, error }` with exactly one of the two set. An SDK that raises errors, such as posthog-python, SHALL raise one email error type. An SDK that resolves instead of raising SHALL report an unexpected internal failure as code `unexpected_error`. +The SDK SHALL report an email error through the language's idiomatic channel only. An SDK whose awaited methods do not reject, such as posthog-node, SHALL resolve to `{ data, error }` with exactly one set, and SHALL report an unexpected internal failure as `unexpected_error`. An SDK that raises, such as posthog-python, SHALL raise one email error type for request and SDK failures, and MAY keep argument errors as native exceptions. #### Scenario: posthog-node never rejects a send - **GIVEN** posthog-node @@ -236,13 +245,18 @@ A disabled client SHALL send no email request and SHALL report the error `client ### Requirement: Shutdown -After the client shuts down, it SHALL send no email request and SHALL report the error `client_closed`. Shutdown SHALL wait for email requests in flight, retries included, to settle before it finishes. +After the client shuts down, it SHALL send no email request and SHALL report the error `client_closed`. Shutdown SHALL wait for email requests in flight, retries included, to settle. Where shutdown takes a timeout, it SHALL wait for them only within the remaining timeout. #### Scenario: Shutdown waits for a send in its retry backoff -- **GIVEN** a send whose first attempt failed with a `503` and that waits to retry -- **WHEN** the caller shuts the client down +- **GIVEN** a send whose first attempt failed with a `503` and that waits about 1 second to retry +- **WHEN** the caller shuts the client down with a timeout of 30 seconds - **THEN** shutdown finishes only after the retry settles +#### Scenario: Shutdown keeps to its timeout during a retry backoff +- **GIVEN** a send whose first attempt failed with a `503` and that waits about 1 second to retry +- **WHEN** the caller shuts the client down with a timeout of 100 milliseconds +- **THEN** shutdown finishes within about 100 milliseconds + #### Scenario: A shut-down client sends nothing - **GIVEN** a client that has shut down - **WHEN** the caller sends an email From d25d6ef1d7f1dbc145f406c001ddb514cde62504 Mon Sep 17 00:00:00 2001 From: Harley Alexander <43975092+mayteio@users.noreply.github.com> Date: Thu, 29 Oct 2026 16:54:34 +0000 Subject: [PATCH 4/4] docs: qualify the email dedup promise and Python shutdown conformance - The purpose says one key per call lets PostHog deduplicate retries, instead of promising a send never goes out twice. The design records the pending-reservation gap. - The conformance table pins the assessed revisions, marks Python's per-send max_retries as passing from 5abcf29, and records synchronous Python shutdown draining as a gap. Co-Authored-By: Claude Opus 5.5 Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be --- openspec/changes/archive/2026-10-29-add-emails/design.md | 7 +++++-- openspec/specs/emails/spec.md | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/openspec/changes/archive/2026-10-29-add-emails/design.md b/openspec/changes/archive/2026-10-29-add-emails/design.md index d0c42255..d61bd4f2 100644 --- a/openspec/changes/archive/2026-10-29-add-emails/design.md +++ b/openspec/changes/archive/2026-10-29-add-emails/design.md @@ -11,7 +11,7 @@ Sources, in priority order: **Goals:** - One contract every server SDK implements for sending a transactional email and reading its status. -- A retry policy that never sends an email twice and never retries what waiting can't fix. +- A retry policy that reuses one idempotency key across a call's attempts, so PostHog can deduplicate retries, and never retries what waiting can't fix. PostHog's deduplication has a known gap: if an email is queued but its key's completion record is lost, an attempt that arrives after the 60 second pending reservation expires can queue it again. - Errors that keep PostHog's stable `code`, so a new server code needs no SDK change. **Non-Goals:** @@ -29,10 +29,13 @@ Sources, in priority order: ## Conformance at the time of writing +Assessed at posthog-node `eb01f45` (PostHog/posthog-js#5418) and posthog-python `5abcf29` (PostHog/posthog-python#1093). + | Requirement | posthog-node | posthog-python | | --- | --- | --- | | Public surface | Pass | Pass | -| Per-send `max_retries` | Pass | Fail: no per-send override | +| Per-send `max_retries` | Pass | Pass, from `5abcf29`. Earlier revisions had no per-send override | +| Shutdown | Pass | Partial: async shutdown waits for email requests in flight. Synchronous shutdown closes the session without waiting for a send or a retry running on another thread | | All other requirements | Pass | Pass | ## Risks / Trade-offs diff --git a/openspec/specs/emails/spec.md b/openspec/specs/emails/spec.md index 1f35e1bc..fc67f8a1 100644 --- a/openspec/specs/emails/spec.md +++ b/openspec/specs/emails/spec.md @@ -2,7 +2,7 @@ ## Purpose -Send one transactional email, such as a password reset or a receipt, from a transactional template in PostHog to one recipient, and read the email's delivery status by its message ID. A send never goes out twice for one call, and an error keeps PostHog's stable code. +Send one transactional email, such as a password reset or a receipt, from a transactional template in PostHog to one recipient, and read the email's delivery status by its message ID. Every attempt of one call uses the same idempotency key so PostHog can deduplicate retries, and an error keeps PostHog's stable code. ## Applicability