docs: humanize and rewrite the documentation

[leoisadev1]

Closes #105

What this does

A full pass over every current docs page (apps/fumadocs/content/docs/**) and both READMEs, with two goals: make the docs read like a maintainer wrote them, and fix everything the docs get wrong about the code. All claims were verified against packages/email-sdk/src (types.ts, core.ts, utils.ts, every adapter, cli.ts) and packages/convex-email. Routes, slugs, meta.json, versioned doc archives, the blog, and generated files are untouched.

Factual errors corrected

• Adapter counts were stale everywhere. The landing page said "20 providers", the adapters index said "22 adapters", the adapter-contract reference said "the 20 adapters". The package exports 23 adapters; every count now says 23.
• "Resend is the only adapter that transmits idempotency keys natively" was false on three pages (fallbacks-and-retries, message reference, production pipeline, create-adapter guide). JetEmail, Lettermint, and Primitive also forward Idempotency-Key; all four are now listed, along with SMTP's Message-ID behavior.
• The routing-name list in the adapter model omitted jetemail, lettermint, and primitive.
• The auth page claimed every adapter accepts baseUrl/headers/fetch. Only five adapters take headers, and SMTP takes none of the three; the section now says which adapters take what.
• Field-support matrix: Unosend and SparkPost were marked as sending tag values only, but both preserve full name/value pairs.
• Both READMEs were missing Lettermint from their adapter lists, and the root README also dropped AWS SES. The message reference now names Lettermint among single-tag providers, and the Lettermint page clarifies its 50-recipient cap is provider-side, not adapter-checked.
• The Convex page now says the component supports 20 provider kinds (it does not wrap jetemail/lettermint/primitive yet), instead of implying it covers every SDK adapter.

Slop removed

• The identical template opener ("calls the X API over fetch — no extra dependency") and closer ("Drop --dry-run for one real send — that is the only check that proves…") stamped across all 23 adapter pages. Each page keeps a uniform one-line opener (endpoint plus fetch), puts the provider's actual quirks in the sentence right after it, and closes with what a live send specifically proves for that provider.
• Em-dash chains (several per paragraph, sitewide), "never X" tailing negations ("routes are explicit, never guessed"), bold-lead marketing bullets on the landing page, and stock fragments like "that distinction is the whole design".
• Where a punchy fragment carried real information, it was rewritten as a full sentence with the reasoning kept (e.g. why fail-fast field validation beats silent drops).

Review fixes

Follow-up commit addressing adversarial-review findings:

• CLI reference tables were missing jetemail, lettermint, and primitive in both the adapters/env table and the credential-flags table, which also made the auto-detection order wrong. Both tables now match cli.ts row for row (jetemail/lettermint/primitive sit between sequenzy and plunk in detection order; Lettermint gets its own flags row for --api-token/--base-url/--route).
• The authentication page's fallback example registered Resend and SES but never set fallback: ["ses"], leaving SES as dead code. Fixed.
• Six adapter pages (jetemail, lettermint, primitive, sequenzy, unosend, zeptomail) shared a near-identical "one real smoke send to prove X and Y" closer. Each is now specific to the provider: route resolution for Lettermint, accepted/rejected and async delivery for Primitive, jobId and slug lookup for Sequenzy, Mail Agent scoping for ZeptoMail, and so on.
• README line 26 still had an em-dash + "never" construction; rewritten plainly.
• A cadence pass on components/convex-email.mdx and guides/production-send-pipeline.mdx, where several sentences were the old em-dash constructions with a semicolon swapped in. The most conspicuous ones were restructured into genuinely different sentences.

Merge with main + new feature docs

Main moved a lot under this branch (#126 delivery status tracking, #125 recipient variables, #127 scheduled sends, #121 fumadocs README, #120/#122 AGENTS.md, #129 Homebrew). The merge keeps main's feature facts and this PR's prose:

• field-support.mdx: kept the corrected tag columns (Unosend/SparkPost = full name/value) and took main's new Send at column; the whole matrix re-verified cell-for-cell against SUPPORTED_MESSAGE_FIELDS in utils.ts.
• Feature docs rewritten into the overhaul voice (facts unchanged): the recipient-variables and scheduled-sends sections in reference/message.mdx, the batch sections on the Mailgun/SendGrid pages, the sendAt sentences on all seven scheduling adapters, and the delivery-tracking + setConfig-replace sections on the Convex page (severity/Type-gated bounce mapping and sticky semantics verified against lib.ts/worker.ts).
• New features got findable homes: cross-links from the quickstart and landing page, sendBulk documented in the adapter contract, all_recipients_failed added to the errors page, per-recipient idempotency-key suffixing noted in fallbacks-and-retries, and the per-recipient afterSend/onError firing exception noted on the hooks page. The Iterable page now distinguishes its adapter-config sendAt from the rejected message-level field.

Greptile P2 fixes

• Tag semantics: the field-support legend and the message reference now say which one-tag provider keeps what — Postmark sends a joined name:value string, Mailtrap and Lettermint forward only the value (verified against all three adapter sources).
• OG cache window (apps/fumadocs/README.md): already accurate on main as merged — the table, "How it works", and "Publishing cadence" all state the /og/blog/* max-age=86400 (~1 day) window separately from the ~60s blog pages. No change needed.

Telemetry pre-integration

Both READMEs already carry the telemetry disclosure section from the telemetry branch, rewritten in this PR's voice with identical facts (collected properties including recipient-variables/scheduling usage and delivery path, redaction rules, ~/.config/email-sdk/telemetry.json, EMAIL_SDK_TELEMETRY=0 / DO_NOT_TRACK=1 / telemetry: false / NODE_ENV=test opt-outs), so the post-merge rebase for that PR is near-clean. privacy.tsx is untouched here and merges cleanly from that branch. README feature lists now mention batch personalization and scheduled sends.

Validation

• bun run types:check in apps/fumadocs (fumadocs-mdx + tsc): passes.
• bun run build in apps/fumadocs: exit 0, all doc routes prerender.
• Field-support matrix re-derived from SUPPORTED_MESSAGE_FIELDS in utils.ts; CLI tables re-checked against cli.ts after the review fixes.

---

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 6:27pm

[greptile-apps]

Greptile Summary

This PR is a documentation overhaul across all 56 MDX files and both READMEs. Every factual claim was verified against source code (types.ts, utils.ts, and each adapter's .ts file), and stale counts/lists were updated throughout.

• Factual corrections verified: adapter count corrected to 23 everywhere; idempotency-key adapters expanded from "Resend only" to Resend, JetEmail, Lettermint, and Primitive (confirmed via context.idempotencyKey header injection in each adapter); SparkPost and Unosend tag columns corrected from Values to Yes (SparkPost maps tags as substitution_data key-value pairs; Unosend forwards message.tags directly); missing jetemail/lettermint/primitive rows added to the CLI adapter table and credential-flags table with correct env vars and detection order.
• Broken example fixed: the authentication page's multi-provider example was registering SES but never listing it in fallback, making it dead code — the fallback: ["ses"] line has been added.
• Prose cleanup: em-dash chains, bold-lead marketing bullets, and repeated template openers/closers across adapter pages removed; previous review comments on tag-name/value semantics for single-tag providers addressed in both the field-support legend and the message reference.

Confidence Score: 5/5

Documentation-only PR with no source code changes; every factual claim was verified against adapter source files and utils.ts before being updated.

All corrections checked out against the implementation: adapter count is exactly 23, idempotency-key header injection is present in jetemail/lettermint/primitive, SparkPost and Unosend both preserve tag names, the five-adapter headers option list matches source, and CLI table env vars match cli.ts line-for-line. The only executable change adds the missing fallback: ["ses"] to fix a dead-code example.

No files require special attention. The changes are entirely in MDX documentation files; no production logic was touched.

Important Files Changed

Filename	Overview
apps/fumadocs/content/docs/adapters/field-support.mdx	Legend updated with Postmark vs Mailtrap/Lettermint tag-name distinction; SparkPost and Unosend tag columns corrected from Values to Yes — both verified against SUPPORTED_MESSAGE_FIELDS and adapter source.
apps/fumadocs/content/docs/authentication.mdx	Headers option now correctly scoped to 5 adapters (Resend, Postmark, JetEmail, Lettermint, Primitive — verified from source); missing fallback: ["ses"] added to the multi-provider code example.
apps/fumadocs/content/docs/reference/cli.mdx	jetemail, lettermint, primitive rows added to both the adapters/env table and credential-flags table in the correct order (between sequenzy and plunk) with correct env vars, verified row-for-row against cli.ts.
apps/fumadocs/content/docs/reference/message.mdx	Idempotency-key adapters expanded from Resend only to include JetEmail, Lettermint, and Primitive; tag-name semantics for single-tag providers clarified; all verified against adapter source files.
apps/fumadocs/content/docs/concepts/fallbacks-and-retries.mdx	Idempotency-key section updated to list all four native adapters; per-recipient key suffixing note added; prose improved without changing facts.
apps/fumadocs/content/docs/components/convex-email.mdx	Provider count corrected to 20 supported provider kinds (matches the 20 kinds listed in the config section — jetemail/lettermint/primitive are not yet wrapped); setConfig replace-vs-merge semantics documented accurately.
apps/fumadocs/content/docs/reference/adapter-contract.mdx	sendBulk optional method documented and verified present in types.ts (line 94); 20 adapters reference replaced with built-in adapters.
README.md	AWS SES and Lettermint re-added to adapter list; telemetry disclosure reformatted as scannable bullets (facts unchanged); emoji removed from feature list; adapter count updated to 23.
packages/email-sdk/README.md	Lettermint entry added to the adapter entry points table; telemetry disclosure reformatted; recipientVariables and sendAt features mentioned.
apps/fumadocs/content/docs/concepts/adapter-model.mdx	Routing names list updated to include jetemail, lettermint, and primitive — matches cli.ts detection order exactly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["PR #128: Docs overhaul"] --> B["Factual corrections"]
    A --> C["Missing adapter entries"]
    A --> D["Prose/style cleanup"]
    A --> E["Broken example fix"]

    B --> B1["Adapter count: 22→23 everywhere"]
    B --> B2["Idempotency-Key: Resend only→\nResend+JetEmail+Lettermint+Primitive"]
    B --> B3["SparkPost/Unosend tags:\nValues→Yes (name+value preserved)"]
    B --> B4["Tag-name semantics: One-tag providers\nPostmark=name:value, Mailtrap/Lettermint=value only"]
    B --> B5["Auth page: headers option\nlimited to 5 adapters, not all"]
    B --> B6["Convex: 20 provider kinds\nnot all 23 SDK adapters"]

    C --> C1["CLI adapters/env table:\njetemail, lettermint, primitive rows added"]
    C --> C2["CLI credential-flags table:\nlettermint own row (--api-token)"]
    C --> C3["Adapter-model routing names:\njetemail, lettermint, primitive added"]
    C --> C4["README adapter lists:\nAWS SES + Lettermint re-added"]

    E --> E1["authentication.mdx example:\nfallback: ['ses'] was missing"]

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["PR #128: Docs overhaul"] --> B["Factual corrections"]
    A --> C["Missing adapter entries"]
    A --> D["Prose/style cleanup"]
    A --> E["Broken example fix"]

    B --> B1["Adapter count: 22→23 everywhere"]
    B --> B2["Idempotency-Key: Resend only→\nResend+JetEmail+Lettermint+Primitive"]
    B --> B3["SparkPost/Unosend tags:\nValues→Yes (name+value preserved)"]
    B --> B4["Tag-name semantics: One-tag providers\nPostmark=name:value, Mailtrap/Lettermint=value only"]
    B --> B5["Auth page: headers option\nlimited to 5 adapters, not all"]
    B --> B6["Convex: 20 provider kinds\nnot all 23 SDK adapters"]

    C --> C1["CLI adapters/env table:\njetemail, lettermint, primitive rows added"]
    C --> C2["CLI credential-flags table:\nlettermint own row (--api-token)"]
    C --> C3["Adapter-model routing names:\njetemail, lettermint, primitive added"]
    C --> C4["README adapter lists:\nAWS SES + Lettermint re-added"]

    E --> E1["authentication.mdx example:\nfallback: ['ses'] was missing"]

Loading

_{Reviews (4): Last reviewed commit: "merge main after telemetry (#141); keep ..." | Re-trigger Greptile}

[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.

[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.

[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.