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 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>
Deploy preview
Changed pages
|
|
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!
|
| 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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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.
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).
Name the 24-hour key window for queued mail, and list the attachment refusals. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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>
|
Note 🤖 Claude Opus 5.5 responding on behalf of Michael Decisions from the rebuild on master and review rounds 1 and 2, in 4f08ec2:
|
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-nodeandnodemailer, create the transport withcreatePostHogTransportfromposthog-node/nodemailer, and keep eachsendMailcall. It covers the PostHog options for one message, a stableidempotency_keyfor mail from a job queue, the error fields (retryableonly 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.jsis 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
clientproperty that PostHog/posthog#130017 adds to thetransactional email api sendevent: weekly organizations whose sends come fromnodemailer. 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/nodemailerimport, itsposthogoptions, and its error and refusal fields, which readers build onimportfails.Rollout
squeak-reactlibrary #5574 and Fix session recording links in JS docs #5575, release posthog-node, then merge this PR.client = nodemailersends in the Impact section show whether teams use the page.Decisions
refusalcode, with what to doposthog-node@5 nodemailer@10error.retryabletrue?idempotency_key, as in the transportfromInvolvement: 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
node scripts/fix-mdx.jsonnodemailer.mdxprettier --check(2.3.0) on the three changed filesmarkdownlint-cli2(0.19.0) with.markdownlint-cli2.jsoncon both MDX filescheck-source-release-callouts.js,check-posthog-js-defaults.js/docs/workflows/transactional-emails/nodeand/nodemailer, 640 and 1440 wide, light and darknode.md, which the preview returns for every page's Markdown exportNot tested:
pnpm starton 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
New page
What to look at
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.src/navs/index.js: a hot file. The entry sits after Node.js; a bad merge here breaks the whole Workflows sidebar.Checklist
vercel.json(no page moved)🤖 Generated with Claude Code