[dmarchuk]

Developers who send content from code cannot find custom headers or track_opens_and_clicks in the API docs, and the docs say attachments stop at 512 KB. The SMTP page also has no sidebar entry. This PR fixes both. The SMTP page itself stays in PostHog/posthog#130796, because nothing here should duplicate it.

Warning

Do not merge before PostHog/posthog#130793, PostHog/posthog#130794, PostHog/posthog#130795, and PostHog/posthog#130796 ship. The SMTP link and sidebar entry break until the page exists.

Changes

• API page: track_opens_and_clicks, headers and their rules, and the new 10 MB attachment limit. The section is renamed, and the one link to it is updated.
• Examples page: the same 10 MB limit.
• Transactional emails page and sidebar: a link to the SMTP page.

Open choices

The stack has not settled these, so smtp.mdx should not present them as final: tracking off by default, one email per To, partly refused sends, and display names containing an address.

Corrections to smtp.mdx in PostHog/posthog#130796

Not pushed, because other work is active on that branch. Read at ab2781bc18.

• Last line: the SMTP tab doesn't list the refused addresses. A partly refused send records only the reply and the sender, so To is empty under Recent problems. Either the page or the relay needs to change. Proposed text: If some addresses in To are refused and others are queued, the reply is 250, and **Recent problems** on the **SMTP** tab shows the refusal.
• Add a beta callout. The page has none, and it is on the workflows-smtp-relay flag. Proposed text: SMTP is in beta. How it handles several To addresses, tracking, partly refused sends, and display names might change.
• Channels tab: the tab label is Messaging. Check which name to use.
• Resend-Idempotency-Key names another provider on a general page. Decide whether to keep it.
• X-PostHog-Distinct-Id works, and the page doesn't list it. The limits of 50 To addresses and 10 Cc or Bcc addresses are also missing.

The rest of the page matched the code: ports, TLS, the 15 MB message limit, forwarded headers, and the template key.

How did you test this code?

Each claim was read against code_send_fields.py, message_templates.py, smtp-message.ts, smtp-relay.service.ts, smtp_activity.py, and SmtpSetup.tsx at ab2781bc18. No request was sent. A full 10 MB request through the public API was not checked against any body size limit in front of it.

• Not done: a local site build, the Vercel preview, and the before and after nav screenshots that a nav change needs.
• Run: markdownlint-cli2 with the repo config, and an MDX parse of the changed pages.

Checklist

• 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 (not done yet)

Agent context

Autonomy: Human-driven (agent-assisted). Agent: Claude Code, Opus 5.5. Skills: /writing-user-facing-copy, /writing-pr-descriptions, /writing-plainly.

🤖 Generated with Claude Code

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Nov 06, 2026 03:56PM

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
Transactional email examples	contents/docs/workflows/transactional-emails/examples.mdx

[github-actions]

Vale prose linter → found 37 errors, 1 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!

contents/docs/workflows/transactional-emails/api.mdx — 10 errors, 0 warnings, 0 suggestions

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
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
337: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
338: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
353: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
354: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
355: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/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/index.mdx — 27 errors, 0 warnings, 0 suggestions

Line	Severity	Message	Rule
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
117: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
118: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
136: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
137: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
161: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
162: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
190: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
191: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
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: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
257: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
258: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
259: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
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
287: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
288: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

[github-actions]

Bundle report

Total JS (gzip)

11.70 MiB (+0.0 KiB / +0.0%)

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

Entrypoint	Eager size	Budget	Modules
✅ app	9.94 MiB (+0.0 KiB / +0.0%)	report-only	1023

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	838.6 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	259.1 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 + 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).