[Silthus]

Problem

A server that sends transactional email with PostHog wants one call on the client it already has. Many teams send HTML their own code rendered, such as React Email output. #5418 added posthog.emails.send() for templates made in PostHog; this PR adds the second form, content from code, on the same call and the same send/email/ URL. The SDK contract is PostHog/sdk-specs openspec/specs/emails/spec.md, plus the draft change add-emails-code-form.

const { data, error } = await posthog.emails.send({
  to: '[email protected]',
  distinctId: user.id,
  templateKey: 'password-reset',
  subject: 'Reset your password',
  html: await render(<PasswordReset url={url} />),
  idempotencyKey: `password-reset:${resetId}`,
})

Moved from Silthus#5.

Caution

Merge risk: high, one-way door. The code form of emails.send(), its exported option types and the migratedFrom client option become public API once released.

Do not merge before the server deploys. The code form depends on the code arm of send/email/ in PostHog/posthog #127122 and #127123. Until both deploy, a code send gets a 400. Merge and release this after them.

Note

Two refusals change for malformed template sends. A send with neither templateId nor templateKey now returns invalid_form, not invalid_template_id. Untyped JavaScript that passes html or subject with templateId is now refused with invalid_form; TypeScript already refuses it.

Changes

• Code form. templateKey, subject, and html, text or both, with optional from and replyTo. send() posts a flat body to POST /api/projects/@current/messaging/send/email/. A string replyTo becomes a one-item list, and an empty list sends no reply-to.
• Flat body in both forms. Every send puts distinct_id at the top level, never identifiers. The template form sends template_id flat, as main has it since feat(node): send a flat body from emails.send #5487.
• One option type per form. SendEmailOptions is a union of SendTemplateEmailOptions and SendCodeEmailOptions, so TypeScript refuses a mix of the two forms.
• One field set per form at runtime. A field the chosen form doesn't take returns invalid_form with its field, before any request. When the other form takes it, why and fix name that form.
• Resend's second argument. send(payload, { idempotencyKey }) returns invalid_form instead of sending with a random key. An undefined second argument still sends.
• Engagement capture is code form only. captureEngagement is sent as capture_engagement, true by default. The template form refuses it.
• migratedFrom client option. Adds X-PostHog-Migrated-From to every emails.send and emails.get request.

Test seams: posthog.emails.send() on a real PostHog client with an injected fetch (emails.spec.ts), and the accepted and refused option shapes as type tests (__tests__/types/emails-forms.ts).

Proof at 8da3b71c2, through fleet proof (the gate passes):

• Live run: code sends and template sends from posthog-node against the server code send at 933d907f3, delivered into a mail catcher. At 8da3b71c2, a code send with replyTo: [] is accepted and delivered, and the old body with reply_to: [] gets a 400.
• Cross-version: this head and the released SDK against master's server, a server with old CDP pods, and the PR server. Master's server answers a code send with a 400.
• Shadow diff: request bodies and results at main and at this head, each difference classified as intended.
• Production shape: posthog-node reads no stored data; the server's sender inputs are measured on #127123.

Release info Sub-libraries affected

Libraries affected

• All of them
• posthog-js (web)
• posthog-js-lite (web lite)
• posthog-node
• posthog-react-native
• @posthog/react-native-plugin
• @posthog/react
• @posthog/ai
• @posthog/convex
• @posthog/next
• @posthog/nextjs-config
• @posthog/nuxt
• @posthog/openfeature-node-provider
• @posthog/openfeature-web-provider
• @posthog/rollup-plugin
• @posthog/webpack-plugin
• @posthog/types
• @posthog/browser-common

Checklist

• All commits are signed (see Commit signing)
• Tests for new code
• Accounted for the impact of any changes across different platforms
• Accounted for backwards compatibility of any changes (no breaking changes!)
• Took care not to unnecessarily increase the bundle size

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

• Written by Claude Code, Claude Opus 5.5 (claude-opus-5-5), as part of map Map: send code-managed email templates with one PostHog call Silthus/posthog#461, directed by Michael. The exact reviewed SHA moved here unchanged.
• Reviews: four GPT-6.1 Sol and Opus 5.5 rounds and four GPT-6.1 Sol final reads on the fork, then a GPT-6.1 Sol fixes round at 933d907f3 and a GPT-6.1 Sol full round at 8da3b71c2.
• 933d907f3 merges main with the flat send body from feat(node): send a flat body from emails.send #5487 (feat(messaging): take template_id and distinct_id at the top of the send body posthog#126287 on the server).
• 8da3b71c2 leaves replyTo: [] out of the body, because the server refuses an empty list. It also names idempotency_key_reused as the error code in the idempotencyKey doc.
• Decisions: both forms send distinct_id flat at the top level, like feat(messaging): take template_id and distinct_id at the top of the send body posthog#126287. Both forms or neither return invalid_form; a template ID that isn't a UUID keeps invalid_template_id.

🤖 Generated with Claude Code

[github-actions]

Coherence

📄 0 spec file errors · ⛔ 0 broken rules · 🚪 2 unchecked inputs · 🐛 0 bugs that came back

What is Coherence?

Coherence compares the code with its spec files (*.spec.md). A spec file lists the rules for one part of the code.

This check read 44 parts of the code and 7 rules.

Note

These findings do not make this check fail.

None of these findings are in files that this pull request changes. You do not need to fix them in this pull request.

🚪 Unchecked inputs (2)

• public api in packages/web/Web.spec.md. The input comes from: host-app.
• webpack plugin in packages/webpack-plugin/Webpack-plugin.spec.md. The input comes from: build.

What this means and how to fix it

Input from outside this code comes in at these places. The spec does not say what checks that input. 10 more places were already like this when Coherence was added. This list does not show them.

To close one of these, find the place by its name in the ## entrances section of its spec file. Add one line under it:

• If all of the input goes through one function that a rule in the spec protects, add guard: <function>.
• If a rule in the spec already checks input from the same source, add the place's name to the entrances: line of that rule.
• If the input needs no check, add control: none - <reason>.

To get the line to add, run npx --no -- coherence scaffold control "<name>".

[github-actions]

Node SDK acceptance v2

Commit: 8da3b71
Workflow run and artifacts

Capture v0

✅ 83 passed / ❌ 4 non-passing / ⚠️ 954 not selected

Drill-down: run artifacts → node-v2-v0 → acceptance/report.json.diagnostics.json (match case_id below).

❌ server_snapshot_payload_false — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:

❌ server_snapshot_payload_zero — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:

❌ server_snapshot_payload_null — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:

❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertion

Flags field differs

Code: flag_request_field

Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134

the first flags request field "geoip_disable" should equal JSON false

Operation: /flags/

Field: geoip_disable

Expected:

false

Actual value:

true

Harness exit: 1; report validation exit: 1.

Capture v1

✅ 148 passed / ❌ 4 non-passing / ⚠️ 889 not selected

Drill-down: run artifacts → node-v2-v1 → acceptance/report.json.diagnostics.json (match case_id below).

❌ server_snapshot_payload_false — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:

❌ server_snapshot_payload_zero — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:

❌ server_snapshot_payload_null — failed_assertion

Expected native data result

Code: snapshot_result

Failed step: acceptance/public/evaluate-flags.feature:868

the public snapshot outcomes should have these semantics:

❌ migration/yaml-parity-v1/remote-flags-v1.feature::Omitted GeoIP settings default to enabled in flag requests — failed_assertion

Flags field differs

Code: flag_request_field

Failed step: migration/yaml-parity-v1/remote-flags-v1.feature:134

the first flags request field "geoip_disable" should equal JSON false

Operation: /flags/

Field: geoip_disable

Expected:

false

Actual value:

true

Harness exit: 1; report validation exit: 1.

[marandaneto]

The code looks good; no qualifying findings. Verdict: correct.

[marandaneto]

Potential customer breaks

The new code-content send form is additive, but the existing email API has a few compatibility changes:

• SendEmailOptions changes from an interface to a union type. Existing interface CustomOptions extends SendEmailOptions declarations or declaration merging will stop compiling.
• Previously ignored extra fields now return invalid_form, so existing JavaScript calls or wrappers passing those fields could stop sending.
• Calls without a form selector now return invalid_form instead of invalid_template_id, which could affect callers branching on that error code.

@Silthus, is it worth preserving compatibility for these cases, or has the existing email API not shipped / not gained users yet? If nobody is using it yet, these changes should not pose a customer compatibility problem.