docs(adapter-contract): document optional sendBulk native batch method

[tembo]

Summary

Follow-up documentation for the batch/recipientVariables feature merged in #125. That PR thoroughly documented the user-facing surface (message + client references, Mailgun/SendGrid adapter pages, field-support matrix), but the new optional EmailProvider.sendBulk method was left undocumented in the adapter-authoring reference. Adapter authors reading the canonical type contract would see an EmailProvider shape that no longer matches the source, with no guidance on implementing native batch personalization.

This is a documentation-only change. No code was touched.

Docs added/updated

• reference/adapter-contract.mdx
  • Added sendBulk to the EmailProvider type block and its <TypeTable>, so the contract matches packages/email-sdk/src/types.ts.
  • New "Native batch sends (sendBulk)" section covering: when the client routes to sendBulk vs send, the exact shape of the message it receives (unexpanded, tokens still literal, recipientVariables attached), the retry/this-binding/error behavior, the assertMaxItems 1000-recipient fail-fast pattern, the built-in { ...provider, sendBulk: provider.send } implementation pattern, and an explicit note that omitting sendBulk is safe because the client falls back to one rendered send per recipient.
• guides/authoring/create-adapter.mdx
  • One checklist line pointing to the new section, framing sendBulk as an optional optimization so the basic-adapter walkthrough stays focused.

Codepaths covered

• packages/email-sdk/src/types.ts — EmailProvider.sendBulk, RecipientVariables.
• packages/email-sdk/src/core.ts — attemptProvider routing (native sendBulk vs sendBulkViaFallback), per-recipient idempotency suffix, aggregated accepted/rejected, all-recipients-failed fallthrough.
• packages/email-sdk/src/mailgun.ts / sendgrid.ts — sendBulk: send wiring, assertMaxItems(..., 1000) cap, per-recipient personalizations.
• packages/email-sdk/src/utils.ts / payloads.ts — hasRecipientVariables, assertMaxItems, recipientVariableEntries, token substitution.

Key knowledge gaps addressed

• How and when the client dispatches to sendBulk (only when both recipientVariables is present and the adapter implements it).
• That the message reaching sendBulk is unexpanded — the adapter, not the client, drives provider-side substitution.
• The mandatory batch-cap fail-fast, mirroring the built-in adapters.
• That sendBulk is a pure performance optimization: the feature works on every adapter via the client-side fallback whether or not an adapter implements it.

Validation

MDX-content-only edits; anchor slugs verified against the referenced headings. The docs app (apps/fumadocs) dependencies are not installed in this sandbox and packages can't be installed here, so bun run types:check / build were not run. No source, config, or frontmatter changed — only prose within existing pages.

---

Triggered by the merge of #125 (pull_request.merged).

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

[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 3:27pm

[tembo]

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

• apps/fumadocs/content/docs/reference/adapter-contract.mdx
• apps/fumadocs/content/docs/guides/authoring/create-adapter.mdx

[leoisadev1]

Closing as superseded by the #128 docs rewrite: reference/adapter-contract.mdx on main now documents sendBulk in the EmailProvider type and the options table (including the recipientVariables routing and per-recipient fallback), and reference/message.mdx covers the client-side fallback semantics in depth. The extra implementation detail here (assertMaxItems, jsonProvider wiring) is internal-helper territory the rewritten page intentionally keeps brief.