docs: document the telemetry subsystem on the docs site

[tembo]

Summary

The PostHog telemetry subsystem (packages/email-sdk/src/telemetry.ts, shipped in #141) is covered in the repo README.md and in AGENTS.md (via the just-merged #145), but the canonical docs site — the one the README points users to ("Full docs live at email-sdk.dev/docs") — had no telemetry page. For a privacy-sensitive, on-by-default feature, that is the exact gap a user would go looking for and not find. The telemetry client option was also missing from the createEmailClient reference.

This is a documentation-only change.

Docs added / updated

• New page content/docs/telemetry.mdx — a top-level page (parallel to authentication.mdx) covering:
  • What telemetry is and the first-run stderr notice.
  • What gets collected, broken out per event (client created, email sent, email batch sent, cli command run) plus the fixed environment facts.
  • What is never collected, and the anonymous-ID storage at ~/.config/email-sdk/telemetry.json (with the $XDG_CONFIG_HOME and read-only-fallback behavior).
  • The redacted error-report path (redaction categories, the fire-and-forget 3s timeout, per-process dedupe/cap, and that EmailValidationError / EmailProviderNotFoundError are never reported).
  • Opting out: EMAIL_SDK_TELEMETRY (0/false/off), DO_NOT_TRACK (1/true), the automatic NODE_ENV=test disable, and the per-client telemetry: false option.
• content/docs/meta.json — added telemetry to the nav, after authentication.
• content/docs/reference/client.mdx — added the telemetry?: boolean option to the createEmailClient TypeTable (default true) and a sentence cross-linking to the new page and the env-var opt-outs.

Codepaths covered

Every claim was verified against source at main:

• packages/email-sdk/src/telemetry.ts — TELEMETRY_NOTICE, isTelemetryDisabled (env opt-outs + NODE_ENV=test), normalizeAdapterName (custom → custom), createTelemetry (anonymous ID, config dir / XDG_CONFIG_HOME, read-only fallback, CAPTURE_TIMEOUT_MS, per-process dedupe/MAX_EXCEPTIONS_PER_PROCESS), isReportableSendError, detectCiVendor, and the redactErrorMessage scrubbing set.
• packages/email-sdk/src/core.ts — the telemetry: options.telemetry === false ? undefined : getTelemetry() gate and the exact capture(...) property sets for the client created, email sent, and email batch sent events.
• packages/email-sdk/src/cli.ts — setTelemetrySource("cli") and the cli command run capture.
• packages/email-sdk/src/types.ts — telemetry?: boolean on the client options.

Key knowledge gaps addressed

• The docs site now has a discoverable, canonical answer to "what does Email SDK collect and how do I turn it off?" instead of that living only in the README.
• The telemetry client option is now in the API reference, matching the env-var story.

Validation

• bun run types:check in apps/fumadocs — passed (MDX compiles, tsc --noEmit clean).
• bun run docs:versions:check — passed.

No source or behavior changes; existing telemetry behavior is unchanged.

---

Triggered by the merge of #145 (docs automation on pull_request.merged).

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

[tembo]

Requesting review from @leoisadev1 who has experience with the following files modified in this PR:

• apps/fumadocs/content/docs/meta.json

[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:15pm