docs(reference): document the telemetry subsystem

[tembo]

Why

PR #128 (docs humanize/rewrite) and #141 (PostHog telemetry) landed together. The telemetry subsystem is a substantial, privacy-relevant, user-facing feature, but it only exists in the two READMEs — the docs site (apps/fumadocs/content/docs/**) has no page for it, and the telemetry client option was missing from the client reference entirely. This closes that gap. Docs-only; no source changes.

Docs added/updated

• New page reference/telemetry.mdx (added to reference/meta.json nav). Covers, verified against source:
  • What gets collected — the four analytics events (client created, email sent, email batch sent, cli command run), their notable properties, the environment fingerprint, the sdk/cli source tag, and the two "no user strings" rules (adapter-name normalization to custom/unknown, recipient counts not recipients).
  • Error reports — which errors are excluded (EmailValidationError, EmailProviderNotFoundError), the message/stack/error-name redaction passes, and the per-process rate limits (5 exceptions, per-object/per-class dedupe, 3-link cause chain, 20 frames).
  • The anonymous ID — random UUID in ~/.config/email-sdk/telemetry.json (honors XDG_CONFIG_HOME), read-only-environment fallback.
  • Delivery — write-only PostHog key, 3s timeout, fire-and-forget/never-throws, CLI flush-before-exit.
  • Opting out — EMAIL_SDK_TELEMETRY=0, DO_NOT_TRACK=1, telemetry: false client option, and automatic NODE_ENV=test.
• reference/client.mdx — added the previously-undocumented telemetry?: boolean option to the createEmailClient TypeTable and cross-linked it to the new page.

Codepaths covered

• packages/email-sdk/src/telemetry.ts — event/exception capture, redaction (redactErrorMessage, sanitizeFrameFilename, sanitizeErrorName), opt-out logic (isTelemetryDisabled), state file (loadTelemetryState/persistTelemetryState), delivery, dedupe/budget caps, normalizeAdapterName, isReportableSendError, detectCiVendor.
• packages/email-sdk/src/core.ts — client created / email sent / email batch sent capture calls and their exact property sets, the telemetry === false opt-out, and captureException on failed sends.
• packages/email-sdk/src/cli.ts — setTelemetrySource("cli"), cli command run capture, and flush() before exit.
• packages/email-sdk/src/types.ts — the telemetry?: boolean client option.

Key knowledge gaps addressed

• The telemetry feature had zero presence in the docs-site navigation despite being on by default and privacy-relevant.
• The telemetry client option was undocumented in the client reference.
• Consolidates the "what is collected / how it's redacted / how to opt out" story into one findable, source-verified page instead of only a README section.

Validation

• bun run types:check (fumadocs-mdx + tsc) in apps/fumadocs: passes.
• bun run build in apps/fumadocs: exit 0; /docs/reference/telemetry, #opting-out, and the client #createemailclientoptions cross-link all prerender.
• All factual claims re-verified against telemetry.ts, core.ts, cli.ts, and types.ts. Versioned archives (docs-v/**), routes, and generated files untouched.

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/reference/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 6:58pm