Repository navigation
feat: send cc, bcc and attachments with emails.send - #1172
Conversation
Takes the flat send body from #1155, and sends a flat distinct_id from the local-template form too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Parks the local-template form (template_data on a code send, the content hash, the upload by key and its retry) and the cc, bcc, headers, tags and attachments fields, to match posthog-node. A code send now takes rendered html and/or text only. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A code send takes cc and bcc as one address or a list, and attachments as files with bytes or Base64 content. The client encodes bytes once, before any retry. A file it can't send raises EmailError with the code invalid_attachment and a field such as attachments__0__content, and the error never repeats the file's content. A template_id send refuses all three fields before any request. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Note 🤖 Claude Opus 5.5 writing on behalf of Michael Decisions for the attachments slice:
|
posthog-python Compliance ReportDate: 2026-11-12T17:14:17.426807+00:00 ✅ All Tests Passed!270/270 tests passed Capture_V1 Tests✅ 95/95 tests passed View Details
Capture_Ai Tests✅ 5/5 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
Feature_Flags_V4 Tests✅ 149/149 tests passed View Details
Feature_Flags_Local_Evaluation Tests✅ 4/4 tests passed View Details
|
next(..., None) used None as its no-match value, so a None key hid the unknown keys after it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
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 |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…/emails-code-attachments # Conflicts: # posthog/emails.py # posthog/test/test_emails.py
A text file passed as a str was sent unchecked as if it were Base64. The client now raises invalid_attachment before any request and hints to pass the file's bytes instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The base PR owns emails-code-form.md, so this PR no longer edits it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Not approved — this change needs a human reviewer.
Re-adding the stamphog label gives the same result unless the changed files change.
stamphog won't review this pull request, because two policy gates refused it. The deny-list gate flagged it for public_api: it adds cc, bcc and attachments to the public posthog.emails types, which shows up in references/public_api_snapshot.txt. The tier gate classified it as T2-never, since it is a cross-cutting feature touching 6 files and 2438 lines.
A human reviewer needs to look at this one. You can ask a maintainer to review it. You could also make it easier to review by splitting it up, for example separating the cc/bcc support from the attachment upload flow.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✗ | matches: public_api |
| size | ✓ | 687L, 3F substantive, 2438L/6F incl. docs/generated/snapshots — within ceiling |
| tier | ✗ | classified as T2-never: T2-never (2438L, 6F, cross-cutting, feat) |
| stamphog 2.7.0 | .stamphog/policy.yml @ unknown · reviewed head f3f5fa3 |
The size check walked back over any number of trailing "=", so a short Base64 string followed by tens of millions of "=" passed as a few bytes, and b64decode then copied and scanned all of it, blocking the async client's event loop. Standard Base64 has at most two "=", so a third now raises invalid_attachment with the Base64 advice during that walk, before any copy. The extra-padding size case is refused this way now. PostHog/michaelr-context#81 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
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 auto-approve this pull request because two gates refused it. The deny-list gate flagged it for public_api, since references/public_api_snapshot.txt changes and new public attributes are added to posthog.emails (cc, bcc, attachments, EmailAttachment). The tier gate classified it as T2-never: a cross-cutting feature of about 2,461 lines across 6 files, including a large rewrite of posthog/emails.py.
A human reviewer needs to look at this one, so please ask a maintainer to review it. Splitting it into smaller pieces, such as the cc/bcc fields separately from the attachment upload flow, may make that review easier, though the public API changes will still need a human.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✗ | matches: public_api |
| size | ✓ | 693L, 3F substantive, 2461L/6F incl. docs/generated/snapshots — within ceiling |
| tier | ✗ | classified as T2-never: T2-never (2461L, 6F, cross-cutting, feat) |
| stamphog 2.7.0 | .stamphog/policy.yml @ unknown · reviewed head b32cc2d |
|
No review started. stamphog started a review of this pull request less than 10 minutes ago, and a label can request at most one review per 10 minutes. The |
There was a problem hiding this comment.
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, because two gates refused it. The deny-list gate matched public_api: references/public_api_snapshot.txt and posthog/emails.py add new public attributes (cc, bcc, attachments on CodeEmailArgs, and the new EmailAttachment type). The tier gate classified the change as T2-never, since it is a cross-cutting feature touching 2461 lines across 6 files. The size gate passed, so size was not the reason.
A human reviewer will need to look at this one. Ask a maintainer for review. You could also split the work into smaller pull requests, but the public API additions will still need a human reviewer.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✗ | matches: public_api |
| size | ✓ | 693L, 3F substantive, 2461L/6F incl. docs/generated/snapshots — within ceiling |
| tier | ✗ | classified as T2-never: T2-never (2461L, 6F, cross-cutting, feat) |
| stamphog 2.7.0 | .stamphog/policy.yml @ unknown · reviewed head b32cc2d |
Go, JS, Ruby and PHP raise attachment_upload_failed for a refused or redirected upload, and the docs list one code for every SDK. The code was upload_failed only in this unreleased change, so it takes the shared name in the error, the tests, the docstrings and the changeset. PostHog/michaelr-context#81 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
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 auto-review this pull request because two policy gates refused it. The deny-list gate flagged it for touching the public API: references/public_api_snapshot.txt gains new CodeEmailArgs fields (cc, bcc, attachments) and a new EmailAttachment type. The tier gate classified it as T2-never, meaning a cross-cutting feature of about 2,461 lines across 6 files, which is never eligible for automatic approval.
Please ask a human reviewer to take this one. If it's practical, you could also split it, for example by landing the cc/bcc support separately from the attachment upload flow, so each piece is smaller and easier to review.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✗ | matches: public_api |
| size | ✓ | 693L, 3F substantive, 2461L/6F incl. docs/generated/snapshots — within ceiling |
| tier | ✗ | classified as T2-never: T2-never (2461L, 6F, cross-cutting, feat) |
| stamphog 2.7.0 | .stamphog/policy.yml @ unknown · reviewed head 7de6993 |
marandaneto
left a comment
There was a problem hiding this comment.
The code looks good; no qualifying findings. Verdict: correct.
Keeps both main's tracking and sensitive fields for code sends and this branch's cc, bcc and attachments. The test fake accepts the new fields. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The two cross-server redirect tests now run against a local PostHog whose storage answers the upload with a 307 to a second local server. They assert the second server receives nothing and no email is sent, instead of injecting the redirect through mocked transports. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
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, because two gates refused it. The deny-list gate flagged it for public_api: references/public_api_snapshot.txt gains new public attributes such as CodeEmailArgs.cc, bcc and attachments, plus a new EmailAttachment type. The tier gate classified it as T2-never, since it is a cross-cutting feature touching 6 files and about 2,495 lines. The size gate passed, so size alone is not the problem.
This needs a human reviewer, so please ask one to review it. If you want to reduce its scope, you could split the work into smaller pull requests, though changes to the public API will still need human review.
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✗ | matches: public_api |
| size | ✓ | 693L, 3F substantive, 2495L/6F incl. docs/generated/snapshots — within ceiling |
| tier | ✗ | classified as T2-never: T2-never (2495L, 6F, cross-cutting, feat) |
| stamphog 2.8.0 | .stamphog/policy.yml @ unknown · reviewed head 174a60b |
* feat: send transactional email with client.emails() Add `client.emails()` with two send forms, `TemplateEmail` for a template made transactional in PostHog and `CodeEmail` for content the app rendered, and `get` for an email's delivery status. Both clients share the argument checks, flat request body, error mapping and retry policy; shutdown refuses new email requests and waits for those in flight within its timeout. New client options: app_host, email_request_timeout_seconds, email_request_max_retries and migrated_from. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(emails): one retry loop per HTTP client, httpmock test server - Each Emails handle retries inside request(); send and get only parse the 2xx reply, so a malformed success is never retried. - The email test server is httpmock's stateful responder instead of a raw TCP server. - New tests pin email_request_timeout_seconds against a slow server, and that it replaces a custom HTTP client's longer timeout. - wait_idle drops an explicit Notified::enable that notify_waiters does not need. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): bound the async shutdown tests' wait for the first request The wait now fails when the send ends without reaching the server, or after 10 seconds, instead of hanging. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): keep Error unwind safe Error::Email holds an EmailError, whose source was a boxed dyn Error. That made posthog_rs::Error lose UnwindSafe and RefUnwindSafe, which it has on main, so code that moves an SDK error across catch_unwind would stop compiling. The source now sits in a newtype that keeps both, and a unit test pins Send, Sync, UnwindSafe and RefUnwindSafe on Error and EmailError. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): read at most 1 MiB of a reply Both clients read an email reply in full, so a hostile or misconfigured app host could make the application buffer an oversized or gzip-expanded body. They now read at most 1 MiB after decompression. A larger body is unreadable, as a failed read was already: an acceptance becomes a retryable network error, and a refusal still counts by its status and Retry-After. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): prove reading stops at the reply cap A raw-socket server claims a 10 MB body, sends 1.1 MiB and holds the connection open. Both clients must report the oversized reply within 5 seconds, well before their 10 second request timeout. A client that read the whole body first fails this test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): wait for email requests when shutdown runs off the runtime `futures::executor::block_on(client.shutdown())`, as the global `posthog_rs::shutdown()` runs it, returned before a send in its retry backoff finished. Off a Tokio runtime, shutdown now blocks the calling thread until the requests end or `shutdown_timeout_ms` passes. From a transport callback it still waits for nothing. Also from the qa-swarm round 2 panel: - `SendEmail` is `#[non_exhaustive]`, so a later send form isn't a breaking change. - `Error::Email` returns the email error's cause from `source()`, so a chain report no longer prints the message twice. - The network-error test proves its retry by the backoff it waits. - One shared rule turns a read body into a reply for both clients, and inline comments became names and docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(emails): send cc, bcc and attachments with a code send A `CodeEmail` takes `cc` and `bcc`, one address per call, and `attachment(EmailAttachment)`. `EmailAttachment::new` encodes the file's bytes as Base64 once; `from_base64` sends encoded content as is, with an optional `content_type` and `content_id`. Empty lists stay off the wire, so an older PostHog still sends a plain email, and a send that does carry one of these fields to a PostHog without it is refused with an error naming the field. `TemplateEmail` has none of these: the template sets its own recipients and content. An attachment's `Debug` output never shows its content. Matches posthog-python (PostHog/posthog-python#1172) and posthog-node (PostHog/posthog-js#5514), against the server contract in PostHog/posthog#127988. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): format the attachment Debug assertions for edition 2018 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(client): prove a transport callback's shutdown waits for no email request Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): script the older server's refusal as PostHog sends it The cross-version live run against PostHog/posthog#127123 answered a send with attachments with 400 validation_error, code invalid_input and attr attachments. The test now scripts that reply instead of a guessed one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(emails): say the attachment limit counts file bytes before Base64 PostHog caps attachments at 512 KB of decoded file content. The method doc and the guide now say so, since Base64 makes the encoded content about a third larger. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * feat(emails): upload attachments by hash, then send their references A code send's files no longer ride inline as Base64. The client hashes each file, asks PostHog which files it lacks, PUTs those to the presigned URLs PostHog returns with only the signed headers, then sends the email naming each file by its SHA-256. It checks 10 files and the 40 MB message estimate before any request, and a refused upload stops the send with the file store's answer. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(emails): format the SHA-256 with the digest's own hex Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): keep the signed upload URL out of errors A failed upload's error drops the presigned URL, whose query signs the upload, and a request that can't be built is an unexpected_error. Tests cover a file attached twice uploading once and a 503 from the file store being retried. The guide names the upload timeout, and the custom client docs say default headers reach the file store too. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): retry the file store's transient server errors An upload now retries the file store's 500, 502 and 504 as well as 503, since a PUT of the same bytes is safe to repeat. PostHog's own 500 is still final. These answers have kind service_unavailable. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * refactor(emails): tidy the upload error's doc and test One doc comment for Upload::request_error, and the signed-URL test reuses closed_url(). Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): pin the body estimate to the server's A body counts like a file: its UTF-8 bytes in Base64 with line breaks, so 57 ASCII bytes count 78 and 57 two-byte characters count 156. The upload refusal's doc names every retried status, and the retry rule names its reason in a helper. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): report an upload-route 404 as not_found on attachments A 404 from the upload route means PostHog has no upload route or sending email from code is off for the project. The client can't tell which, so it reports PostHog's own answer, not_found when the reply named no code, on field attachments, and sends nothing. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(emails): name every cause of an upload-route 404 The NotFound kind covers a send with files to a PostHog without the upload route, and the guide and mapper name a wrong app_host as a third cause. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): keep a supplied client's default headers off the file store When the app supplies http_client or blocking_http_client, uploads go through a client the SDK builds, so the app's default headers, such as a credential, never reach the file store or make it refuse the signed PUT. The SDK's own client still uploads when the app supplies none. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): keep PostHog's code on an upload-route 404 The sdk-specs emails spec carries a response's code unchanged, or api_error when it has none, so an upload-route 404 keeps PostHog's answer and only names attachments as the field. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * docs(emails): say what the upload client takes from a supplied one A supplied client's root certificates, TLS options and in-code proxy don't reach uploads; the SDK-built client trusts the system roots and takes its proxy from the environment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): count the subject in the message estimate The server counts the subject as folded encoded words, 75 bytes for each 42 UTF-8 bytes. Without it, a long subject beside a near-limit file passed the local check, uploaded, and was refused at send. PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): prove uploads against a fake that behaves like PostHog The upload tests now run against an in-memory PostHog and file store that behave like the real ones: the store keeps a file only when its bytes match the signed checksum and no other credentials ride along, and PostHog accepts a send only when each file it names is stored. The size, retry and error-kind cases move from private helpers to public sends. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): build the upload client once per PostHog client With a supplied HTTP client, each send with files built and dropped its own upload client: a runtime thread per send for the blocking flavour, and no connection reuse for either. The PostHog client now keeps the one it built. Tests' closed_url moves to port 1, so a parallel test's server can't take it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): let the fake refuse what PostHog and S3 refuse The fake now takes only POST and JSON on PostHog's routes, refuses a blank subject or a send with no body, answers field_not_accepted when files are off, and issues expired grants or grants for other bytes that its store refuses on its own. Tests read the store's versions and the accepted emails instead of request counts, and the size boundary sends real emails with HTML, text or both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): count derived text and upload only over https Without text, PostHog sends text it derives from the HTML and counts it in the size estimate, so the client now counts the HTML twice. An HTML-only send near the limit was passing the local check, uploading its files, and then being refused. A file store URL that isn't https now fails the send on that attachment before any upload, with a fix to make the store's URL https and no URL in the error. Only an app_host that is plain http itself, the existing way to reach a local PostHog, allows plain-http uploads. No new option. Tests reach the fake PostHog over https through a TLS front with a test certificate. Also adds a test that a refused upload isn't retried, and simplifies the fake's subject check. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): never follow a redirect on an upload An https upload URL could still leak the file: reqwest follows a 307 or 308 on the PUT and re-sends the body, even from https to http. Every upload now goes through the client the SDK builds, which follows no redirect, whether or not the app supplied its own. A 3xx fails that attachment with attachment_upload_failed, names the attachment but not the URL, and sends nothing. A signed upload never succeeds through a redirect. The no-retry test now uses the fake's expired grants and shows the refusal comes back before the first retry could have run, and the https refusal test pins its api_error code, which the guide now names. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * test(emails): redirect uploads to a second behaving store The redirect tests sent the 307 to a scripted server and counted its requests. They now send it to a second fake file store that would keep a correctly signed PUT, and assert that it kept nothing, along with the error, the empty first store and no send. Refs PostHog/michaelr-context#87 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * fix(emails): fail a send whose upload grant overflows the header map HeaderMap::insert panics past 32,768 entries, which a malformed or compromised upload-route reply can reach below the reply size limit. Insert with try_insert so such a reply reads as malformed instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* feat(emails): send transactional email and read its status
Add Client.Emails(), a port of posthog.emails from posthog-node and
posthog-python. Send takes a TemplateEmail (a template made in PostHog,
by ID) or a CodeEmail (content the app rendered, named by a key), posts
the flat body to /api/projects/@current/messaging/send/email/ on the app
host with the project secret key, and retries with one idempotency key.
Get reads /api/projects/@current/messaging/emails/{id}/. Close waits for
email requests in flight.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(emails): retry one request path, settle the Close test
One request method sends, retries and classifies a reply that isn't a 2xx,
so Send and Get parse a successful reply once. The Close test checks the
retry reached the server before Close returned, instead of a race on the
result channel.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): refuse nil emails, keep the context cause, reject trailing bytes
- Send refuses a nil *TemplateEmail or *CodeEmail with invalid_form instead
of panicking.
- When the context ends during a retry wait, the error wraps ctx.Err(), so
errors.Is finds context.DeadlineExceeded.
- A reply that isn't JSON as a whole carries no fields, so a 2xx with
trailing bytes is an api_error.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(emails): assert the shutdown cause on an interrupted send
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): encode request bodies with encoding/json
goccy/go-json's MarshalNoEscape hides its argument from escape analysis, so
a body built on the stack can move while it encodes. The Go 1.21 race tests
caught it reading the template body as garbage and panicking. The email
bodies now use the standard library encoder with HTML escaping off, and a
test pins the HTML as written on the wire.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(emails): close the client in the request timeout test
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): retry an answer cut off mid-body, whatever its status
A dropped connection after a 409's headers lost idempotency_key_in_flight
and became a non-retryable api_error. A failed body read now is a network
error for every status, so the client retries it with the same
idempotency key.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): keep Retry-After on an answer cut off mid-body
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(emails): send cc, bcc and attachments on a code send
A CodeEmail takes Cc, Bcc and Attachments, matching posthog-node
(PostHog/posthog-js#5514) and posthog-python (PostHog/posthog-python#1172)
and the server contract in PostHog/posthog#127988. An EmailAttachment
carries the file's bytes, which encoding/json sends as standard Base64.
An attachment without a Filename or Content fails with invalid_attachment
before any request, and empty lists stay out of the body, so a server that
doesn't take a field yet only sees it when the send uses it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): address the QA swarm panel on the emails API
- Cap EmailRequestMaxRetries and a send's MaxRetries at 9, as MaxRetries
and FeatureFlagRequestMaxRetries are, so one send can't retry for hours
and hold Close.
- Match a PostHog Cloud endpoint written with upper case or the default
:443 port to its app host.
- Keep Retry-After on a 2xx answer that lacks its message ID or status.
- Check UUIDs with google/uuid instead of a second pattern.
- Merge the caller's context and the shutdown context once per request,
which removes the separate shutdown branch of the retry wait.
- Move the reasons in function bodies into named helpers, and correct the
AppHost doc: SecretKey also feeds local flag evaluation on Endpoint.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): one attachment type, and the reply an older PostHog sends
EmailAttachment carries its own JSON names, so the code send encodes it
directly. A blank Filename is refused like a blank address. The test for
a field PostHog doesn't take yet replays the reply PostHog/posthog#127123
gives for it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* feat(emails): upload attachments to file storage, then send references
A CodeEmail's attachments no longer ride inline as Base64. Send checks the
10-file and 40 MB message limits locally, hashes each file with SHA-256, asks
PostHog which files it lacks, PUTs those to the presigned URLs without the
secret key, and sends the email naming each file by its hash. A failed upload
stops the send and surfaces the storage's answer.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* refactor(emails): one attachment type, and refuse an upload slot without a method
Folds the reference type into the attachment the send encodes, refuses an
upload answer that names no method instead of guessing PUT, and tests that the
message limit counts every file together.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): word file storage's refusal and a broken-off upload answer cleanly
A live run against SeaweedFS showed the storage's message ending in two
periods. A broken-off answer to an upload now names file storage, not
PostHog, and is retried like any network error.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): ask again for an expired upload URL, upload a file once, retry storage 5xx
Review round 1 on the upload flow:
- An upload URL that expired while earlier files uploaded is asked for again
before its PUT starts.
- A file attached twice uploads once.
- A storage 500, 502, 503, 504 or 429 is retried within MaxRetries; the daily
upload quota is not.
- The EmailRequestTimeout doc and the changeset say how long an upload may take
and what a PostHog without the upload route answers.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): expire upload URLs by the local clock, name the daily upload quota
An upload URL now expires 15 minutes after PostHog's answer by the client's
own clock, or earlier when PostHog says so, so a clock behind PostHog's
can't keep an expired URL. The daily upload quota gets its own name,
EmailErrorDailyQuotaExceeded. Field names an attachment only when its upload
failed, not when asking PostHog again for its URL failed, and a file PostHog
has by the time it asks again isn't uploaded.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(emails): an upload URL expires 15 minutes after the answer by the local clock
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): honor file storage's Retry-After and retry a stalled upload
A storage refusal keeps its Retry-After, so a throttled upload waits as long
as storage asks, or goes back to the caller when that is longer than the
client retries. S3's RequestTimeout, a 400 for a stalled upload, is retried
like a 5xx. The expiry test now pins the 15-minute lifetime with its own
durations instead of the constant it checks.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): report the upload route's 404 on Attachments as PostHog answered
A 404 from the upload route comes from a PostHog without the route or a
project that can't send email from code. The client can't tell which, so it
keeps PostHog's not_found and its reason, names Attachments, and sends
nothing.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(emails): keep storage's Retry-After when its answer breaks off
Both broken-off upload tests now flush before aborting, so the client reads
a status and headers and then loses the body, the path they name.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): keep a storage redirect's signed Location out of upload errors
Go reads a redirect's Location before any redirect policy runs, and quotes a
Location it can't parse in its error. A storage redirect keeps the request's
signature, so an upload error whose cause names a URL now drops that text,
keeping only whether it was a cancellation or a timeout.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): name storage throttles and upload refusals as the caller knows them
A storage 429 is now a rate limit and S3's RequestTimeout is service
unavailable, so a caller that waits on Name sees the same retry the client
made. An upload route refusal names Attachments or Attachments[i] in Field,
not the route's own files field, which the caller never sent. The duplicate
503 retry test folds into the table test.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): name the right attachment when asking again for its URL is refused
Asking again for an expired URL lists one file, so the route's files__0__
names whichever attachment that was. The refusal now names it by its place
in Attachments.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): count the subject in the message size as PostHog does
PostHog now counts a subject as encoded words, 75 bytes per 42 bytes of
UTF-8, so a long subject could push a near-limit email past what PostHog
takes after the SDK let it through. The docs for the storage-backed error
names now say file storage can be the one that answered.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(emails): time an upload URL's life through Send with the client's clock
The local-clock expiry test called private helpers. The email sender now
reads the client's clock, so the test drives Send with a clock that moves
14 minutes during the first upload and sees the second file's URL asked
for again.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(emails): prove attachments by what storage holds and PostHog delivers
The attachment tests asserted signed paths and header strings against a
bucket that took anything. They now run against a fake bucket that, like
S3, stores a PUT only when it matches what PostHog signed, arrives before
the URL expires and carries the signed checksum, and a fake PostHog that
answers uploads from what storage holds, refuses fields and files it
doesn't take, and records the email it would deliver. Each test asserts
the delivered email or the error, and was mutation-checked.
A storage refusal is retried by its name instead of a separate flag, an
upload's network error says no email was sent, the CodeEmail doc no longer
promises PostHog stores nothing, and a file attached twice is uploaded per
attachment, since only bandwidth told the two apart.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(emails): say each attachment PostHog lacks is uploaded
The changeset still said each missing file uploads once, which held only
while a file attached twice was uploaded once.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): count the text PostHog derives and upload only over https
Without Text, PostHog derives the plain text from the HTML and counts it
in the message size, so an HTML-only email near the limit uploaded its
files and was then refused. The client now counts the HTML twice, since
the derived text is never longer.
An http upload URL from misconfigured storage would carry the file and
its signed URL unencrypted. The client now stops before any upload
unless AllowInsecureAppHost allows plain HTTP for local development.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(emails): say a storage wait past 30 seconds goes back to the caller
The changeset said retries wait as long as storage's Retry-After asks;
the client waits up to 30 seconds and hands a longer wait back in
EmailError.RetryAfter.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(emails): upload a file attached twice once again
A second PUT of bytes storage already holds only added traffic, and a
refusal of it, such as a throttle, failed a send whose file had landed.
The client uploads each hash once again; the test has storage throttle
the redundant upload and the email still goes out.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* test(emails): prove an upload never follows a storage redirect
A 307 from file storage to another host would re-send the file there,
even over http, and report success. The email client already answers a
redirect with the redirect itself; this test pins that from the outside:
the other host receives nothing, the attachment fails without its URL,
and no email is sent. The changeset says uploads never go through a
redirect.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(emails): say retries bound uploads and not_found covers attachments
EmailRequestMaxRetries also bounds each attachment upload's retries, so
Ptr(0) turns those off too. EmailErrorNotFound on Attachments means this
PostHog can't take attachments yet.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs(emails): say not_found on Attachments has two causes
A 404 from the upload route means this PostHog can't take attachments
yet or the project can't send email from code, and the client can't tell
which.
Refs PostHog/michaelr-context#80
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Ports update, cancel and list onto main's request code from #1172: replies are parsed from the raw body, and each call goes through _posthog_request. Keeps both sides' send fields, tests and strict-type checks; the regenerated public API snapshot carries both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
Ticket: PostHog/michaelr-context#81
💡 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.sendtakes renderedhtml/textonly, and files sent inline in the send request would cap a message far below what senders need.Change: the code form takes
cc,bccandattachments. The SDK hashes each file, asks PostHog where to upload the files it lacks, uploads them straight to file storage, then sends the email with each file's hash in place of its bytes.cc/bcc: one address or a list. A string becomes a one-item list on the wire. An empty list is left out, asreply_tois.attachments:{filename, content, content_type?, content_id?}. Content is bytes, any bytes-like, or a Base64 string. The SDK hashes it withhashlib.sha256.too_many_attachments) and a message over 40 MB after Base64 encoding, about 29 MB of files (message_too_large). There is no per-file cap. It counts and sizes the files before it copies or hashes any, so an oversized email costs no memory. A Base64 string is sized by its data, and more than two trailing=is refused asinvalid_attachmentbefore the string is copied, so padding can neither slip a file past the limit nor cost memory. The estimate matches the server's byte for byte: each file and each ofhtmlandtext(as UTF-8 bytes) count as Base64 with line breaks, the subject adds 75 bytes per 42 UTF-8 bytes, plus 64 KiB. Withouttext, the HTML counts twice, because PostHog derives the text from it and the derived text is never longer. Missing or unknown keys and empty content raiseinvalid_attachmentwith afieldsuch asattachments__0__content, and the error never repeats the content.POST /messaging/attachments/uploads/with each distinct file's hash and size, so the same bytes in two attachments upload once. A file PostHog already has comes backpresentand is skipped. For the rest, the SDK sends a plainPUTto the returned URL with exactly the returned headers: no bearer token, none of the client's default params or headers, and no redirect followed: a 3xx answer raisesattachment_upload_failedon that attachment, naming no URL, and sends nothing, since following a 307 or 308 would send the file again to the new address, even over plain HTTP. It uploads only to anhttpsURL: a plain-HTTP upload URL raisesapi_errornaming the attachment before any upload, unless the client's own host is plain HTTP, as in local development. The environment's CA bundle and proxy settings still apply. A refusal from the upload route namesattachments, or the first attachment holding the file it names, never the wire fieldfiles.PUTraisesattachment_upload_failedwith the HTTP status and the bucket's own error code and message, and no email is sent. A storage that is unreachable or answers 429, 500, 502, 503 or 504 is retried like a send. Out of retries, an unreachable storage raisesnetwork_errorwithfieldnaming the attachment, and the signed URL never reaches a traceback.429 upload_quota_exceeded) is not retried.not_foundonfieldattachmentswith PostHog's own reason, and sends nothing. A 404 means a PostHog without the route or sending email from code off for the project, so the SDK names neither and never turns it intofield_not_accepted.template_id, all three fields are refused before any request.trackingandsensitivefrom #1216 in one send.It mirrors posthog-node in PostHog/posthog-js#5514. Server side: PostHog/posthog#131833 (upload route), #131944 (send by reference).
Spec divergence: the emails spec doesn't cover
cc,bccor attachments yet, and its open draft parks them. Follow-up: spec them from this contract.Impact: Grow Workflows. Attachments are part of Resend parity. The server's send event gains attachment counts and sizes, refusals included, which show whether size refusals fall once teams move over.
Merge Danger
Caution
🔴 Merge risk: high · one-way door once released:
cc,bccandattachmentsonemails.sendbecome a public SDK contractcc,bccorattachmentsgo from a localTypeErrorto a real send with copies and files, in both regions. These rows are new, so no base-versus-HEAD proof covers them: a missed bug there could send a copy or a file to the wrong recipient, or expose a bcc, with no error. The tests, the live run and the merge gate's real send exercise them, and the production diff is over 400 lines.mainand this head.attachmentswithfield_not_acceptedbefore any upload.ccandbcchave none: a fault there is fixed forward with a new SDK version.Rollout
💚 How did you test it?
174a60b, after mergingmain: ruff format and check, mypy,import posthogwith warnings as errors, the strict type smoke, the public API snapshot, and the full test suite (7013 passed) pass locally. CI: see the checks on the head.Authorizationheader, an expired URL, mismatched bytes and a wrong method, as S3 does. The tests assert the delivered email, the stored files and the error, never request shapes. The CA trust, redirect and cut-off-answer tests run over real sockets, the CA test with a real TLS handshake. Each fix was red first. Mutations each fail at least one test: keep the session's or the client's Authorization on the PUT, upload a file marked present, ignore the bodies in the estimate, allow an eleventh file, treat a 4xx PUT as success, upload shared bytes twice, stop retrying a storage 500, give storage refusals PostHog's names, drop the attachment from an unreachable-storage error, count files after reading them, check the size after copying, size Base64 including extra padding, allow more than two=of Base64 padding (a 70 MB peak for 40 MB of=), count body characters instead of UTF-8 bytes, count html and text as one body, count raw body bytes, ignoretext, ignore the subject or count its characters, count 43 bytes per encoded word, size padded Base64 by copying it, follow a storage redirect in the async client, follow a storage 307 to a plain-HTTP server (sync and async; without the fix the file reaches that server), misname a storage 429 or 503, count the HTML once withouttext, skip or always skip the https check, name the wire field of an upload refusal, read a storage answer after the upload on a streaming session, dropccorbcc, leave the upload route's 404 bare, drop PostHog's 404 answer, and turn the 404 intofield_not_accepted.emails.send, sync and async, with PostHog and its storage faked behind the transport: the error and itsfield, the bytes storage holds, and the email PostHog delivers (its attachments,ccandbcc, and whether it was sent at all). That covers the skip onpresent, shared bytes stored once, no email after a refused or redirected PUT, retried storage faults, a lost reply replayed by its idempotency key, the limits at the edge (the largest file that fits and one byte more; a 57-byte body counted as 78 bytes and 57 two-byte characters as 156; a 42-byte subject counted as 75 and 43 bytes as 150), and injected clients that carry their own params, headers and redirect settings.174a60b(a local app server and storage server): a storage 500, 429 or async 503 is retried and the email sent; a 403 raisesattachment_upload_failedwith no send; an unreachable storage raisesnetwork_errornaming the attachment, with no signed URL in the traceback.174a60b: the same 24 calls (template and code sends, sends withmain'strackingandsensitive, retries, refusals, quota, status reads; sync and async) throughmainand this head make the same 32 requests and end the same way.1828040, reused at174a60bbecause no upload request in it changes since (the switch-off refusal now namesattachmentsinstead of the server'sfiles, with the same single request, and sincemain's #1216 a send leavescapture_engagementout unless set, PostHog's default): the server PRs' heads merged as fetched, with no server patch, plus SeaweedFS and maildev. New files upload with only the signed headers and deliver byte-identical, with bcc only in the envelope. A file with an explicitcontent_typeand an inline image withcontent_iddeliver as sent. The same files again answerpresentand upload nothing. The same bytes in two attachments upload once and arrive as two files. A tampered upload raises the storage refusal (then namedupload_failed, nowattachment_upload_failed) and sends nothing. A project off the allowlist getsfield_not_accepted. Line-wrapped Base64 raisesinvalid_attachmentbefore any request. The async client delivers.1828040; at174a60bthe gap for cc, bcc and attachments against a live backend is accepted by Michael until the real-send merge gate passes: againstmaster, a send with a file makes one request, the upload ask, and raisesnot_foundonattachmentswith PostHog's own reason ("Endpoint not found."). A plain send still delivers, and a send withccandbccdelivers with the bcc only in the envelope. Against the server PRs with sending email from code off, a send with a file raisesnot_foundonattachmentswith Django's reason ("Not found."), and nothing uploads or sends.Earlier evidence: inline Base64 attachments (
ac102e0)ac102e0: CI green, review clean, and both owed proofs captured.master, a send with these fields got a 400 namingattachmentsand nothing was sent. A plain send still delivered.📝 Checklist
If releasing new changes
sampo addto 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.daily_quota_exceededat once; a rate limit is still retriedattachment_upload_failed, the name Go, JS, Ruby and PHP use, for a refused or redirected upload; renamed fromattachment_upload_failed, which no release carriednot_foundwithfieldattachments; not a bare 404Involvement: reviews: design pass, nine rounds (six of them full nine-lens panels), final reads, and fixes for PostHog Review's findings; ReviewHog unavailable. Proof captured: tests, mutation checks, shadow diff, live run and cross-version.
🤖 Generated with Claude Code