[Silthus]

Merge gate: node-store (#77) and django-facade (#78) live in both regions, the allowlist at * in both regions, and a real send through this SDK version with a real project key, delivered and confirmed by Michael. Then the repo's normal release.

Problem

An app moving its email from Resend to PostHog can't send a receipt with a PDF, or copy finance on an invoice. The code form of posthog.emails.send() (#5509) takes rendered html and text only.

Inline Base64 files capped an email at a request body's size. Now the SDK uploads each file to PostHog's file storage by its hash and sends the email with references, so an email carries up to 10 files and about 29 MB. Ticket: PostHog/michaelr-context#82.

Impact: Grow Workflows. It removes a blocker for Resend migrations, seen as code sends with migratedFrom that carry files.

Merge Danger

Caution

🔴 Merge risk: high · one-way door at merge: merging releases posthog-node, and the attachments shape and its error codes become a public contract

• A send with files that fails to upload or send: the email is not sent and the call returns an EmailError, for teams that send files from code, in US and EU. Sends without files take the same path as before, plus a copy of the options at the call.
• Switch-off: the server's per-team env allowlist on the upload route. With a team off, the upload route refuses a send with files before any upload. The SDK itself has no switch: it is live on release, and we fix forward.

Rollout

• Stages: node-store, then django-facade, live in both regions; the allowlist * in both regions; then merge, which releases through the repo's normal release.
• Decided: headers and tags wait for a later slice.
• Watch: the upload route's refusals by code on the server, per django-facade (Capture actions if using toolbar #78). No SDK-side alert exists.

Changes

• cc and bcc: one address or a list. A string becomes a one-item list. An empty list is left out, as feat(node): send email content from code with emails.send #5509 does for replyTo.
• attachments: { filename, content, contentType?, contentId? }. content is a Buffer, a Uint8Array or a Base64 string, at least one byte. An empty list is left out.
• Hash, upload, send: the SDK hashes each file with SHA-256 (crypto.subtle, so the edge runtime works), asks POST /api/projects/@current/messaging/attachments/uploads/ which files PostHog lacks, PUTs each missing file once to the URL PostHog signed, with exactly the headers it returned and no API key, then sends the email with { sha256, filename, content_type?, content_id? } per file. The same file twice uploads once.
• Nothing is sent when an upload fails. A storage refusal returns attachment_upload_failed with the storage's status and reason; a network failure or a timeout returns network_error, and a timeout's fix names emailRequestTimeoutMs. The ask retries like the send does; each PUT also retries a storage 429 or 5xx, since it resends the same bytes and checksum to the same URL.
• Refused before any request, with the server's codes: more than 10 files (too_many_attachments), an email over 40 MB after Base64 encoding (message_too_large, the server's estimate over the files, both bodies and the subject; without text, the html counts twice, since PostHog derives the text from it), an empty file, and every shape invalid_attachment already covered. The size check runs on each file's length before any copy or decode, so an oversized file costs no extra memory.
• Uploads only over https. Before any upload, an upload URL that isn't https returns api_error on that attachment, saying to fix the file storage's URL, without the URL, and nothing is sent. A client whose appHost is plain HTTP, which is local development, may upload over plain HTTP too; there is no new option. Uploads don't follow redirects either, so storage can't send a file on to another URL: a 307 or 308 returns attachment_upload_failed on that attachment. The option rides on the email sender's own fetch options, so @posthog/core and the public API don't change; a custom fetch may ignore it.
• emails/attachments.ts holds validation, the size limit, decoding and hashing. emails.ts keeps HTTP, retries and the upload protocol.
• A 404 on the upload route comes from a PostHog without the route, or from sending email from code being off for the project. The SDK can't tell them apart, so it returns PostHog's own not_found on attachments, with its reason, and sends nothing.
• The options are copied at the call, so a caller that changes them while the files upload doesn't change the email.
• Template form: templateId with any of the three returns invalid_form, and the types refuse it.

There is no sdk-specs spec for the code form or attachments yet (openspec/specs/emails/spec.md covers the template send), so no divergence to call out.

Evidence

Lane gate green at e7b0a0c, 1678 of 1678 tests in each runtime: check-types, lint, format, the posthog-node unit tests and test:edge-compat (every node spec under the edge runtime). The worktree box can't start for this repo, so the gate ran locally under fleet heavy.

• Test seams: posthog.emails.send() on a real client whose fetch is an in-memory PostHog and file store (__tests__/utils/emails-fake.ts). It checks each request the way the services do: the key, both routes' schemas, the allowlist, the message estimate, signed-URL expiry, length and checksum, attachment_not_uploaded, idempotency, and an older server's refusal of cc or bcc. Tests assert what the caller gets back and what was stored and sent. Faults are injected only as a status, a network error, a hang, a lost reply, or a server that recovers after a set number of refusals. The accepted and refused shapes are type tests.
• Retries proven by outcome: a refusal the SDK must not retry sends nothing even though the next request would succeed; storage that fails, answers too late, or drops the connection as often as the retries allow still delivers; one failure more sends nothing. Mutating each retry rule, and each retry budget by one either way, fails the test written for it.
• Red, then green: the new attachment tests fail on the inline Base64 code and pass at ceda104. Each review fix added its test red first: storage retries, the timeout message, error names and caller field names at 2b2c3be, the storage 429 retry at ab5800e, PostHog's own 404 answer at afa528f, an older PostHog's refusal of cc or bcc at 367d337, and a project that can't send files yet, refused on attachments, at b3ee911. Boundary tests pin how the size check counts html and text: 57 ASCII bytes count 78, and 57 two-byte characters count 156, as PostHog's estimate does. The subject counts 75 bytes for each 42 UTF-8 bytes, as node-store's estimate does since feat(cdp): send transactional email files by reference posthog#131944: a 42-byte subject counts 75, 43 bytes 150, 21 two-byte characters 75, 22 of them 150, and an empty subject nothing. Each case sends the largest file that fits beside it and refuses one byte more; the tests failed before the subject term (a01858a). An html-only email that fits with the html counted once but not twice is refused before any request, and sent once it has a short text. An upload URL that isn't https is refused before any upload on the attachment it belongs to, and a plain-HTTP appHost uploads over plain HTTP. An upload that storage redirects returns attachment_upload_failed, and nothing reaches the redirect target. These failed before 00e5bc1, 3e4e0cc and c38ed50.
• Live run at e7b0a0c: the built SDK with real fetch, against a fake PostHog API that presigns uploads the way the server's store does, and a real S3-compatible bucket that checks each signed PUT.
  • New files upload, arrive byte-identical, and the email goes out by hash, with cc and bcc. A duplicate file uploads once.
  • The same files again: PostHog has them, so the SDK asks and sends, with no upload.
  • Bytes changed in flight: the bucket refuses the checksum, the SDK returns attachment_upload_failed, and nothing is stored or sent.
  • The largest file an email with empty bodies and a short subject carries uploads and sends; one byte more is refused with no request.
  • An html-only email whose html fits once but not twice is refused with no request; the same email with a short text uploads and sends.
  • The run's API and bucket are plain HTTP on localhost, so every upload goes through the plain-HTTP appHost opt-in.
  • A storage that answers the PUT with a 307 to another origin, with real Node fetch: the build before c38ed50 followed it, re-sent the file there and sent the email; e7b0a0c stops at the 307, the other origin receives nothing, and nothing is sent.
• Shadow diff at e7b0a0c, against the merge base after main came in: 13 send shapes the base already accepts (template and code form, every replyTo shape, template data with a Date, a toJSON object and undefined values, unicode), with and without migratedFrom, post byte-identical requests on the merge base and on this branch. The options copy at the call changes nothing on the wire.
• Cross-version at e7b0a0c: against today's PostHog Cloud in US and EU, which has no upload route yet, a send with a file makes one request, gets 404, returns not_found on attachments with PostHog's reason, and sends nothing. A send with cc and bcc and no file skips the upload route and posts both as lists to the send route; the run's fake key stops it at authentication, and the SDK reports that answer unchanged.
  • An older PostHog that takes the send but not cc or bcc answers field_not_accepted on that field. A real key is needed to reach that answer live, so a test replays Django's refusal through the public send: the SDK returns it as a validation_error on cc or bcc, with PostHog's reason and fix, without a retry. It fails when the mapping breaks or the SDK retries.
  • A project that can't send files yet gets field_not_accepted from the upload route, naming files. The SDK reports it on attachments, the field the caller passed, and sends nothing. A test replays the server's refusal, and it failed with files before the fix.
• Gap: an end-to-end run against the real API, including a live older server refusing cc or bcc, needs a real secret key and waits for node-store and django-facade to deploy. That run is the merge gate above, and Michael accepted this gap until it passes. Opening (including the into module v1.4.2 fails to build #79) is the slice that proves it.

Earlier evidence: the inline Base64 cut at 8dd465b

• Live run: a send with to, two cc, one bcc, a binary PDF and an inline PNG went through a local PostHog with the server stack (feat(cdp): deliver transactional email attachments from a side table posthog#127986, #127988) to maildev. The files arrived byte-identical, the PNG inline, and the bcc only in the envelope.
• Cross-version: against the server of the time (feat(messaging): send an email with inline html from code posthog#127123), a send with these fields got a 400 naming attachments and nothing was sent. A plain send still delivered.
• Shadow diff: 12 sends the base already accepts (template and code form, every replyTo shape) posted byte-identical requests on the base and on this branch.
• StampHog approved 0d5386b of that cut.

The Python twin is PostHog/posthog-python#1172.

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, for Michael. The rework merged main and replaced inline Base64 with hash, upload, send. A design pass by GPT-6.1 Sol ran before the PR body changed.

Question	Answer	Who	Where
Which code-form fields ship in the attachments slice?	Attachments, cc and bcc. Headers and tags wait for a later slice	👍 Accepted default	comment
How do files reach PostHog?	Hash, upload what PostHog lacks, send by reference; replaces inline Base64	👍 Accepted default	PostHog/michaelr-context#82
What does a 404 on the upload route answer?	PostHog's own not_found on attachments, nothing sent; replaced the field_not_accepted mapping	👍 Accepted default	comment
How do local limits fail?	With the server's codes, before any request	🤖 Agent	comment
Does the SDK estimate sends without files?	No: the server estimates only sends with files, and its request cap covers the rest	🤖 Agent	comment
Uploads in parallel or one by one?	One by one, each with the client's request timeout	🤖 Agent	comment
Which options does the email carry?	A copy taken at the call	🤖 Agent	comment
Which file storage failures retry?	A 429 or any 5xx; a 4xx fails at once	🤖 Agent	comment
Which field does an upload-route refusal name?	The caller's: files becomes attachments, files__<i> the caller's attachments__<j>	🤖 Agent	comment
Which local-development opt-in allows plain-HTTP uploads?	A plain-HTTP appHost; no new option	🤖 Agent	comment
Does an upload follow a file storage redirect?	No: a redirect returns attachment_upload_failed; core's fetch options stay as they are	🤖 Agent	comment
How do the tests reach PostHog?	An in-memory PostHog and file store that check requests like the services; replaced the queued fetch replies	🤖 Agent	comment

Involvement: 2 questions answered on the earlier cut. Reviews: the design pass (GPT-6.1 Sol); a panel of 11 lenses on Opus 5.5 and GPT-6.1 Sol with the client libraries team's perspectives, then two fix rounds and three final reads; a second full panel of 11 lenses on the final code, three fix rounds that moved every test outside-in, final reads four to six, a seventh round on the subject term (correctness, spec conformance and compatibility lenses), an eighth on the derived text and https uploads (adding a security lens), whose redirect finding is fixed, a ninth on that fix, two on a test-fake change that cleared a CodeQL alert (one finding, fixed), one on moving the redirect option off core's shared type after CI's public API check, and one on a docblock the proof judge flagged, all clean at the end; PostHog Review on each push (one finding on c38ed50, on signed URLs expiring during very slow uploads, answered and declined), clean on e7b0a0c; the earlier cut's rounds. CodeRabbit skipped: no slot for this stack. Proof captured: live run, cross-version and shadow diff.

🤖 Generated with Claude Code

[posthog]

PostHog Review · Standard · reviewed ccb14b5: 1 Should fix.

This is the only automatic review while this pull request is a draft. Comment @posthog review to review new changes sooner. Otherwise, a review of the new changes runs when you mark it ready for review.

See this review and its findings in PostHog Review. Comment @posthog review --deep for a Deep review. A Deep review takes longer and looks deeper than a Standard review.

[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: f13c1e0
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.

[github-actions]

Replay incident risk check

The current diff no longer matches any past incident pattern.

No incident-pattern matches for 12 changed file(s) vs origin/main.

[Silthus]

Note

🤖 Claude Opus 5.5 writing on behalf of Michael

Decisions for the attachments slice:

• 👍 Which code-form fields ship in the attachments slice? Attachments, cc and bcc. Headers and tags wait for a later slice.
• 👍 How does StampHog approve an SDK draft? StampHog doesn't review drafts, so this PR goes ready only for the stamp, then back to draft.

[github-actions]

Download bundle size visualization

[stamphog]

Not approved — this change needs a human reviewer.

Re-add the stamphog label to request another review once you have addressed this.

Independent assurance and STRONG author familiarity cover the risky areas, but @PostHog's substantive inline concern remains unfixed. Address the encoding concern in packages/node/src/emails/emails.ts with native Node encoding and an edge-compatible fallback, or obtain a non-author acceptance in the thread, before re-requesting.

• Author wrote 100% of the modified lines and has 0 merged PRs in these paths (familiarity STRONG).
• PostHog Review (Standard) reviewed the current head: no findings.
• @PostHog, packages/node/src/emails/emails.ts: the open performance concern remains unaddressed. base64Of still spreads byte chunks into JavaScript arguments, builds intermediate strings, and calls btoa rather than using native Node encoding; attachment conversion runs synchronously before the request.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	171L, 4F substantive, 290L/7F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1c-medium (290L, 7F, two-areas, feat)
stamphog 2.7.0		.stamphog/policy.yml @ 5a1a78e · reviewed head 5a1a78e

[posthog]

PostHog Review · Standard · reviewed 9bcebfc: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

[posthog]

PostHog Review · Standard · reviewed 7da8f5b: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

[posthog]

PostHog Review · Standard · reviewed 93df0bc: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

[marandaneto]

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

[posthog]

PostHog Review · Standard · reviewed e7b0a0c: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

New commits were pushed — dismissing the stamphog approval from an earlier head. Re-add the trigger label to request a fresh review.

[posthog]

PostHog Review · Standard · reviewed 80dfd49: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

New commits were pushed — dismissing the stamphog approval from an earlier head. Re-add the trigger label to request a fresh review.

[posthog]

PostHog Review · Standard · reviewed a708379: no findings. This pull request is large, so the review ran in 4 parts with less depth than usual.

New commits were pushed — dismissing the stamphog approval from an earlier head. Re-add the trigger label to request a fresh review.

[stamphog]

Not approved — escalated to a human reviewer.

Re-add the stamphog label to request another review once you have addressed this.

The risky changes lack independent assurance on the current head; all supplied formal reviews cover older commits, and the discussion summary does not establish current-head coverage. Request a current-head review from Harley Alexander, Vincent (Wen Yu) Ge, or another teammate before re-requesting.

• Risky territory without independent assurance: Public API contracts — packages/node/src/emails/types.ts and packages/node/src/exports.ts expose attachment options and copy recipients as supported SDK inputs, while packages/node/src/emails/errors.ts adds attachment-specific error classification.; Data ingestion or write paths — packages/node/src/emails/emails.ts:244–279 requests storage uploads, writes missing attachment bytes, and includes file references in email sends.; Auth or security-sensitive surface — packages/node/src/emails/emails.ts:263–285 authenticates upload preparation and controls transport security, redirect handling, and headers for file transfers.; Crypto/secrets — packages/node/src/emails/attachments.ts:202–204 computes SHA-256 identifiers used to deduplicate files and reference uploaded content.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	588L, 7F substantive, 2055L/13F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1d-complex (2055L, 13F, two-areas, feat)
stamphog 2.8.0		.stamphog/policy.yml @ 7257879 · reviewed head 7257879