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..5d961056 --- /dev/null +++ b/acceptance/public/emails.feature @@ -0,0 +1,119 @@ +@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: 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 + 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 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 + 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..d61bd4f2 --- /dev/null +++ b/openspec/changes/archive/2026-10-29-add-emails/design.md @@ -0,0 +1,43 @@ +## 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 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:** + +- 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. 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 + +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 | 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 + +- 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..428be36b --- /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 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. + +## 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..edf84773 --- /dev/null +++ b/openspec/changes/archive/2026-10-29-add-emails/specs/emails/spec.md @@ -0,0 +1,209 @@ +## 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 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. + +#### 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 `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` +- **THEN** the error name is `monthly_quota_exceeded` + +#### 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` + +### Requirement: Error channel + +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 +- **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. 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 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 +- **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..fc67f8a1 --- /dev/null +++ b/openspec/specs/emails/spec.md @@ -0,0 +1,264 @@ +# 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. Every attempt of one call uses the same idempotency key so PostHog can deduplicate retries, 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` | +| A local `invalid_*` argument error, with no HTTP status | `validation_error` | +| 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 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. + +#### 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 `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` +- **THEN** the error name is `monthly_quota_exceeded` + +#### 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` + +### Requirement: Error channel + +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 +- **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. 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 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 +- **THEN** the SDK reports the error code `client_closed` +- **AND** no request is made