Skip to content

docs(workflows): send Action Mailer mail through PostHog on Rails - #21986

Closed
Silthus wants to merge 38 commits into
masterfrom
docs/transactional-email-rails
Closed

Silthus wants to merge 38 commits into
masterfrom
docs/transactional-email-rails

Conversation

@Silthus

@Silthus Silthus commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

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:

  • install posthog-ruby and posthog-rails, set secret_key in PostHog.init, and verify the From domain;
  • set config.action_mailer.delivery_method = :posthog, with mailers that don't change;
  • name emails: X-PostHog-Template-Key, then <mailer>-<action>, then posthog_settings[:default_template_key];
  • set send options with the X-PostHog-* headers, including open and click tracking and X-PostHog-Sensitive, and what PostHog does when a mail leaves them out;
  • send with deliver_later and a stable X-PostHog-Idempotency-Key, so a job retry never sends twice;
  • read the refusals (PostHog::Rails::UnsupportedMailError) and the errors (PostHog::Rails::DeliveryError and retryable?), 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-rails release that ships it, not before. Ticket: https://github.com/PostHog/michaelr-context/issues/43 (private).

Seams for review. The sidebar in src/navs/index.js is shared with the Nodemailer (#21987) and Better Auth docs: one entry each, no reorders. This branch merged master after 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

  • Readers of the Transactional emails sidebar see one more entry, Rails after React Email; no page moves, so no redirect. Covered by the UI walk on the preview.
  • Rails developers who follow the page before posthog-rails ships 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.
  • The page's code: the error handler boots and retries as the page says on Rails 7.2 and 6.1 (handler proof), and every header, refusal code and error field matches Document project structure  #329's head.
  • Switch-off: none: live on deploy, fix forward.
  • Tier: non-critical

Rollout

  • Stages: merge on the day posthog-rails releases Document project structure  #329.
  • Decided: the docs wait for the release, so no reader meets a delivery method that isn't out yet.

Evidence

  • Every claim on the page matches the code and tests in posthog-ruby#329 at ed1a910: the template key order, the seven headers and the sensitive default, the refusal codes including invalid_mail, DeliveryError and retryable?, and raise_delivery_errors with its logging.
  • The handler boots and retries as the page says (at Document project structure  #329's 95a00a9; later commits only add a test). The page's rescue_from handlers, in on_load(:action_mailer), run real Action Mailer jobs on Rails 7.2 and on Rails 6.1 against a fake API: a permanent 400 sends once and is reported, a 503 retries to five sends, a refused mail sends nothing and is reported, and no job is left behind.
  • The preview at 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.
  • Screenshots of that walk are captured. They go up with gh pr-assets when Michael approves the upload to the public assets repo.
  • prettier@2.8.8 --check src/navs/index.js passes. pnpm format covers no .mdx files.
  • Vale: one warning fixed in 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 at da3ad031b still shows this head.
Agent context

Decisions

Question Answer Who Where
Where does the Rails page go? Under Send transactional emails, after the SDK pages 👍 Accepted default ticket
When does it merge? With the posthog-rails release that ships the delivery method 👍 Accepted default ticket
How should queued mail retry? A rescue_from PostHog::Rails::DeliveryError in on_load(:action_mailer) that retries only retryable? errors after retry_after, with a stable X-PostHog-Idempotency-Key 🤖 Agent ticket
What does the handler do with a refused mail? Logs and reports UnsupportedMailError, and never retries it 🤖 Agent ticket
Does the page name a release number? Not until the release exists 🤖 Agent ticket
Where does Rails sit after React Email landed first? After React Email; neither entry moves 🤖 Agent ticket

Involvement: 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

  • I've read the docs and/or content style guides.
  • Words are spelled using American English
  • Use relative URLs for internal links
  • I've checked the pages added or changed in the Vercel preview build
  • If I moved a page, I added a redirect in vercel.json (no page moved)

🤖 Generated with Claude Code

mayteio and others added 28 commits October 24, 2026 10:38
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>
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Nov 13, 2026 08:16AM

Changed pages

Page Source
Send transactional emails with Rails contents/docs/workflows/transactional-emails/rails.mdx

@github-actions github-actions Bot added the docs Improvements or additions to product documentation, "Docs" label Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

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!

contents/docs/workflows/transactional-emails/rails.mdx — 0 errors, 2 warnings, 0 suggestions
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

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Silthus and others added 2 commits November 5, 2026 12:43
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>
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

12.07 MiB (+0.0 KiB / +0.0%)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 10.41 MiB (+0.1 KiB / +0.0%) report-only 1100
Largest modules in the app closure
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).

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PostHog Review · Standard · reviewed 7f790a2: 1 Should fix.

```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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>

@posthog posthog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Base automatically changed from docs/transactional-email-api-code-form to master November 6, 2026 07:40
Silthus and others added 7 commits November 13, 2026 05:06
…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>
@Silthus Silthus closed this Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to product documentation, "Docs"

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants