docs: telemetry page, Homebrew install tab, convex typed returns

[leoisadev1]

Triages the five Tembo draft docs PRs (written before the #128 full docs rewrite) and ports the parts main still lacks, rewritten in the current docs voice and re-verified against source.

What's here

Telemetry page (from #144). The READMEs disclose telemetry, but the docs site had no page for it. Adds /docs/telemetry covering the four events and their properties, error-report redaction, storage/transport, CI detection, and every opt-out (EMAIL_SDK_TELEMETRY, DO_NOT_TRACK, telemetry: false, NODE_ENV=test). Every claim checked against packages/email-sdk/src/telemetry.ts, core.ts, and cli.ts. Also adds the telemetry option to the client reference TypeTable and the sidebar entry.

Homebrew install (from #134). Formula/email-sdk.rb shipped with 0.6.5 but neither install.mdx nor the CLI reference mentioned it. Adds a third tab to the install page and a pointer from the CLI reference. Corrects the draft's claim that releases update the formula on main automatically: release.yml opens an automated formula-bump PR, so the copy on main tracks releases after that PR merges.

Convex typed returns (from #136). One sentence each in the component docs and the package README noting status/listEvents resolve to ConvexEmailDoc | null / ConvexEmailEventDoc[] and that those types (plus ConvexEmailDeliveryStatus) are exported. The draft's full field table duplicated what the rewritten page already says in prose, so it was not ported.

Not ported: #135 (adapter-contract already documents sendBulk in the type and options table, and message.mdx covers the fallback semantics) and #140 (iterable.mdx already disambiguates adapter-level sendAt from the rejected message field).

Validation

• cd apps/fumadocs && bun run types:check — green
• bun run build — green, telemetry page prerendered

---

Created with PostHog Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
email-sdk-fumadocs	Ready	Preview, Comment	Jul 6, 2026 7:11pm

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[greptile-apps]

Greptile Summary

This PR adds three documentation additions that were missing from the docs site after the #128 full rewrite: a new /docs/telemetry page, a Homebrew install tab in the getting-started guide, and typed-return annotations for the Convex email helpers. All technical claims were cross-verified against the source code before this review.

• Telemetry page — covers all four event types, redaction rules, storage path, CI vendor detection table, and every opt-out mechanism; every claim matches packages/email-sdk/src/telemetry.ts exactly (event names, env-var values, dedup caps, frame sanitization).
• Homebrew tab — adds a third tab to the install page with the correct brew install --formula URL and an explicit caveat that brew upgrade will not auto-track URL-installed formulas; client.mdx and cli.mdx receive matching cross-links.
• Convex typed returns — one-sentence additions in both convex-email.mdx and packages/convex-email/README.md noting status → ConvexEmailDoc | null and listEvents → ConvexEmailEventDoc[]; types are confirmed exported from client/index.ts.

Confidence Score: 5/5

Documentation-only changes; no executable code is modified.

Every technical claim in the new telemetry page, Homebrew tab, and Convex typed-return sentences was checked against the corresponding source files and all match. The telemetry TypeTable entry in client.mdx accurately reflects the options.telemetry === false guard in core.ts. The Convex type exports (ConvexEmailDoc, ConvexEmailEventDoc, ConvexEmailDeliveryStatus) are confirmed present in client/index.ts. No logic, types, or build configuration is touched.

No files require special attention.

Important Files Changed

Filename	Overview
apps/fumadocs/content/docs/telemetry.mdx	New telemetry page — four events, redaction rules, storage path, CI detection table, and all opt-out mechanisms verified against packages/email-sdk/src/telemetry.ts; all claims match the source.
apps/fumadocs/content/docs/getting-started/install.mdx	Adds a third "Homebrew (global)" tab with accurate formula URL, Bun-runtime explanation, and an explicit note that brew upgrade will not auto-update URL-installed formulas; tab value string matches the items array.
apps/fumadocs/content/docs/reference/client.mdx	Adds telemetry option to the TypeTable with correct type/default and cross-links to the new telemetry page; aligns with core.ts line 99 (options.telemetry === false).
apps/fumadocs/content/docs/reference/cli.mdx	One-sentence cross-reference to the Homebrew formula section added to the CLI reference preamble.
apps/fumadocs/content/docs/components/convex-email.mdx	Adds typed-return note for status/listEvents; `ConvexEmailDoc
packages/convex-email/README.md	Mirrors the typed-return note from the component docs; all three types are confirmed exported from client/index.ts lines 255–263.
apps/fumadocs/content/docs/meta.json	Inserts "telemetry" between "authentication" and "concepts" in the sidebar pages array; matches the location of telemetry.mdx at the docs root.
AGENTS.md	Clarifies credential-loading order to .env.local, then .env, then shell; a straightforward prose improvement.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User installs email-sdk] --> B{Install method}
    B -->|npm / project| C[npx email-sdk / local binary]
    B -->|bunx / no-install| D[bunx email-sdk]
    B -->|Homebrew global| E[brew install --formula URL]
    E --> F[email-sdk binary on PATH]
    C & D & F --> G[CLI commands\nadapters · doctor · send]
    G --> H{Telemetry enabled?}
    H -->|Yes default| I[capture cli command run → PostHog]
    H -->|No: EMAIL_SDK_TELEMETRY=0\nDO_NOT_TRACK=1\nNODE_ENV=test\ntelemetry:false| J[No-op telemetry]
    I --> K[fire-and-forget 3 s timeout]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User installs email-sdk] --> B{Install method}
    B -->|npm / project| C[npx email-sdk / local binary]
    B -->|bunx / no-install| D[bunx email-sdk]
    B -->|Homebrew global| E[brew install --formula URL]
    E --> F[email-sdk binary on PATH]
    C & D & F --> G[CLI commands\nadapters · doctor · send]
    G --> H{Telemetry enabled?}
    H -->|Yes default| I[capture cli command run → PostHog]
    H -->|No: EMAIL_SDK_TELEMETRY=0\nDO_NOT_TRACK=1\nNODE_ENV=test\ntelemetry:false| J[No-op telemetry]
    I --> K[fire-and-forget 3 s timeout]

Loading

_{Reviews (1): Last reviewed commit: "docs(agents): live-check scripts also lo..." | Re-trigger Greptile}