Docs: transactional email API page for code-managed templates, an anchor per error code #475

Activity

1. Silthus

   added

   wayfinder:implement

   on Oct 14, 2026
2. Silthus

   added a parent issue on Oct 14, 2026

   • Map: send code-managed email templates with one PostHog call #461
3. Silthus

   marked this as blocked by 2 issues on Oct 14, 2026

   • Email API: idempotency keys and throttles for safe retries #472
   • posthog-node: emails.send from a key or an HTML file, synced by content hash, returning { data, error } #474
4. Silthus

   marked this as blocking on Oct 14, 2026

   • Agent skill: verify a sender, upload the template from the repo, send by key #476
5. Silthus

   changed the title [-]Docs: email API reference page with an anchor per error code[/-] [+]Docs: transactional email API page for code-managed templates, an anchor per error code[/+] on Oct 16, 2026
6. Silthus

   unmarked this as blocked on Oct 16, 2026

   • Email API: idempotency keys and throttles for safe retries #472
7. Silthus

   marked this as blocked by 2 issues on Oct 16, 2026

   • Email templates: upload a template by key from code #487
   • Email templates: one send route that names the template in the body, with a content hash #488
8. Silthus

   self-assigned this

   on Oct 17, 2026
9. Silthus commented on Oct 17, 2026

   

   Silthus

   on Oct 17, 2026

   OwnerAuthor

   More actions

   Runtime: T3 child task
   Task: node:delegated-task:command%3Amcp%3A955e36b3-3986-469c-b816-09cf656780af%3Adelegate-task%3Awf-email-impl-475-2
   Cast: Opus 5.5, high. Cap 180 minutes.
10. Silthus commented on Oct 17, 2026

    

    Silthus

    on Oct 17, 2026

    OwnerAuthor

    More actions

    Resolution

    Shipped: draft PostHog/posthog.com#21306, branch Silthus:docs/transactional-email-api against master. Reviewed head c86c7a6a9894864505bb828b5df228a1523ff47b. fleet proof gate passes on it (live-run evidence at HEAD, HEAD reviewed in final read 3).

    What shipped

    • contents/docs/workflows/transactional-email-api.mdx: one beta page at /docs/workflows/transactional-email-api.
      • The beta note (enabled per project, ask in-app), the project secret API key with hog_flow:write, and the template format (Liquid, {{ variables.* }}, no person properties).
      • posthog-node: templateFile, send, the content hash flow, rolling deploys and template_superseded, uploadTemplate for a rollback, serverless bundles (Next.js, Vercel, Netlify), and edge runtimes.
      • The routes: upload by key (with if_not_superseded and the superseded result), the send route by key and by ID, the content hash algorithm with the spec's test vector, and the older ID route.
      • "Sends are not idempotent", rate limits, templates managed by code (tag, read-only preview, lock, release), adoption, and a cURL example for each route.
      • 27 anchored sections: every catalog code, the template_superseded warning, and every posthog-node code.
    • src/navs/index.js: Workflows › Transactional email › Send email from code, with a beta badge.
    • The site builds the markdown twin (.md) at build time, so the skill can read it. No copyable agent prompt and no llms.txt line, as the map says.

    Proof

    • Red: before the page existed, the docs_url from a real template_not_found response, opened on the local dev server, answered 404 (the Gatsby development 404 page). The anchor check found 0/27.
    • Green on c86c7a6a9: 200, and a plain navigation lands on the #template_not_found section. The anchor check finds 27/27 codes, each section quoting the server's detail and fix strings verbatim from 7845707ba33.
    • Mutation: changing the quoted key_in_use fix sentence made the check fail with 26/27.
    • Lint: Vale 3.13.1 with the repo config: no errors. Left: dictionary gaps and verbatim API quotes. markdownlint-cli2: 0 errors. The pre-commit hooks passed. All commits are signed (G).
    • Screenshots of the page, the anchor, and the sidebar before and after (light and dark, wide and narrow) are in the PR body.
    • Evidence: ~/.local/state/fleet/proof/PostHog/posthog.com/21306/c86c7a6a9894864505bb828b5df228a1523ff47b/live-run.

    What I ran: the docs dev server with GATSBY_MINIMAL=true pnpm start through fleet heavy (pnpm, as the repo prescribes), not a full production build.

    Review

    Opus 5.5, high effort, fresh read-only agents. Each round was recorded with fleet proof review-start and review-finish.

    • Round 1: 10 findings (2 medium, 8 low). All held and are fixed.
    • Final read 1: 3 new low findings in the fix lines. Fixed.
    • Final read 2: 1 new low finding. Fixed.
    • Final read 3: PASS.

    Calls made

    • The code wins over the spec catalog. Each difference:
      • immutable is live now, with a read-only preview and Stop managing in code (Email templates: refuse edits to code-managed templates on the server #491, Email templates: read-only view of code-managed templates #492).
      • Only seven codes carry why, fix, and docs_url. The existing send-pipeline codes and the shared API codes have only type, code, detail, and attr, so the page gives their fix.
      • invalid_request also covers hash with id, and key sent with other fields on adoption.
      • authentication_failed and permission_denied are two sections. A missing header answers not_authenticated.
      • template_superseded uses the server's wording. In posthog-node it is { code, message }, without fix.
      • The SDK adds api_error and unexpected_error.
      • The beta flag gates only the upload and send routes, not adoption or release.
      • The per-project rate limit counts only project secret API key requests.
    • Email templates: an automatic upload never republishes a superseded hash #499 landed during this ticket (7845707ba33). The page documents if_not_superseded and superseded as landed, so nothing in the PR is marked pending.
    • The anchor check stays out of the repo. A posthog.com content PR changes only contents/ and the nav. The script and its output are in the PR body and the proof storage.
    • SDK-only codes get anchors too, so every error.code from posthog-node has a fix.
    • The Node setup recommends enableLocalEvaluation: false, because secretKey also starts feature flag polling, which needs feature_flag:read.
    • Personal API key fallback: project secret API keys are in beta, so the page documents personal API keys for the HTTP routes, with the project ID in the URL. posthog-node always calls @current.
    • Screenshots: gh pr-assets and gh --attach need write access to PostHog repos, which this account lacks. They are published to the public fork with fleet proof publish instead.

    Local setup (nothing in the diff)

    • Node 22 (the repo's engine) in a private directory, because the box has Node 24.
    • PHANTOMJS_PLATFORM=linux PHANTOMJS_ARCH=x64, because phantomjs-prebuilt has no arm64 build.
    • DEBUG unset, because webpack inlines process.env.DEBUG into the SSR bundle.
    • A private GIT_CONFIG_GLOBAL for the dev server only, because the global url.insteadOf rewrite breaks the gatsby-source-git "already cloned" check on a restart.

    Follow-ups

    • Merge timing: hold feat: new scene for new pipeline configuration creation PostHog/posthog#21306 until the backend stack (Ship code-managed email templates as one reviewed draft PR #498) and feat(node): send transactional email with the flat SDK contract PostHog/posthog-js#5312 ship. The PR's risk callout says so.
    • Fork CI: upstream workflows (Vale, markdownlint, the Vercel preview) don't run on this fork PR until a maintainer approves them. Only the Wiz scanners ran (pass).
    • Markdown twin: not checked locally. A minimal production build would show the .md output.
    • posthog-node version: the page names no version. Add one when Think through the Elements tab PostHog/posthog#5312 releases.
    • Default sender docs: the configure-channels page never mentions a default sender or Make default. This page now explains it. That page could too.
11. Silthus

    closed this as completedon Oct 17, 2026