Repository navigation
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 <noreply@anthropic.com> 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 <noreply@anthropic.com> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> 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 <noreply@anthropic.com> 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 <noreply@anthropic.com> 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 <noreply@anthropic.com> Generated-By: PostHog Desktop Task-Id: e72a2c10-f145-4f7c-8754-a4fcc06a18be
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> 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 <noreply@anthropic.com> 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…only Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> # 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
… 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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 <noreply@anthropic.com>
…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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
… email scope Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Add a Rails page under Send transactional emails: the :posthog delivery method of posthog-rails, how mail is named, the X-PostHog-* headers that set send options, deliver_later with a stable X-PostHog-Idempotency-Key, the refusals, and the errors. Ticket: PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Deploy preview
Changed pages
|
|
Vale prose linter → found 0 errors, 2 warnings, 0 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 |
|---|---|---|---|
| 42:29 | warning | Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. | PostHogBase.ProductNames |
| 143:104 | warning | Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. | PostHogBase.ProductNames |
There was a problem hiding this comment.
PostHog Review · Standard · reviewed fcf7bf1: 3 Should fix.
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.
Register the retry handler in an on_load block, retry only retryable errors after retry_after, and state the 24-hour idempotency window. Refs PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refs PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Bundle reportTotal JS (gzip)12.07 MiB (+0.0 KiB / +0.0%) Eager graph (modules shipped in each entrypoint's initial chunks)
Largest modules in the
|
| Module | Size |
|---|---|
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css |
1022.3 KiB |
./src/components/Stickers/Stickers.tsx |
696.4 KiB |
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js |
354.8 KiB |
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules |
351.4 KiB |
./node_modules/.pnpm/framer-motion@14.0.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 126 modules |
287.2 KiB |
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/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 |
258.5 KiB |
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/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/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/construction-2.mjs |
228.2 KiB |
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/magnifying-glass.mjs |
221.7 KiB |
./src/hooks/useProducts.tsx + 24 modules |
155.6 KiB |
./src/hooks/useProduct.ts + 9 modules |
149.4 KiB |
./src/components/Icons/Icons.tsx |
147.4 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).
| ```ruby file=config/initializers/posthog.rb | ||
| ActiveSupport.on_load(:action_mailer) do | ||
| ActionMailer::MailDeliveryJob.rescue_from PostHog::Rails::DeliveryError do |error| | ||
| raise error unless error.retryable? && executions < 5 |
There was a problem hiding this comment.
P2 · Stop backend retries for terminal delivery failures
With Sidekiq's default retry policy, raise error hands permanent failures such as recipient_suppressed back to Sidekiq, which retries them 25 times. The same handoff bypasses executions < 5 after transient failures exhaust this handler, so it doesn't enforce the intended retry policy. Report and discard terminal failures, or explicitly configure backend retries.
There was a problem hiding this comment.
Fixed in 1e33afe: the handler now reports the final error with Rails.error.report(error, handled: true) and ends the job, both for a permanent error and after the fifth attempt, so the backend has nothing to retry. In a Rails app, a 400 was reported once and not raised, and a 503 ran five attempts and was then reported without a raise.
A raised error goes to the queue backend, which retries it with its own policy. Report it with Rails.error and end the job. Refs PostHog/michaelr-context#43 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
PostHog Review · Standard · reviewed 1e33afe: 2 Should fix.
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.
| if error.retryable? && executions < 5 | ||
| retry_job wait: error.retry_after || 30 * executions | ||
| else | ||
| Rails.error.report(error, handled: true) |
There was a problem hiding this comment.
P2 · Use error reporting compatible with supported Rails versions
On Rails 6.1, which posthog-rails supports, a permanent delivery error or the fifth transient failure reaches Rails.error.report, but Rails.error requires Rails 7+. The handler raises NoMethodError instead of consuming the failure, returning it to Sidekiq for further retries. Use compatible reporting or explicitly require Rails 7+ for this example.
There was a problem hiding this comment.
Fixed in 9153139: the handler no longer calls Rails.error. It logs the mail it ends with Rails.logger.error and reports it with PostHog.capture_exception, which the posthog-rails facade offers on every Rails version it supports. The snippet, run in a Rails 6.1.7.10 app and a 7.2.3.1 app with deliver_later: a 400 sent once, then was logged and reported, not raised; a 503 sent five times, then was logged and reported.
| if error.retryable? && executions < 5 | ||
| retry_job wait: error.retry_after || 30 * executions | ||
| else | ||
| Rails.error.report(error, handled: true) |
There was a problem hiding this comment.
P2 · Configure reporting before discarding terminal delivery failures
With the documented setup on Rails 7+, Rails.error.report has no subscriber: Rails supplies none by default, and PostHog registers one only when auto_capture_exceptions is enabled. Permanent failures and exhausted retries consequently finish as successful jobs without reporting the lost email. Configure a subscriber or explicitly log the error before discarding it.
There was a problem hiding this comment.
Fixed in 9153139: before it ends the job, the handler always logs the lost mail with Rails.logger.error, and reports it with PostHog.capture_exception, which needs no Rails.error subscriber. Verified in the same Rails 6.1 and 7.2 apps: the log line and the captured exception appear for a permanent 400 and after the fifth 503.
…email-rails # Conflicts: # contents/docs/workflows/transactional-emails/api.mdx # contents/docs/workflows/transactional-emails/index.mdx # contents/docs/workflows/transactional-emails/node.mdx # src/navs/index.js
Drop the release number, which another release has passed. Link the Ruby page for the client setup in Rails and for tracking, instead of repeating them. Add the tracking and sensitive headers, and cap template keys at 256. The retry handler now logs a mail it ends and reports it with PostHog.capture_exception, which works on every Rails version posthog-rails supports and needs no Rails.error subscriber. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s sensitive setting Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tracking Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…email-rails # Conflicts: # src/navs/index.js
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Changes
A Rails developer who sends mail with Action Mailer finds no page that shows how to send that mail through PostHog. This PR adds Send transactional emails with Rails under Send transactional emails, and a Rails entry in the sidebar after React Email.
The page shows how to:
posthog-rubyandposthog-rails, setsecret_keyinPostHog.init, and verify theFromdomain;config.action_mailer.delivery_method = :posthog, with mailers that don't change;X-PostHog-Template-Key, then<mailer>-<action>, thenposthog_settings[:default_template_key];X-PostHog-*headers, including open and click tracking andX-PostHog-Sensitive, and what PostHog does when a mail leaves them out;deliver_laterand a stableX-PostHog-Idempotency-Key, so a job retry never sends twice;PostHog::Rails::UnsupportedMailError) and the errors (PostHog::Rails::DeliveryErrorandretryable?), retry only a retryable error, and report the rest.The page documents the delivery method in PostHog/posthog-ruby#329. It merges with the
posthog-railsrelease that ships it, not before. Ticket: https://github.com/PostHog/michaelr-context/issues/43 (private).Seams for review. The sidebar in
src/navs/index.jsis shared with the Nodemailer (#21987) and Better Auth docs: one entry each, no reorders. This branch mergedmasterafter React Email (#21984) landed in the same spot; Rails now follows it.Merge danger
Note
🔵 Merge risk: low · two-way door: one new page and one sidebar entry; taking them down leaves nothing behind, and the contract the page describes turns one-way with #329's release, not here
posthog-railsships the delivery method get Action Mailer's error for an unknown delivery method on their first send. That row is closed by merging with the release, not before.Rollout
posthog-railsreleases Document project structure #329.Evidence
ed1a910: the template key order, the seven headers and the sensitive default, the refusal codes includinginvalid_mail,DeliveryErrorandretryable?, andraise_delivery_errorswith its logging.95a00a9; later commits only add a test). The page'srescue_fromhandlers, inon_load(:action_mailer), run real Action Mailer jobs on Rails 7.2 and on Rails 6.1 against a fake API: a permanent400sends once and is reported, a503retries to five sends, a refused mail sends nothing and is reported, and no job is left behind.da3ad031b(Rails page), in headless Chromium at 1440 and 390 wide: the title, the eight sections and the code blocks render, the page has no horizontal scroll at 390, the sidebar lists Rails once, after React Email, and the links to the Ruby and API pages land on their anchors.gh pr-assetswhen Michael approves the upload to the public assets repo.prettier@2.8.8 --check src/navs/index.jspasses.pnpm formatcovers no.mdxfiles.c10f0fabb(Error Tracking, the product, is capitalized). Two remain on "logs" as the general concept and as a verb, which the rule allows. The fix changes one link text, so the walk atda3ad031bstill shows this head.Agent context
Decisions
posthog-railsrelease that ships the delivery methodrescue_from PostHog::Rails::DeliveryErrorinon_load(:action_mailer)that retries onlyretryable?errors afterretry_after, with a stableX-PostHog-Idempotency-KeyUnsupportedMailError, and never retries itInvolvement: no grilling or prototype rounds; two cross-model review rounds and four final reads (GPT-6.1 Sol), ReviewHog; UI walk and handler proof captured.
Taken over in place from the earlier thread on the same ticket; its commits and authorship are kept.
Checklist
vercel.json(no page moved)🤖 Generated with Claude Code