[Silthus]

💡 Motivation and Context

A Go backend can't send transactional email through PostHog today. posthog-go has no emails API, while posthog-node and posthog-python send by template and, in PostHog/posthog-js#5509 and PostHog/posthog-python#1171, by rendered content too. This PR adds Client.Emails(). Send takes a template made in PostHog, by its ID, or content your code rendered, named by a key. Get reads the email's status by its message ID. Part of map Silthus/posthog#461.

result, err := client.Emails().Send(ctx, posthog.CodeEmail{
	To:          "[email protected]",
	DistinctID:  "user_123",
	TemplateKey: "password-reset",
	Subject:     "Reset your password",
	HTML:        renderedHTML, // React email: render it to HTML in your app first
})

Impact

Pays into Grow Workflows through workflows_emails billed actions, which count API sends (measured on the team's Workflows usage dashboard). In scope: Messaging, transactional email. Expected move: small, up, as it opens API sends to Go backends. Run cost: n/a.

Caution

Merge risk: medium, one-way door once released.

• A release makes the Emails API, the EmailError codes and four Config fields a public contract.
• Client gains the Emails method, so a type that implements Client itself stops compiling until it adds one. posthog-go added Flush the same way, in a minor release.
• Release only after feat(messaging): send an email with inline html from code posthog#127123 and feat(cdp): deliver a code send's content on its own transactional email route posthog#127122 deploy. Both forms post the flat body from the contract (Transactional email SDK contract for posthog-python and posthog-node posthog#120921), the same body that posthog-python's main sends since feat: send a flat body from emails.send posthog-python#1155. Today's server still takes the nested template.id body, so until then every Send gets a 400 required on template. Get already works. The cross-version run below shows both.

What changes

• Client.Emails() returns Emails, with Send(ctx, Email) and Get(ctx, messageID). A no-op client's Emails refuses every call with client_disabled.
• Two forms, one Send. Email is sealed and has two types, in the style of Enqueue(Message):
  • TemplateEmail{To, TemplateID, TemplateData, DistinctID, IdempotencyKey, MaxRetries} posts template_id and message_data.
  • CodeEmail{To, TemplateKey, Subject, HTML, Text, From, ReplyTo, CaptureEngagement, DistinctID, IdempotencyKey, MaxRetries} posts a flat body. CaptureEngagement is a *bool, so it is on unless set to false.
• Requests go to POST /api/projects/@current/messaging/send/email/ and GET /api/projects/@current/messaging/emails/{id}/ on the app host, with Config.SecretKey as the bearer token: the project secret API key that the flag poller already uses. The app host is Config.AppHost, or the app host of a PostHog Cloud Endpoint (us.i goes to us.posthog.com, eu.i to eu.posthog.com), matched without regard to case, a trailing slash or port 443. Any other endpoint, such as a proxy, needs AppHost: email requests never go to Endpoint.
• Arguments are checked before any request, as Node and Python check them: the recipient, the template ID, the template key, the subject and body, ReplyTo, the idempotency key and MaxRetries. The client state comes next: disabled, closed, no app host, no secret key.
• Every send carries an idempotency key, a UUID v4 unless you pass one, kept across retries. Network errors, idempotency_key_in_flight, 429 except quota_limited, and 503 retry up to Config.EmailRequestMaxRetries (default 2) or a send's MaxRetries, each 0 to 9 like the client's other retry options. The wait is 2^n s with jitter, at most 30 s, or Retry-After when longer. A Retry-After over 30 s fails at once. Get retries the same way, as both reference SDKs do.
• Errors are *EmailError values with PostHog's Code, Message, Why, Fix, DocsURL, Field, StatusCode and RetryAfter, plus a coarse Name from the spec's table. errors.Is finds ErrSDKDisabled, ErrClosed and context.DeadlineExceeded through Unwrap. An error never holds the secret key or the request body.
• Warnings in a 202 are logged and returned in SendEmailResult.Warnings.
• Close waits for email requests in flight within its context, then cancels them.
• New Config fields: AppHost, EmailRequestTimeout (default 15 s), EmailRequestMaxRetries and MigratedFrom, which sets X-PostHog-Migrated-From. Validate checks each.
• Out of scope for now: local templates (TemplateData on a code send, the content hash, the upload by key), headers, tags, and any rendering dependency. Cc, bcc and attachments come in #408, stacked on this PR. The app renders the email and passes HTML.

Spec divergence. PostHog/sdk-specs openspec/specs/emails/spec.md covers the template form and the status read. The code form and CaptureEngagement go beyond it, matching posthog-node in PostHog/posthog-js#5509 and posthog-python in PostHog/posthog-python#1171.

💚 How did you test it?

Test seams: Client.Emails().Send and .Get on a real client built with NewWithConfig, against an httptest server or a fake transport. The tests pin each body and header, each refusal before a request, each error code and Name, retries, Retry-After, the request timeout, a cancelled context, a closed or disabled client, and Close during a retry wait. Three Example functions document the API.

Gate at 80ee4a5 passes: gofmt -l, go mod tidy with no diff, go vet ./..., go test -race ./..., bin/api-diff against the regenerated api/public-api.txt, and the otel and posthogmcpsdk modules. A full go test -race ./... under Go 1.21.13, the module's floor, passes too.

Live run at 8e181df against a local PostHog stack: Django at PostHog/posthog#127123 (51409d9), cdp-api and the email and hogflow workers at PostHog/posthog#127122 (b5889c9), and maildev. A Go program drove the branch through a recording proxy. All six cases passed:

Case	Observed
TemplateEmail by ID with TemplateData	202 with an ID; the mail rendered the data
CodeEmail with HTML, Text, From, ReplyTo, CaptureEngagement: false	202; the mail had that subject, html, text, from and reply-to; the body carried capture_engagement: false
The same send twice with one IdempotencyKey	Same ID; Replayed false, then true; one mail
From on an unverified domain	*EmailError sender_not_verified, validation_error, HTTP 400; no mail
Get on the code send's ID	sent, with CreatedAt and StatusAt
A wrong secret key	*EmailError authentication_failed, missing_api_key, HTTP 401

Cross-version run at 8e181df against master's server (762afdf), without the two server PRs. Both send forms get a 400 required on template, because master still takes the nested body. Get reads a status once it exists: it gets a not_found for the first seconds, then sent. An unknown ID gets not_found.

The raw request and response pairs, the maildev readbacks and the driver are saved with fleet proof. After it, 5417c2d closes a client in one unit test, and 8cef8a9 and c7d0a9c make an answer cut off mid-body a retryable network error for every status that keeps its Retry-After (found by PostHog Review and the fleet review). The live cases never hit those paths. Then a QA swarm panel (round 7: fresh eyes on Claude, eight lenses on GPT-6.1 Sol) led to 80ee4a5: the 0 to 9 retry range, Cloud host matching without regard to case or port 443, RetryAfter kept on an accepted reply without a message ID, uuid.Validate in place of a regex, one cancellation path in request, and the AppHost doc. Each fix has a test that fails without it. Those paths don't change what the live cases sent or received. The narrow round 8 on the fixes found nothing in the code.

Shadow diff at 80ee4a5 against main (fee6566): the same 26 inputs (capture with and without feature flags, identify, alias, group identify, exception, every Enqueue type, remote and local flag evaluation with PersonalApiKey and SecretKey, Flush, Close twice, Enqueue after Close) give the same requests, return values, errors and log lines on both. Each side matches four repeat runs, and a planted change shows up in the diff. So nothing outside Emails() changes, Close included.

fleet proof gate passes at 80ee4a5: live run, cross-version and shadow diff, CI green, review round 8, judge pass.

📝 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 pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Question	Answer	Who	Where
Scope of the port	Template form, code form, status read; local templates and extra fields wait	👤 Human	comment
React email rendering	The app renders and passes HTML; no rendering dependency	👤 Human	comment
Release order	Not before the server's code form deploys	👤 Human	comment
Shape of Send	One Send(ctx, Email), sealed Email, two types	🤖 Agent	comment
Which key authenticates	Config.SecretKey, as in Node and Python	🤖 Agent	comment
Does Get retry	Yes, as both SDKs and the spec do	🤖 Agent	comment
Adding Emails to Client	Minor release, by the Flush precedent	🤖 Agent	comment
Email without a cloud endpoint	missing_app_host until AppHost is set	🤖 Agent	comment
Today's server takes only the nested body	Keep the contract's flat body and release after PostHog/posthog#127123 deploys; no nested fallback	🤖 Agent	comment

Involvement: no grilling rounds; reviews: one GPT-6.1 Sol design read, six fleet proof review rounds (GPT-6.1 Sol), then a QA swarm panel of nine lenses and a narrow round on its fixes, which found nothing in the code; three PostHog Review passes, every finding fixed or answered on its thread; live run and cross-version run against a local PostHog stack.

• Written by Claude Code, Claude Opus 5.5 (claude-opus-5-5), as the posthog-go slice of map Map: send code-managed email templates with one PostHog call Silthus/posthog#461, directed by Michael.
• Reviews: a GPT-6.1 Sol design read; its two minor findings (one retrying request path, a racy Close test) are fixed in 78c6e6c. A fleet proof review round (GPT-6.1 Sol) found three edge cases: a nil *TemplateEmail panicked, a context ending during a retry wait lost its cause, and a 2xx with trailing bytes after valid JSON passed. All three are fixed in 0ffc1f6, each with a test that fails without the fix. The Go 1.21 race job then caught goccy/go-json's MarshalNoEscape reading a stack-built body as garbage. The email bodies now encode with encoding/json, HTML unescaped, in 8e181df, and a full go test -race ./... under Go 1.21.13 passes. A third review round on the fixes found nothing.
• QA swarm (round 7): six findings fixed in 80ee4a5. Rejected: the flag poller sending SecretKey to Endpoint (unchanged on main: local evaluation already does it whenever SecretKey is set; the AppHost doc now says so), a shadow diff for Close (nothing is replaced; the drain is a no-op without email requests), and an encoder error branch Go requires. Follow-up for sdk-specs: spec coverage for the code form, CaptureEngagement and MigratedFrom.

🤖 Generated with Claude Code

[github-actions]

posthog-go Compliance Report

Date: 2026-11-04 07:18:53 UTC
Duration: 169314ms

✅ All Tests Passed!

111/111 tests passed

---

Capture_V1 Tests

✅ 94/94 tests passed

View Details

Test	Status	Duration
Endpoint And Method.Targets V1 Endpoint	✅	19ms
Endpoint And Method.Does Not Use Legacy Endpoints	✅	7ms
Required Headers.Has Authorization Bearer Header	✅	6ms
Required Headers.Has Content Type Json	✅	6ms
Required Headers.Has Posthog Sdk Info Format	✅	17ms
Required Headers.Has Posthog Attempt Header	✅	6ms
Required Headers.Has Posthog Request Id	✅	6ms
Required Headers.Has Posthog Request Timestamp	✅	7ms
Required Headers.Has User Agent	✅	6ms
Body Format.Body Has Created At And Batch	✅	6ms
Body Format.No Api Key In Body	✅	7ms
Body Format.No Sent At In Body	✅	6ms
Event Format.Event Has Required Root Fields	✅	5ms
Event Format.Event Uuid Is Valid	✅	7ms
Event Format.Event Timestamp Is Rfc3339	✅	6ms
Event Format.Distinct Id Is String	✅	6ms
Event Format.Distinct Id At Root Not Properties	✅	6ms
Event Format.Custom Properties Preserved	✅	6ms
Event Format.Set Properties Preserved	✅	6ms
Event Format.Set Once Properties Preserved	✅	6ms
Event Format.Groups Properties Preserved	✅	6ms
Event Format.Sdk Generates Uuid If Not Provided	✅	6ms
Event Format.Event Has Required Root Fields Batch	✅	9ms
Event Format.Event Uuid Is Valid Batch	✅	8ms
Event Format.Event Timestamp Is Rfc3339 Batch	✅	9ms
Event Format.Distinct Id Is String Batch	✅	9ms
Event Format.Distinct Id At Root Not Properties Batch	✅	8ms
Event Format.Custom Properties Preserved Batch	✅	10ms
Event Format.Set Properties Preserved Batch	✅	9ms
Event Format.Set Once Properties Preserved Batch	✅	8ms
Event Format.Groups Properties Preserved Batch	✅	9ms
Event Format.Sdk Generates Uuid If Not Provided Batch	✅	9ms
Batch Behavior.Multiple Events In Single Batch	✅	31ms
Batch Behavior.Batch Envelope Smoke	✅	10ms
Batch Behavior.Flush With No Events Sends Nothing	✅	4ms
Batch Behavior.Flush At Triggers Batch	✅	1007ms
Batch Behavior.Created At Reflects Batch Creation Time	✅	8ms
Deduplication.Generates Unique Uuids	✅	15ms
Deduplication.Different Events Same Content Different Uuids	✅	8ms
Deduplication.Preserves Uuid On Retry	✅	5133ms
Deduplication.Preserves Timestamp On Retry	✅	5136ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5138ms
Deduplication.No Duplicate Events In Batch	✅	32ms
Header Behavior On Retry.Attempt Header Starts At One	✅	6ms
Header Behavior On Retry.Attempt Header Increments On Retry	✅	10140ms
Header Behavior On Retry.Request Id Preserved On Retry	✅	5135ms
Header Behavior On Retry.Different Requests Have Different Request Ids	✅	2015ms
Header Behavior On Retry.Request Timestamp Changes On Retry	✅	5136ms
Response Format Validation.Success Response Has Uuid Keyed Results	✅	9ms
Response Format Validation.Success Response Has Ok For Each Event	✅	28ms
Response Format Validation.Success No Retry After When All Ok	✅	28ms
Response Format Validation.Success Retry After Present When Retry Events	✅	131ms
Response Format Validation.Success No Retry After When Drop Only	✅	29ms
Response Format Validation.Response Echoes Request Id	✅	6ms
Retry Behavior.Retries On 408	✅	5135ms
Retry Behavior.Retries On 500	✅	5137ms
Retry Behavior.Retries On 503	✅	5138ms
Retry Behavior.Retries On 504	✅	5137ms
Retry Behavior.Retryable Errors Have Retry After	✅	2132ms
Retry Behavior.Respects Retry After On Retryable Error	✅	8137ms
Retry Behavior.Does Not Retry On 400	✅	2132ms
Retry Behavior.Does Not Retry On 401	✅	2134ms
Retry Behavior.Does Not Retry On 402	✅	2133ms
Retry Behavior.Does Not Retry On 413	✅	2134ms
Retry Behavior.Does Not Retry On 415	✅	2133ms
Retry Behavior.Non Retryable Errors Have No Retry After	✅	2133ms
Retry Behavior.Implements Backoff	✅	15143ms
Retry Behavior.Max Retries Respected	✅	15143ms
Partial Batch Handling.Handles 200 Full Success	✅	2009ms
Partial Batch Handling.Handles 200 With All Ok	✅	3034ms
Partial Batch Handling.Does Not Retry Dropped Events	✅	3030ms
Partial Batch Handling.Does Not Retry Limited Events	✅	3032ms
Partial Batch Handling.Prunes Ok Events On Partial Retry	✅	5137ms
Partial Batch Handling.Prunes Dropped Events On Partial Retry	✅	5134ms
Partial Batch Handling.Retries Only Retry Events From Partial	✅	5135ms
Partial Batch Handling.Partial Retry Preserves Uuids	✅	5133ms
Partial Batch Handling.Partial Retry Attempt Header Increments	✅	5133ms
Partial Batch Handling.Partial Retry Request Id Preserved	✅	5133ms
Partial Batch Handling.Respects Retry After On Partial	✅	5137ms
Partial Batch Handling.Unknown Result Treated As Terminal	✅	3032ms
Partial Batch Handling.Mixed Ok Drop Limited No Retry	✅	3034ms
Compression.Sends Gzip Content Encoding	✅	8ms
Compression.No Content Encoding When Disabled	✅	7ms
Compression.Compressed Body Is Decompressible	✅	17ms
Error Handling.Does Not Retry On Unknown 4Xx	✅	2133ms
Event Options.Cookieless Mode Override	✅	10ms
Event Options.Disable Skew Correction Override	✅	12ms
Event Options.Process Person Profile Override	✅	8ms
Event Options.Product Tour Id Override	✅	17ms
Event Options.Unset Options Omitted	✅	18ms
Event Options.Options Override In Batch	✅	15ms
Geoip And Historical Migration.Geoip Disable Injected Into Properties	✅	13ms
Geoip And Historical Migration.Historical Migration Set In Body	✅	9ms
Geoip And Historical Migration.Historical Migration Absent By Default	✅	6ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

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

[posthog]

PostHog Review · Standard · reviewed 53dd2f6: 2 Must fix, 3 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

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.

[Silthus]

Note

🤖 Claude Opus 5.5 responding on behalf of Michael

Decisions for this PR:

• 👤 Scope of the port Match posthog-node and posthog-python: template form, code form, status read. Local templates, cc, bcc, headers, tags and attachments wait for their server slice.
• 👤 React email rendering The app renders and passes HTML; the SDK takes no rendering dependency.
• 👤 Release order Never merge before the server's code form deploys; a code send gets a 400 until then.
• 🤖 Shape of Send One Send(ctx, Email) with a sealed Email and two types, TemplateEmail and CodeEmail, as Enqueue(Message) works; not two methods.
• 🤖 Which key authenticates Config.SecretKey, the project secret API key the flag poller uses, as one secret key serves both in Node and Python; no separate emails key.
• 🤖 Does Get retry Yes, with the client's retry limit, following both SDKs and the sdk-specs emails spec.
• 🤖 Adding Emails to Client A minor release, as Flush was added; the changeset says a custom Client needs the method.
• 🤖 Where email goes without a cloud endpoint Refuse with missing_app_host until Config.AppHost is set, so a custom ingestion proxy never receives the secret key.
• 🤖 Today's server takes only the nested template.id body Keep the flat body of the contract, as posthog-python's main (feat: send a flat body from emails.send posthog-python#1155) and posthog-node (feat(node): send email content from code with emails.send posthog-js#5509) send it, and release only after feat(messaging): send an email with inline html from code posthog#127123 deploys. A nested fallback would serve a shape that is going away. The cross-version run against master shows every send gets a 400 until then; Get already works.

[posthog]

PostHog Review · Standard · reviewed 5417c2d: 1 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

[stamphog]

Not approved — this change needs a human reviewer.

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

Two substantive concerns from @PostHog remain unresolved, so its current-head commented review does not provide concern-free assurance for the risky changes. Address the interface compatibility concern in posthog.go and failed-response reads in emails.go, then request a fresh review from @PostHog or a human teammate before re-requesting.

• PostHog Review (Standard) reviewed the current head: 1 finding, posted on the PR.
• posthog[bot] reviewed the current head.
• @PostHog on posthog.go:156: Client still requires the additional Emails method, while .changeset/emails-send.md selects a minor release; external implementations lose interface compatibility. RELEASING.md:35-39 distinguishes backward-compatible features from breaking changes, and no independent acceptance of this concern is present.
• @PostHog on emails.go:504-511: response-body read failures are preserved only for successful HTTP statuses. A truncated 409 response loses its retryable error code and becomes a non-retryable API error, so the transport-recovery concern remains unfixed.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	868L, 5F substantive, 1937L/9F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1d-complex (1937L, 9F, two-areas, feat)
stamphog 2.7.0		.stamphog/policy.yml @ 5417c2d · reviewed head 5417c2d

[Silthus]

@PostHog review

[posthog]

@Silthus PostHog Review is reviewing this pull request.

[posthog]

PostHog Review · Standard · reviewed 8cef8a9: 1 Should fix. This pull request is large, so the review ran in 4 parts with less depth than usual.

This is review round 3 on this pull request. When findings keep coming back in the same code, the approach is usually the problem. Before the next fix, check whether a different design would remove the whole class of findings.

[Silthus]

@PostHog review

[posthog]

@Silthus PostHog Review is reviewing this pull request.

[posthog]

PostHog Review · Standard · reviewed c7d0a9c: 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. This PR no longer qualifies for automatic review.

[Silthus]

@PostHog review

[posthog]

@Silthus PostHog Review is reviewing this pull request.

[posthog]

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

[stamphog]

Approved.

The public API, email write path and secret-bearing requests have independent assurance from the current-head agent review. No concrete unresolved review concerns or other policy refusal grounds are present.

• PostHog Review (Standard) reviewed the current head: no findings.
• posthog[bot] reviewed the current head.

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	912L, 5F substantive, 2064L/9F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1d-complex (2064L, 9F, two-areas, feat)
stamphog 2.7.0		.stamphog/policy.yml @ 80ee4a5 · reviewed head 80ee4a5