[mayteio]

Changes

This PR adds a docs page for the transactional email API in Workflows. The page tells a reader how to make an email template transactional, how to send it with POST /api/projects/@current/messaging/send/email/, how to read each email's status with GET /api/projects/@current/messaging/emails/:message_id/, and how to do both with the Python and Node.js SDKs.

Why: Teams in the transactional email beta have no public docs. This page documents the send API, the status API, and the SDKs, so they can integrate without support.

• Adds an overview and one page for each platform, the same way the push notification docs do:
  • /docs/workflows/transactional-emails: how to make a template transactional, the API key and its scopes, what a send needs, idempotency keys, the error code table, rate limits, statuses and reasons, and how transactional emails behave.
  • /docs/workflows/transactional-emails/node: install, the client with enableLocalEvaluation: false, send, check a status, timeouts and retries, and a no-network test.
  • /docs/workflows/transactional-emails/python: install, sync and async clients, send, check a status, timeouts and retries, and a no-network test.
  • /docs/workflows/transactional-emails/api: the raw send and status endpoints with cURL, for other languages.
• The send examples use the single send route, with the template ID in the body as template.id. A note says that the older template route still works.
• The Python and Node.js tabs use the SDKs, from Python 7.81.0 and Node.js 5.61.0. A "Send with an SDK" section covers the secret key, the app host for a proxy or a self-hosted instance, local evaluation, retries, and errors.
• A "Check an email's status" section covers the statuses, the reasons, the 404 cases, the scopes, and the read rate limits.
• Adds a "Transactional emails" group to the Workflows docs sidebar, below "Send a broadcast", with Overview, Node.js, Python, and API entries.
• Marks the page as beta with a callout. The page does not tell readers to request access.
• Depends on feat(messaging): refuse transactional sends the email worker would skip posthog#123019. That PR adds the 422 refusal codes sending_suspended, sending_paused, and recipient_suppressed, and the 400 transactional_email_paused response for an inactive workflow. The page assumes that PR merges.
• Merge after feat(node): send transactional email from a template posthog-js#5418 and feat: send transactional email from posthog templates posthog-python#1093 publish. The SDK section names their versions, so check the version numbers against the releases first.

Checks:

• vale on the four pages: 0 errors, 0 warnings.
• pnpm format:docs (scripts/fix-mdx.js) on the four pages: no changes. Prettier on src/navs/index.js: clean.
• node scripts/check-src-links.js: 0 broken links.
• src/navs/activeMenu.test.ts: passes.
• I did not start the dev server, so this PR has no before and after screenshots of the sidebar yet.

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

---

Created with PostHog Desktop

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Oct 30, 2026 12:50PM

Changed pages

Page	Source
Send transactional emails	contents/docs/workflows/transactional-emails/index.mdx
Send transactional emails with the API	contents/docs/workflows/transactional-emails/api.mdx
Send transactional emails with Node.js	contents/docs/workflows/transactional-emails/node.mdx
Send transactional emails with Python	contents/docs/workflows/transactional-emails/python.mdx

[github-actions]

Bundle report

Total JS (gzip)

10.53 MiB (+135.7 KiB / +1.3%)

Largest changed named chunks

Chunk	Gzip	Δ vs master
23b110d95c587435d17e5a559280a7b225e5608c.js	110.1 KiB	new
655c369601e38a7136cffdc999798d51fd71fc19.js	50.8 KiB	new
app.js	2354.0 KiB	-31.4 KiB / -1.3%
component---src-pages-desktop-tsx.js	25.2 KiB	new
7fc77900805ef1080f2cf8cea0e3717eea07d124.js	14.1 KiB	new
61055f01ba571e8f3eba4da329eafbb4c9c61420.js	7.7 KiB	-12.0 KiB / -60.8%
47d90eddd1e286b0d0e7b096ab3157885ca00a1d.js	10.5 KiB	new
component---src-pages-tier-list-tsx.js	8.8 KiB	new
component---src-pages-r-replay-vision-tsx.js	8.0 KiB	new
78f6350c99e28d0c1d72c92320a2a22aa65b541a.js	5.6 KiB	new
f3b7b034a27b39049f4d2a75339bbf78f5ae187c.js	4.7 KiB	new
component---src-pages-changelog-video-index-tsx.js	3.3 KiB	+2.9 KiB / +777.6%
component---src-pages-spicy-mov-index-tsx.js	3.3 KiB	+2.9 KiB / +783.8%
component---src-pages-demo-index-tsx.js	3.3 KiB	+2.9 KiB / +707.5%
component---src-pages-videos-play-tsx.js	3.7 KiB	+2.8 KiB / +313.8%

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

Entrypoint	Eager size	Budget	Modules
✅ app	20.39 MiB (-485.3 KiB / -2.3%)	report-only	2114

Largest modules in the app closure

Module	Size
./src/data/mcp-tools.json	1451.5 KiB
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	840.9 KiB
./src/components/Stickers/Stickers.tsx	696.4 KiB
./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs	481.2 KiB
./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/trenchcoat.mjs	450.8 KiB
./node_modules/.pnpm/[email protected]/node_modules/rehype-raw/lib/index.js + 29 modules	395.1 KiB
./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs	385.8 KiB
./src/hooks/useCustomers.tsx + 61 modules	381.8 KiB
./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/tourist.mjs	364.6 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
./src/components/ProductComparisonTable/index.tsx + 130 modules	314.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/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs	284.1 KiB
./node_modules/.pnpm/[email protected][email protected]/node_modules/cloudinary-core/cloudinary-core.js	281.9 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).

[marandaneto]

Public API/product review against the SDK guidelines. These six suggestions are non-blocking, focused on copy-pasteable SDK setup, actionable errors, bounded retries, and supported testing. The first three were validated with focused snippet probes; the remaining suggestions are documentation improvements assessed by inspection.