[Silthus]

Part of the code-first rebuild of posthog-node's email API; replaces PostHog#5373.

Problem

A team moving from Resend sends receipts with a PDF, copies to a shared inbox, and tags for their own analytics. This PR adds cc, bcc, headers, tags and attachments to the code form, rendered content and local templates alike.

Stacks on #7. Needs the server's fields and attachments arms of send/email/.

Impact

Same as the stack: Grow Workflows, billed workflows_emails from API sends. These fields remove the most common reason a Resend caller cannot switch.

Merge Danger

Caution

🔴 Merge risk: high · one-way door (merge-risk rubric)

• New public option names and wire fields, and attachment content (customer files) through the SDK. The SDK never logs content and no error repeats it; the limits stay on the server.

Changes

Kind	Files	Lines (this PR, against #7)
Production	2	+110 −9
Tests	2	+137 −0
References and changesets	2	+102 −2

• Code form only. A template send with one of these fields returns invalid_form on that field instead of sending without it. The types refuse them there too.
• On the wire, each left out when absent: cc and bcc (a string becomes a one-item list), headers and tags as given, attachments as { filename, content, content_type?, content_id? } with a Buffer or Uint8Array as Base64.
• Once per send. Attachments are encoded when the body is built, before retries and the local template's hash. The upload never carries these fields.
• Refused before any request: a Resend path, content that is not a Buffer, Uint8Array or string, or attachments that is not a list, as invalid_attachment named validation_error with field: attachments__<n>__....
• Equal to the reviewed feat(node): send cc, bcc, headers, tags and attachments with a code send PostHog/posthog-js#5373, plus capture_engagement sent true when absent; the five fields join the code form's field set from feat(node): send transactional email from code with emails.send #5.

Evidence

• Test seams: posthog.emails.send() on a real client with FakeEmailsApi; the accepted and refused shapes as type tests.
• What the tests pin: each field's mapping row on rendered content and on a local template; Base64 for Buffer and Uint8Array; one encoding across retries and the resend after upload; each invalid_attachment and invalid_form refusal; no attachment content in an error.
• Local gate on d5097112: node vitest (1340 passed), edge (1340 passed), tsc, oxlint, oxfmt, build, references committed; core vitest.
• Owed proofs:
  • Live run (an email with cc, a tag and a PDF into the dev mail catcher): gap until the server arms exist.
  • Cross-version (these fields against a server without them): a 400 invalid_request naming the field in field; live check stays a gap.
  • Production shape: gap until read-only production access is available.

Decisions

No load-bearing decisions.

Involvement: carries the PostHog#5373 review rounds; a fresh HEAD read and a final read on the restack (both clean), no live proof yet.

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 Opus 5.5 (claude-opus-5-5) in Claude Code, as build lane js2 of map Map: send code-managed email templates with one PostHog call posthog#461, directed by Michael. The code comes from the reviewed stack feat(node): send transactional email with the flat SDK contract PostHog/posthog-js#5312, feat(node): send email content from code, uploading local templates by hash PostHog/posthog-js#5371, feat(node): send cc, bcc, headers, tags and attachments with a code send PostHog/posthog-js#5373 and feat(node): read an email's status with emails.get PostHog/posthog-js#5372 (closed; fork copies feat(node): send transactional email with the flat SDK contract #1–feat(node): read an email's status with emails.get #4), restacked code-first. The equality with each reviewed head is checked by diff and listed in the lane ledger.
• Reviews: GPT-6.1 Sol and Claude Opus 5.5 lanes through T3 Code, per the qa-swarm panel.

🤖 Generated with Claude Code

[github-actions]

Coherence

4 spec problems · 0 failing chokepoints · 2 spec gaps · 0 guard failures

44 components, 7 bullets (5 invariants, 2 requirements), 4 problems

Spec problems (spec --check)

• packages/ai/src/otel/Otel.spec.md:7 an invariant bullet starts with <name>: <sentence>
• packages/ai/src/otel/Otel.spec.md:8 an invariant bullet starts with <name>: <sentence>
• Posthog-js.practice.md:20 practice add an invariant cites 187a5c5, which is no commit in this repository
• Posthog-js.practice.md:20 practice add an invariant cites 8922ab2, which is no commit in this repository

Chokepoints: none declared.

Spec gaps: 2 entrances with outside or unknown trust and no traced control, and 10 more held by the adoption baseline

• packages/web/Web.spec.md entrance public api (trust host-app): packages/web
• packages/webpack-plugin/Webpack-plugin.spec.md entrance webpack plugin (trust build): packages/webpack-plugin

Close one with guard: <chokepoint>, an invariant that names it on its entrances: line, or control: none — <reason>; scaffold control proposes it.

[github-actions]

Node SDK compliance v2

Commit: fb9640e
Workflow run and artifacts

Capture v0 — acceptance

✅ 28 passed / ❌ 3 non-passing / ⚠️ 853 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:

Harness exit: 1; report validation exit: 1.

Capture v1 — acceptance

✅ 28 passed / ❌ 3 non-passing / ⚠️ 853 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:

Harness exit: 1; report validation exit: 1.

Capture v0 — migration

✅ 55 passed / ❌ 1 non-passing / ⚠️ 101 not selected

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

❌ 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 — migration

✅ 120 passed / ❌ 1 non-passing / ⚠️ 36 not selected

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

❌ 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.