Skip to content

docs(workflows): send Nodemailer mail through PostHog - #21987

Closed
Silthus wants to merge 33 commits into
masterfrom
docs/transactional-email-nodemailer
Closed

Silthus wants to merge 33 commits into
masterfrom
docs/transactional-email-nodemailer

Conversation

@Silthus

@Silthus Silthus commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Changes

A developer whose app sends email with Nodemailer finds no page that tells them how to send that email through PostHog.

This PR adds Send transactional emails with Nodemailer under Send transactional emails. The page shows how to install posthog-node and nodemailer, create the transport with createPostHogTransport from posthog-node/nodemailer, and keep each sendMail call. It covers the PostHog options for one message, a stable idempotency_key for mail from a job queue, the error fields (retryable only with an idempotency key), and each message that PostHog refuses (EPOSTHOGUNSUPPORTED). The Node.js page's code-send section links to the page, and the sidebar gets a Nodemailer entry after Node.js.

Ticket: https://github.com/PostHog/michaelr-context/issues/41 (private).

Base: master. The transport ships in posthog-node with PostHog/posthog-js#5575, on #5574. The page is ready for review; it merges only after a posthog-node release ships the transport.

Seams for review. src/navs/index.js is a hot file: this PR adds one entry after Node.js. Check for cross-stack breaks: the same concept documented twice (retries, idempotency keys, tracking, sensitive emails on the Node.js page and on this page), and any claim that differs from the transport in #5575.

Impact

Shows on the client property that PostHog/posthog#130017 adds to the transactional email api send event: weekly organizations whose sends come from nodemailer. This page is how those teams find the transport.

Merge danger

Caution

🔴 Merge risk: high · one-way door at merge: the page publishes the posthog-node/nodemailer import, its posthog options, and its error and refusal fields, which readers build on

  • New page and sidebar entry: a reader who opens the Nodemailer docs gets this page; every other docs page renders as before (preview build and the walk below).
  • Uncovered: a merge before a posthog-node release ships the transport would publish install steps for an entry point no release has, so a reader's import fails.
  • Switch-off: none: docs publish on merge. Fix forward.
  • Tier: critical (b: high at merge; c: one-way door)

Rollout

Decisions

Question Answer Who Where
Ready now, or a draft until the release? Ready now; the merge waits for the release 👤 Human ticket
Where does the sidebar entry go? After Node.js 👍 Accepted default ticket
Does the page document every refusal? Yes, one row per refusal code, with what to do 🤖 Agent ticket
Which versions does the install line pin? posthog-node@5 nodemailer@10 🤖 Agent comment
Does the page explain tracking, sensitive and retries again? No, one line each and a link to the Node.js page 🤖 Agent comment
Does the page name the release with the transport? Not until a release ships it 🤖 Agent comment
What does the page say about attachments? Upload then send, under the existing "temporarily unavailable" callout, no error code 🤖 Agent comment
When is error.retryable true? Only with an idempotency_key, as in the transport 🤖 Agent comment
What does the page promise about parts PostHog doesn't send? Never drops content, recipients or options; ignores the named headers and display names other than from 🤖 Agent comment
Hyphens or en dashes in definition lists? En dashes, per Vale 🤖 Agent comment

Involvement: 0 grilling rounds, 2 review panel rounds (fresh eyes on Claude; correctness and sweep on GPT-6.1 Sol) and 1 final read (GPT-6.1 Sol), UI walk captured on the preview.

🔍 Reviewer's guide

Testing done

Check Command / method Result
MDX fixer node scripts/fix-mdx.js on nodemailer.mdx No changes
Formatting prettier --check (2.3.0) on the three changed files Pass
Markdown lint markdownlint-cli2 (0.19.0) with .markdownlint-cli2.jsonc on both MDX files 0 errors
Repo checks check-source-release-callouts.js, check-posthog-js-defaults.js Pass
Preview build Deploy preview, run 43377891668 attempt 2 (attempt 1 stalled in "Build site" with no error and timed out) Built and deployed
Page load Headless Chromium on the preview and on production, /docs/workflows/transactional-emails/node and /nodemailer, 640 and 1440 wide, light and dark Both pages render; no new console errors except a 404 for node.md, which the preview returns for every page's Markdown export
Accuracy Each claim checked against posthog-node's transport at #5575 c9a28bd80 2 review rounds and a final read, no open finding

Not tested: pnpm start on this devbox (the preview build stands in for it). The narrow nav: the site collapses the sidebar at 640 wide before and after, so the entry shows in the wide captures only.

Screenshots

Sidebar, on the Node.js page

State Before After
Light, narrow window before light narrow after light narrow
Light, wide window before light wide after light wide
Dark, narrow window before dark narrow after dark narrow
Dark, wide window before dark wide after dark wide

New page

State After
Light, narrow window nodemailer light narrow
Light, wide window nodemailer light wide
Dark, narrow window nodemailer dark narrow
Dark, wide window nodemailer dark wide
Errors and refusals nodemailer errors and refusals

What to look at

  1. The refusal table and "Handle errors" in nodemailer.mdx: they restate the transport's contract from Fix session recording links in JS docs #5575. A wrong row tells a developer to send a message PostHog refuses, or to retry a send that can go out twice.
  2. src/navs/index.js: a hot file. The entry sits after Node.js; a bad merge here breaks the whole Workflows sidebar.

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 Nodemailer page under Send transactional emails: install, the
PostHog transport, key and host, the posthog options, retries from a
queue with a stable idempotency_key, and the messages PostHog refuses.
Link it from the Node.js page and add a sidebar entry after Node.js.

Ticket: PostHog/michaelr-context#41

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 07:21AM

Changed pages

Page Source
Send transactional emails with Node.js contents/docs/workflows/transactional-emails/node.mdx
Send transactional emails with Nodemailer contents/docs/workflows/transactional-emails/nodemailer.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 10 errors, 12 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/node.mdx — 10 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
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:18 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:17 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: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
184:293 warning 'Nodemailer' is a possible misspelling. PostHogBase.Spelling
199: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
200: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
201: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/nodemailer.mdx — 0 errors, 9 warnings, 0 suggestions
Line Severity Message Rule
2:39 warning 'Nodemailer' is a possible misspelling. PostHogBase.Spelling
7:31 warning 'Nodemailer' is a possible misspelling. PostHogBase.Spelling
19:96 warning 'Nodemailer' is a possible misspelling. PostHogBase.Spelling
61:21 warning 'Nodemailer' is a possible misspelling. PostHogBase.Spelling
91:215 warning Capitalize 'Logs' for PostHog's product. Use 'logs' for the general industry concept. PostHogBase.ProductNames
94:70 warning 'Nodemailer's' is a possible misspelling. PostHogBase.Spelling
114:12 warning 'retryable' is a possible misspelling. PostHogBase.Spelling
118:36 warning 'Nodemailer' is a possible misspelling. PostHogBase.Spelling
133:36 warning 'Nodemailer' is a possible misspelling. PostHogBase.Spelling

@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 7c0f31f: 1 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.


- **`template_key`** names the email, such as `order-shipped`. PostHog groups the email's metrics and sends under it. Without it, the transport uses `defaultTemplateKey` from `createPostHogTransport`, or `nodemailer`. Use letters, digits, hyphens, and underscores.
- **`distinct_id`** records the email against the person with this distinct ID. Without it, PostHog uses a person whose distinct ID is the `to` address. See [link emails to your users](/docs/workflows/transactional-emails/node#link-emails-to-your-users).
- **`idempotency_key`** identifies this one email. PostHog sends an email only once for each key.

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 · Limit the idempotency guarantee to its 24-hour window

When a queue retries a send more than 24 hours after PostHog queued it, the same idempotency_key no longer prevents another email. The transactional-email overview documents this expiration, but this unconditional guarantee tells readers that a stable key always prevents duplicates. State the 24-hour window and link the queue guidance to that limit.

@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.0 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).

Name the 24-hour key window for queued mail, and list the attachment refusals.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Base automatically changed from docs/transactional-email-api-code-form to master November 6, 2026 07:40
Silthus and others added 4 commits November 13, 2026 04:55
Master's SDK pages, API page, overview and nav win. The branch now adds only the Nodemailer page, its sidebar entry after Node.js, and one link from the Node.js page's code-send section.

The Nodemailer page follows the transport as it ships: tracking and sensitive replace capture_engagement, an unsupported_option refusal, the send error fields, the 60-second read timeout, the attachments warning master carries, and installs pinned to their current major.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…demailer; name the refused part headers and stream plugins

Refs PostHog/michaelr-context#41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Name the ignored headers, the sensitive default, same-content retries, the
compile-time read outside the 60 second limit, and link the client's retry
list instead of repeating it. En dashes and code spans per Vale.

Refs PostHog/michaelr-context#41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…display names

Refs PostHog/michaelr-context#41

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Silthus

Silthus commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Note

🤖 Claude Opus 5.5 responding on behalf of Michael

Decisions from the rebuild on master and review rounds 1 and 2, in 4f08ec2:

  • 🤖 Which versions does the install line pin? posthog-node@5 nodemailer@10, the @<major> pattern of the other SDK pages: 5 matches the Node.js page, and 10 is Nodemailer's current major.
  • 🤖 Does the page explain tracking, sensitive and retries again? No. One line each in the Node.js page's words, with a link to its section, so the two pages can't disagree.
  • 🤖 Does the page name the posthog-node release that adds the transport? Not yet. No release ships it; add the version when it does. The PR stays a draft until then.
  • 🤖 What does the page say about attachments? That posthog-node uploads each file before the send, under the same "Attachments are temporarily unavailable" callout the other pages carry, without an error code, since the SDK's upload path may return another code than a raw API send.
  • 🤖 When is error.retryable true? Only for a message with an idempotency_key, the same rule as posthog-node's transport.
  • 🤖 What does the page promise about parts PostHog doesn't send? It never drops content, recipients or options; it ignores only the headers the unsupported_header row names and the display names of every address except from, and refuses the rest.
  • 🤖 Hyphens or en dashes in the definition lists? En dashes, per the repo's Vale EnDash rule, though the Node.js page on master still uses hyphens.

@Silthus
Silthus marked this pull request as ready for review November 13, 2026 08:05
@Silthus
Silthus marked this pull request as draft November 14, 2026 17:47
@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