Repository navigation
docs(workflows): send transactional emails from Go, .NET, Rust, Ruby, Elixir and PHP - #21932
Merged
Merged
Conversation
Document how to make a Workflows email template transactional and send it with POST /api/projects/:project_id/messaging_templates/:template_id/send/. The page covers the API key, the request and response, idempotency keys, error codes, rate limits, and how transactional emails behave. The page is marked beta. Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: a0274fa0-d9be-48bf-b601-f153decf241d
…e SDKs - Send through `POST /messaging/send/email/` with `template.id`. The template route still works. - Read an email's status with `GET /messaging/emails/:message_id/`: statuses, reasons, 404 cases, scopes and read limits. - Send and read with the Python and Node.js SDKs. - Add `recipient_unreachable` to the errors table. Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
- The Node.js example turns off local evaluation, and both examples keep the SDK's error. - The status examples handle the error first and explain retrying a not_found. - The SDK section adds install, client reuse, timeouts and retries, uncertain outcomes, and a no-network testing example. Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
…m pages The overview keeps the template, key, idempotency, errors, statuses and behavior. Node.js, Python and API pages hold the setup, send, status, retries and testing for each platform, with a sidebar group like push notifications. Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
…he overview - A quick start links to the Node.js, Python and API pages. - Creating an email follows the Transactional section's wizard, and the hidden workflow explanation is gone. - Agents can set it up with the PostHog MCP server. - Protect sensitive data turns off click tracking and keeps deliveries, opens and statuses. Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
The send endpoint now takes a flat body (PostHog/posthog#126287), so the field table, the curl example and the engagement events note use template_id and distinct_id. Co-Authored-By: Claude Opus 5.5 <[email protected]> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
…il API page Document the code form of the send route (template_key with the subject and body), capture_engagement, the checks that only apply to it, and a delivery_unavailable anchor for the 503's docs link. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…mits Add DKIM-Signature and Received to the reserved headers, the header name and value limits, the tag length, and that reply_to takes bare addresses. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…only Co-Authored-By: Claude Opus 5.5 <[email protected]>
…t template_key and ph_ tags do - A retry with the same Idempotency-Key is the same request when every field of the code-form table matches. - template_key groups the email's metrics and sends. - A tag name that starts with ph_, in any case, is refused. - capture_engagement on a template send defaults to the project's setting. - Drop a double blank line after the checks table (fix-mdx). Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ell out the ph_ case rule - The template-send table gets a capture_engagement row with the project default, and says a retry sends the field the same way. - The code-form row keeps only its own default. - A ph_ tag name is refused in uppercase or lowercase. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]> # Conflicts: # contents/docs/workflows/transactional-emails/api.mdx # contents/docs/workflows/transactional-emails/node.mdx # contents/docs/workflows/transactional-emails/python.mdx
…code send The first release sends content from code with template_key, subject, html and text only. React Email output is rendered by the app and sent as html. Co-Authored-By: Claude Opus 5.5 <[email protected]>
- Drop capture_engagement from the template send: the send route refuses it there, with the other fields of content from your code. - Fold sender_not_allowed into sender_not_verified, the code the first release returns for a from address no verified sender can use. - Add "Send content from your code" to the Node.js and Python pages, with a React Email example rendered by the app. Co-Authored-By: Claude Opus 5.5 <[email protected]>
… in a replay - A field error is a 400 with type validation_error, a field code such as required or invalid, and attr naming the field. - A replay also compares the sender PostHog chose, so a retry without from after the default sender changed returns idempotency_key_reused. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ntify distinct ID Add "Link emails to your users" to the API, Node.js and Python pages: pass the distinct ID you pass to identify(), what happens without one today (a separate person keyed by the email address), and that invites and signup checks can leave it out. The overview and the API tables point there instead of "always send it". Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
… Elixir and PHP Add a page for each SDK with the template send, content from code, the status read, and the distinct ID guidance. Copies and attachments are marked as coming in a later version. The API page shows every SDK in its language tabs. Co-Authored-By: Claude Opus 5.5 <[email protected]>
github-actions
Bot
added
the
docs
Contributor
Deploy preview
Changed pages
|
Contributor
|
Vale prose linter → found 74 errors, 23 warnings, 3 suggestions in your markdown Full report → Copy the linter results into an LLM to batch-fix issues. Linter being weird? Update the rules!
|
| Line | Severity | Message | Rule |
|---|---|---|---|
| 17:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 18:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 181:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 182:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 334:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 335:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 336:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/dotnet.mdx — 5 errors, 3 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 79:94 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 127:20 | warning | 'Hangfire' is a possible misspelling. | PostHogBase.Spelling |
| 184:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 185:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 208:20 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 210:13 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 211:26 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/elixir.mdx — 5 errors, 5 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 59:66 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 106:20 | warning | 'Oban' is a possible misspelling. | PostHogBase.Spelling |
| 167:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 168:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 172:336 | warning | 'EEx' is a possible misspelling. | PostHogBase.Spelling |
| 191:21 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 193:13 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 194:27 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 222:32 | warning | 'config's' is a possible misspelling. | PostHogBase.Spelling |
contents/docs/workflows/transactional-emails/examples.mdx — 0 errors, 1 warnings, 3 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 19:17 | suggestion | Address the reader directly. Use 'you' instead of 'The user'. | PostHogDocs.DirectAddress |
| 66:76 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 105:37 | suggestion | Address the reader directly. Use 'you' instead of 'the user'. | PostHogDocs.DirectAddress |
| 156:4 | warning | 'Receipt with a PDF' heading should be in sentence case, and product names should be capitalized. | PostHogBase.SentenceCase |
contents/docs/workflows/transactional-emails/go.mdx — 5 errors, 2 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 61:199 | warning | Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. | PostHogBase.ProductNames |
| 164:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 165:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 189:20 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 191:13 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 192:26 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/index.mdx — 27 errors, 0 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 113:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 114:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 115:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 116:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 133:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 134:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 135:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 156:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 157:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 158:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 159:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 160:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 186:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 187:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 188:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 189:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 253:42 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 254:74 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 255:42 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 256:39 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 257:35 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 281:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 282:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 283:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 284:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 285:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 286:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/node.mdx — 5 errors, 2 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 54:72 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 146:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 147:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 177:20 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 179:13 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 180:26 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/php.mdx — 5 errors, 2 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 59:67 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 164:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 165:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 187:21 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 189:13 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 190:27 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/python.mdx — 5 errors, 2 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 73:89 | warning | Capitalize 'Feature Flags' for PostHog's product. Use 'feature flags' for the general industry concept. | PostHogBase.ProductNames |
| 168:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 169:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 207:21 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 209:14 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 210:27 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/ruby.mdx — 5 errors, 2 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 55:215 | warning | Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. | PostHogBase.ProductNames |
| 130:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 131:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 152:21 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 154:13 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 155:27 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
contents/docs/workflows/transactional-emails/rust.mdx — 5 errors, 4 warnings, 0 suggestions
| Line | Severity | Message | Rule |
|---|---|---|---|
| 12:127 | warning | Avoid trivializing words. 'easy to' can sound dismissive to the reader. | PostHogDocs.Trivializers |
| 153:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 154:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 158:420 | warning | 'Askama' is a possible misspelling. | PostHogBase.Spelling |
| 158:430 | warning | 'Tera' is a possible misspelling. | PostHogBase.Spelling |
| 183:1 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 185:13 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 186:27 | error | Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash. | PostHogBase.EnDash |
| 214:33 | warning | 'httpmock' is a possible misspelling. | PostHogBase.Spelling |
![posthog[bot]](https://avatars.githubusercontent.com/in/1203049?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 3afd19a: 4 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.
| ``` | ||
|
|
||
| - **Local evaluation:** When `SecretKey` is set, the client also polls flag definitions with it for [local evaluation](/docs/feature-flags/local-evaluation). Give the key the **Feature flag** read scope too, or the client logs a failed poll each time it polls. | ||
| - **Host:** On PostHog Cloud, the client sends email to the app host of your region, even when `Endpoint` is an ingestion host such as `us.i.posthog.com`. For any other host, such as a reverse proxy or a self-hosted instance, set `AppHost` to your PostHog app URL. The client refuses to send the secret key to a host that might be a proxy. |
Contributor
There was a problem hiding this comment.
P2 · Limit the proxy safety claim to email requests
When an existing client uses an ingestion proxy, adding SecretKey starts flag-definition requests against Endpoint, including the secret. AppHost only reroutes email requests, so the stated refusal does not protect the key from that proxy. The Ruby, PHP, and Elixir notes repeat this claim; document the flag-request exposure and a safe configuration.
Comment on lines
+37
to
+39
| def send_password_reset(user, reset_link, reset_request_id) | ||
| # Raises PostHog::EmailError when PostHog doesn't queue the email. Branch on error.code. | ||
| result = posthog.emails.send( |
Contributor
There was a problem hiding this comment.
P2 · Pass the Ruby client into the helper methods
When readers call this helper after the setup example, posthog raises NameError: Ruby methods declared with def do not capture the surrounding local variables. Both send helpers and email_bounced? therefore fail before making an SDK request. Pass the initialized client into each helper, or store it in an instance variable accessible to those methods.
Comment on lines
+43
to
+44
| func sendPasswordReset(ctx context.Context, userID, email, firstName, resetLink, resetRequestID string) (string, error) { | ||
| result, err := client.Emails().Send(ctx, posthog.TemplateEmail{ |
Contributor
There was a problem hiding this comment.
P2 · Pass the Go client into the helper functions
When readers combine this helper with the setup example, compilation fails with undefined: client. The setup creates client with :=, which requires function scope, while these package-level functions cannot capture that local variable. Both send examples and emailBounced have this problem; pass a posthog.Client parameter into each helper.
Comment on lines
+137
to
+139
| if errors.As(err, &emailErr) && emailErr.Code == "not_found" { | ||
| // The first status can take a few seconds to arrive. Try again later. | ||
| return false, nil |
Contributor
There was a problem hiding this comment.
P2 · Preserve the unavailable status so callers can retry
When a status lookup returns not_found before the first status arrives, emailBounced returns false, nil, exactly as for a successful lookup of a non-bounced email. Callers cannot detect this transient failure and trigger the retry recommended below the example. Return an explicit unknown result, propagate the error, or perform bounded retries inside the helper.
Use the placeholders the site fills in, pass the client to the Go and Ruby helpers, tell "not yet" from "not bounced" in Go, add the .NET usings and serde_json, and say that flag definitions still load from the ingestion host with the secret key. Ruby's timeout covers each connect, read, and write. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…nd review Co-Authored-By: Claude Opus 5.5 <[email protected]>
Contributor
Bundle reportTotal JS (gzip)11.70 MiB (+0.1 KiB / +0.0%) Eager graph (modules shipped in each entrypoint's initial chunks)
Largest modules in the
|
| Module | Size |
|---|---|
css ./node_modules/.pnpm/[email protected][email protected]/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css |
838.6 KiB |
./src/components/Stickers/Stickers.tsx |
696.4 KiB |
./node_modules/.pnpm/@[email protected][email protected][email protected][email protected]/node_modules/@posthog/icons/dist/posthog-icons.es.js |
354.8 KiB |
./node_modules/.pnpm/[email protected]_@[email protected][email protected]/node_modules/react-markdown/lib/react-markdown.js + 88 modules |
351.4 KiB |
./node_modules/.pnpm/[email protected][email protected][email protected][email protected]/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 126 modules |
287.2 KiB |
./node_modules/.pnpm/[email protected][email protected]/node_modules/cloudinary-core/cloudinary-core.js |
281.9 KiB |
./src/components/SearchUI/index.tsx + 87 modules |
273.1 KiB |
./gatsby-browser.tsx + 59 modules |
259.1 KiB |
./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-1.mjs |
248.5 KiB |
./src/components/Pricing/PricingSlider/Slider.tsx + 87 modules |
240.2 KiB |
./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-2.mjs |
228.2 KiB |
./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/magnifying-glass.mjs |
221.7 KiB |
./src/hooks/useProducts.tsx + 23 modules |
153.9 KiB |
./src/hooks/skills.tsx + 2 modules |
150.7 KiB |
./src/hooks/useProduct.ts + 9 modules |
150.0 KiB |
Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).
The Node.js and Python client examples used <ph_project_api_key> and a hard-coded ingestion host, which the site doesn't replace. They now use <ph_project_token> and <ph_client_api_host>, as the SDK pages do, so a logged-in reader sees their own project token and host. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…email-all-sdks Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
…ming-soon notes Co-Authored-By: Claude Opus 5.5 <[email protected]>
…atus reads A send needs transactional_email:write and a status read needs transactional_email:read or :write. Keys with a hog_flow scope still work. Co-Authored-By: Claude Opus 5.5 <[email protected]>
The key steps still picked Workflow, which creates a hog_flow key. The scopes list names the new scope Transactional email. Co-Authored-By: Claude Opus 5.5 <[email protected]>
… email scope Co-Authored-By: Claude Opus 5.5 <[email protected]>
Silthus
marked this pull request as ready for review
November 5, 2026 08:42
…email-all-sdks Co-Authored-By: Claude Opus 5.5 <[email protected]>
A status read right after a send can answer 404 for a few seconds, until the send's first status arrives. Say so where the API page lists the 404, and that a retry after a short wait is the fix. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
posthog-python#1171 ships as a minor bump, and PyPI is already at 7.83.2, so the code send arrives in 7.84.0, not 7.83.0. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…email-all-sdks Co-Authored-By: Claude Opus 5.5 <[email protected]>
dmarchuk
approved these changes
Nov 5, 2026
This was referenced Nov 5, 2026
…send Add a quick start that sends a first email with curl, a table to choose where the content lives, a coding agent prompt on each SDK page, a retry column in the errors table, and a checklist for an email that didn't arrive. Each SDK page now shows a send from a background job, a test that fakes HTTP, and its proxy notes at the end. A new examples page covers sign-in codes, email address checks, invites, receipts with a PDF, and a funnel that measures an email. PHP names 4.22.0 and Elixir 2.20.0, the versions their releases now publish. Co-Authored-By: Claude Opus 5.5 <[email protected]>
PostHog remembers an idempotency key for 24 hours, so a job retried after that can send the email twice. Each background-job example now says to finish its retries within 24 hours. The Sidekiq job retries 5 times, the River job has 5 attempts, and the BullMQ job shows its attempts and backoff. The quick start turns on Protect sensitive data for its reset email. Co-Authored-By: Claude Opus 5.5 <[email protected]>
… note The Node.js and Python pages now document cc, bcc, and attachments, as the other six SDK pages do, and the receipt example shows Node.js and Python. Five pages said that the client never sends the secret key to a proxy, but local evaluation does. They now say that the client never sends email requests there. The Celery retries now wait long enough to pass a rate limit, and the quick start sets the key before it sends. Co-Authored-By: Claude Opus 5.5 <[email protected]>
Base automatically changed from
docs/transactional-email-api-code-form
to
master
November 6, 2026 07:40
Silthus
changed the base branch from
docs/transactional-email-api-code-form
to
master
November 6, 2026 07:40
…se them No SDK release sends cc, bcc, or attachments yet, so the SDK pages must not document them. The API takes them today, so the API page and the receipt example (cURL only) keep them. Co-Authored-By: Claude Opus 5.5 <[email protected]>
…email-all-sdks # Conflicts: # contents/docs/workflows/transactional-emails/api.mdx # contents/docs/workflows/transactional-emails/index.mdx # contents/docs/workflows/transactional-emails/node.mdx
…erge Co-Authored-By: Claude Opus 5.5 <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
Before this PR, the transactional email docs covered only Node.js, Python, and the raw API. A reader saw many reference sections before they could send one email. This PR adds a page for each of the other six SDKs and rewrites the existing pages so that a reader sends a first email in a few minutes.
New pages
Every SDK page (all eight)
Overview page
Other changes
The API shapes come from the SDK PRs: posthog-go #406, posthog-dotnet #365, posthog-rs #324, posthog-ruby #324, posthog-elixir #236, and posthog-php #288. Copies and attachments come from posthog-js #5514, posthog-python #1172, posthog-go #408, posthog-dotnet #367, posthog-rs #326, posthog-ruby #325, posthog-php #292, and posthog-elixir #239.
Based on
masterafter #21819 merged. This PR also rewrites the four pages of #21819: the overview, API, Node.js, and Python pages. It keeps the API page's note that a404right after a send means "retry after a short wait", and Python 7.84.0 for content from code.Note
🔵 Merge risk: low · two-way door
Note
The pages name these versions, and each one is published: posthog-node 5.61.2 for templates and 5.62.0 for content from code, posthog (Python) 7.81.2 and 7.84.0, posthog-go 1.40.0, PostHog .NET 2.20.0, posthog-rs 0.31.0, posthog-ruby 3.30.0, posthog (Elixir) 2.20.0, and posthog-php 4.22.0. On 2026-11-06, I checked each version on its registry, and checked that its release tag contains the SDK's email PR.
Checklist
vercel.json(no page moved)Evidence
I ran the dev server (
pnpm start) on the branch and rendered each changed page with Playwright: the overview, Examples, Node.js, and Python pages at 2448c60, and the other pages at 727ba84, which changed only in text since then. I captured them at 1440 px and 640 px wide, in light and dark mode. The "before" captures come from the same server with the base branch'ssrc/navs/index.js.Sidebar
New and rewritten sections at the head
API page language tabs
Checks
After the captures, commit
8196ea65fonly removes text: the SDK copies-and-attachments sections, the receipt example's Node.js and Python tabs, and one API note. The Vercel preview build renders the head.pnpm formatran on the changed files. Prettier skips.mdx, so I checked the code blocks by hand.Each changed page loads with no new console errors. The 404 for a missing asset, the SVG
widthwarning, andvalidateDOMNestingalso show on pages that this PR doesn't change. The .NET and Python pages show a React duplicate-key warning for their two tabs in the same language, and the tabs switch correctly.The Ruby WebMock test ran in a container and passed.
No page moved, so
pnpm test-redirectsdoes not apply. I didn't run a full site build, so the Markdown copy of each page (the.mdURL that the agent prompts name) isn't checked locally. The Vercel preview builds it.A cross-model review panel ran four rounds and six final reads. Each API claim was checked against the SDK PR heads.
Calls made
.mdURL, so the agent reads the current docs, not what it remembers.$posthog.emails, so the setup snippet and the helpers work together when you paste them. A Rails app can use an initializer constant in its place.Retry-After. Each backoff runs past the per-minute rate limit. To readRetry-After, each example needs code for its queue's scheduling API.8196ea65fremoves them from the SDK pages, and the receipt example keeps only its cURL tab. #22022 restores them.Follow-ups
file=Swift Package Manageron the React Native source maps page renders as "Swift". That is why the .NET tab says "ASP.NET". It needs a site issue, not a fix in this PR.🤖 Generated with Claude Code