[Silthus]

💡 Motivation and Context

Problem: an app moving its email from Resend to PostHog can't send a receipt with a PDF, or copy finance on an invoice. posthog.emails.send takes rendered html/text only (#1171).

Change: the code form takes cc, bcc and attachments, as the send contract defines them.

• cc/bcc: one address or a list. A string becomes a one-item list on the wire.
• An empty cc, bcc or attachments list is left out, as feat: send email content from code with posthog.emails.send #1171 does for reply_to, so an older server still sends the email.
• attachments: {filename, content, content_type?, content_id?}. Bytes are Base64-encoded once, before the retry loop. A string is sent as is.
• A path key (Resend style), an unknown key, a missing or empty filename, or content that isn't bytes or a Base64 string raises invalid_attachment with a field such as attachments__0__content. The error never repeats the content.
• With template_id, all three fields are refused before any request.
• The server holds the limits (10 addresses, 10 files, 512 KB). A server without these fields refuses the send with an error naming the field, and never drops them.

Stacked on #1171. It mirrors posthog-node in PostHog/posthog-js#5514.

Impact: Grow Workflows. It removes a blocker for Resend migrations, seen as code sends with migrated_from in project 2.

Merge danger: low, two-way door. The fields are new and optional in an unreleased API. Release this only after the server half deploys; until then a send with these fields gets 400.

💚 How did you test it?

• Proof gate passes at ac102e0: CI green, review clean, and both owed proofs captured.
• StampHog can't approve this PR: its policy sends any public API addition to a human maintainer.
• Test seams: the request body emails.send posts (bytes become Base64, content_type/content_id mapped), the refusals on the template form, and the invalid_attachment cases. The sync and async clients are both covered.
• 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 today's server (feat(messaging): send an email with inline html from code posthog#127123), a send with these fields gets a 400 naming attachments and nothing is sent. A plain send still delivers.

📝 Checklist

• All commits are signed (see Commit signing)
• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran sampo add 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 fields come back from the pre-cut code of #1171 (e654aef), without headers, tags or local templates.

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 does StampHog approve an SDK draft?	Mark it ready for the stamp, then back to draft	👍 Accepted default	comment

Involvement: 2 questions answered. Reviews: GPT-6.1 Sol and Opus 5.5, rounds 1 and 2 and five final reads; StampHog. Proof captured: live run and cross-version.

🤖 Generated with Claude Code

[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]

posthog-python Compliance Report

Date: 2026-11-04T08:44:04.078632+00:00
Duration: 259913ms

✅ All Tests Passed!

121/121 tests passed

---

Capture_V1 Tests

✅ 95/95 tests passed

View Details

Test	Status	Duration
Endpoint And Method.Targets V1 Endpoint	✅	517ms
Endpoint And Method.Does Not Use Legacy Endpoints	✅	511ms
Required Headers.Has Authorization Bearer Header	✅	511ms
Required Headers.Has Content Type Json	✅	510ms
Required Headers.Has Posthog Sdk Info Format	✅	511ms
Required Headers.Has Posthog Attempt Header	✅	510ms
Required Headers.Has Posthog Request Id	✅	511ms
Required Headers.Has Posthog Request Timestamp	✅	511ms
Required Headers.Has User Agent	✅	510ms
Body Format.Body Has Created At And Batch	✅	510ms
Body Format.No Api Key In Body	✅	511ms
Body Format.No Sent At In Body	✅	510ms
Event Format.Event Has Required Root Fields	✅	511ms
Event Format.Event Uuid Is Valid	✅	510ms
Event Format.Event Timestamp Is Rfc3339	✅	510ms
Event Format.Non Utc Event Timestamp Is Converted To Utc	✅	528ms
Event Format.Distinct Id Is String	✅	510ms
Event Format.Distinct Id At Root Not Properties	✅	510ms
Event Format.Custom Properties Preserved	✅	511ms
Event Format.Set Properties Preserved	✅	510ms
Event Format.Set Once Properties Preserved	✅	511ms
Event Format.Groups Properties Preserved	✅	510ms
Event Format.Sdk Generates Uuid If Not Provided	✅	510ms
Event Format.Event Has Required Root Fields Batch	✅	514ms
Event Format.Event Uuid Is Valid Batch	✅	513ms
Event Format.Event Timestamp Is Rfc3339 Batch	✅	514ms
Event Format.Distinct Id Is String Batch	✅	514ms
Event Format.Distinct Id At Root Not Properties Batch	✅	514ms
Event Format.Custom Properties Preserved Batch	✅	513ms
Event Format.Set Properties Preserved Batch	✅	514ms
Event Format.Set Once Properties Preserved Batch	✅	514ms
Event Format.Groups Properties Preserved Batch	✅	514ms
Event Format.Sdk Generates Uuid If Not Provided Batch	✅	514ms
Batch Behavior.Multiple Events In Single Batch	✅	518ms
Batch Behavior.Batch Envelope Smoke	✅	516ms
Batch Behavior.Flush With No Events Sends Nothing	✅	506ms
Batch Behavior.Flush At Triggers Batch	✅	1013ms
Batch Behavior.Created At Reflects Batch Creation Time	✅	510ms
Deduplication.Generates Unique Uuids	✅	518ms
Deduplication.Different Events Same Content Different Uuids	✅	513ms
Deduplication.Preserves Uuid On Retry	✅	6516ms
Deduplication.Preserves Timestamp On Retry	✅	6519ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	6523ms
Deduplication.No Duplicate Events In Batch	✅	518ms
Header Behavior On Retry.Attempt Header Starts At One	✅	510ms
Header Behavior On Retry.Attempt Header Increments On Retry	✅	13527ms
Header Behavior On Retry.Request Id Preserved On Retry	✅	6521ms
Header Behavior On Retry.Different Requests Have Different Request Ids	✅	3019ms
Header Behavior On Retry.Request Timestamp Changes On Retry	✅	6516ms
Response Format Validation.Success Response Has Uuid Keyed Results	✅	511ms
Response Format Validation.Success Response Has Ok For Each Event	✅	515ms
Response Format Validation.Success No Retry After When All Ok	✅	513ms
Response Format Validation.Success Retry After Present When Retry Events	✅	1516ms
Response Format Validation.Success No Retry After When Drop Only	✅	514ms
Response Format Validation.Response Echoes Request Id	✅	510ms
Retry Behavior.Retries On 408	✅	6516ms
Retry Behavior.Retries On 500	✅	6516ms
Retry Behavior.Retries On 503	✅	8523ms
Retry Behavior.Retries On 504	✅	6520ms
Retry Behavior.Retryable Errors Have Retry After	✅	3516ms
Retry Behavior.Respects Retry After On Retryable Error	✅	11517ms
Retry Behavior.Does Not Retry On 400	✅	2513ms
Retry Behavior.Does Not Retry On 401	✅	2513ms
Retry Behavior.Does Not Retry On 402	✅	2514ms
Retry Behavior.Does Not Retry On 413	✅	2512ms
Retry Behavior.Does Not Retry On 415	✅	2514ms
Retry Behavior.Non Retryable Errors Have No Retry After	✅	2513ms
Retry Behavior.Implements Backoff	✅	22526ms
Retry Behavior.Max Retries Respected	✅	22537ms
Partial Batch Handling.Handles 200 Full Success	✅	2513ms
Partial Batch Handling.Handles 200 With All Ok	✅	3516ms
Partial Batch Handling.Does Not Retry Dropped Events	✅	3517ms
Partial Batch Handling.Does Not Retry Limited Events	✅	3515ms
Partial Batch Handling.Prunes Ok Events On Partial Retry	✅	6518ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry	✅	6522ms
Partial Batch Handling.Retries Only Retry Events From Partial	✅	6523ms
Partial Batch Handling.Partial Retry Preserves Uuids	✅	6523ms
Partial Batch Handling.Partial Retry Attempt Header Increments	✅	6522ms
Partial Batch Handling.Partial Retry Request Id Preserved	✅	6519ms
Partial Batch Handling.Respects Retry After On Partial	✅	8521ms
Partial Batch Handling.Unknown Result Treated As Terminal	✅	3516ms
Partial Batch Handling.Mixed Ok Drop Limited No Retry	✅	3520ms
Compression.Sends Gzip Content Encoding	✅	511ms
Compression.No Content Encoding When Disabled	✅	511ms
Compression.Compressed Body Is Decompressible	✅	510ms
Error Handling.Does Not Retry On Unknown 4Xx	✅	2512ms
Event Options.Cookieless Mode Override	✅	512ms
Event Options.Disable Skew Correction Override	✅	511ms
Event Options.Process Person Profile Override	✅	510ms
Event Options.Product Tour Id Override	✅	511ms
Event Options.Unset Options Omitted	✅	510ms
Event Options.Options Override In Batch	✅	515ms
Geoip And Historical Migration.Geoip Disable Injected Into Properties	✅	510ms
Geoip And Historical Migration.Historical Migration Set In Body	✅	512ms
Geoip And Historical Migration.Historical Migration Absent By Default	✅	510ms

Capture_Ai Tests

✅ 5/5 tests passed

View Details

Test	Status	Duration
Routing.Capture Ai Posts To Ai Endpoint	✅	511ms
Routing.Capture Does Not Reroute Ai Named Events	✅	511ms
Identity.Capture Ai Event Has Uuid	✅	511ms
Identity.Capture Ai Keeps Supplied Uuid	✅	511ms
Timestamp Format.Non Utc Event Timestamp Is Converted To Utc	✅	511ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	11ms
Request Payload.Flags Request Uses V2 Query Param	✅	10ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	11ms
Request Payload.Flags Request Omits Authorization Header	✅	10ms
Request Payload.Token In Flags Body Matches Init	✅	9ms
Request Payload.Groups Round Trip	✅	10ms
Request Payload.Groups Default To Empty Object	✅	10ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	11ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	10ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	10ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	509ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	15ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	9ms
Retry Behavior.Retries Flags On 502	✅	314ms
Retry Behavior.Retries Flags On 504	✅	314ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	512ms

Feature_Flags_Local_Evaluation Tests

✅ 4/4 tests passed

View Details

Test	Status	Duration
Versioned Boolean Matching.Matching Version Missing	✅	73ms
Versioned Boolean Matching.Matching Version 1	✅	70ms
Versioned Boolean Matching.Matching Version 2	✅	69ms
Versioned Boolean Matching.Version Only Reload 1 2 1 2 Missing	✅	38ms

[stamphog]

Not approved — this change needs a human reviewer.

Re-adding the stamphog label gives the same result unless the changed files change.

StampHog can't approve this pull request automatically. Two gates refused it. The deny-list gate flagged a public API change: posthog/emails.py adds the EmailAttachment type and new cc, bcc and attachments fields on CodeEmailArgs, and references/public_api_snapshot.txt records them. The tier gate classified the change as T2-never (336 lines across 5 files, cross-cutting, a feature), a tier that is never auto-approved.

The size gate passed, so splitting the pull request won't change the outcome. Ask a human maintainer to review it, since a public API addition needs that sign-off.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✗	matches: public_api
size	✓	124L, 2F substantive, 336L/5F incl. docs/generated/snapshots — within ceiling
tier	✗	classified as T2-never: T2-never (336L, 5F, cross-cutting, feat)
stamphog 2.7.0		.stamphog/policy.yml @ unknown · reviewed head a080862

[veria-ai]

Medium: Bound attachments before encoding

The documented 10-file/512 KB limits are not checked before this comprehension encodes every attachment and _encode materializes the JSON body; an isolated preparation check accepted an 8 MiB file and allocated roughly 32 MiB beyond the original input. As defense in depth for applications forwarding user uploads, check file count and aggregate size before encoding, including bounds for Base64 strings, since server-side rejection cannot protect the host process from these allocations.

[Silthus]

Not changing this. The server owns the 10-file and 512 KB limits, so it can raise them without a new SDK release. A copy of the limits here would drift. The caller already holds the file in memory, and Base64 adds a third to its size. That cost is the caller's choice, and the server refuses the send before anything goes out.

[veria-ai]

PR overview

The PR extends emails.send to support CC and BCC recipients and email attachments, including encoding attachments for the request body.

One issue remains open: attachment count and size limits are not enforced before encoding and JSON serialization, allowing oversized inputs to cause substantial memory allocations in the calling application. This is a defense-in-depth gap for applications forwarding user uploads, since server-side rejection occurs too late to prevent those local allocations. No issues have been addressed yet.

Open issues (1)

• Medium: Bound attachments before encoding — posthog/emails.py:456

Fixed/addressed: 0 · PR risk: 4/10