email-sdk

# Email SDK Use this skill when an agent works with this repository or wires `@opencoredev/email-sdk` into another TypeScript app. This skill is intentionally dynamic: do not treat the examples below as the full current API or template catalog. First refresh the local package docs/source for the installed version, then implement against what the repo, dependency, and current machine-readable documentation actually expose. ## Refresh Current Docs Before changing code, inspect the most relevant current sources: 1. If you are inside this repo, read: - `README.md` - `packages/email-sdk/README.md` - `packages/email-sdk/package.json` - `apps/fumadocs/content/docs/**/*.mdx` - `packages/email-sdk/src/index.ts` - the specific adapter file in `packages/email-sdk/src/<adapter>.ts` - `packages/email-sdk/src/types.ts`, `core.ts`, and `errors.ts` when message shape, routing, retries, hooks, or error handling matter. 2. If you are inside an app that has `@opencoredev/email-sdk` installed, inspect: - the app lockfile and `node_modules/@opencoredev/email-sdk/package.json` - `node_modules/@opencoredev/email-sdk/README.md` - `node_modules/@opencoredev/email-sdk/dist/*.d.ts` - the app's existing email, notification, queue, environment, and test patterns. 3. If local docs are missing or the task depends on version-sensitive behavior, fetch the current published package metadata/docs before implementing: - `bun pm view @opencoredev/email-sdk` - `bun email-sdk version` when the CLI is installed in the target app - `https://email-sdk.dev/docs/llms.txt` to discover the current documentation tree - the exact raw Markdown page at `https://email-sdk.dev/docs/<path>.md` - the repository docs or package README for the exact version in use. Prefer the raw `.md` endpoints over scraping rendered HTML. They return `Content-Type: text/markdown`, preserve current internal links, and include the page title and canonical route. For React Email UI or template work: 1. Fetch `https://email-sdk.dev/docs/ui.md` first. 2. Follow its current category and template links instead of relying on a hard-coded template list. 3. Fetch the chosen template page as raw Markdown, for example `https://email-sdk.dev/docs/ui/account/verification-code.md`. 4. Use the documented `shadcn@latest add` registry URL when installation is requested, or copy the Manual source from the same page. 5. Keep templates on the actual `@opencoredev/email-sdk/react` primitives and verify both light and dark email themes when changing presentation. When local source and external docs disagree, prefer the code/types for the exact installed version and mention the mismatch. ## Defaults - Prefer `bun` and `bunx`. - Keep the core dependency-free. - Import adapters from separate entry points such as `@opencoredev/email-sdk/resend`, `@opencoredev/email-sdk/smtp`, and the adapter-specific entry point shown by the current package exports. - Do not add Nodemailer for SMTP; Email SDK includes its own SMTP transport. - SMTP auth on non-secure ports upgrades with STARTTLS by default. Only use `allowInsecureAuth` for trusted local test servers. - Adapters must either map a normalized `EmailMessage` field or reject it clearly. Never silently drop CC, BCC, reply-to, headers, tags, metadata, or attachments. - Keep adapter credentials in environment variables. - Never log API keys, SMTP passwords, raw tokens, full message bodies, or unnecessary recipient data. - Preserve the host app's architecture for queues, templates, env validation, retries, and tests. ## Integration Pattern Entry point names like `@opencoredev/email-sdk/resend` and `@opencoredev/email-sdk/smtp` are illustrative. Verify the exact exports from the installed version before copying these imports. Prefer wiring Email SDK as a production send pipeline: one normalized message shape, explicit adapter routes, fail-fast field support, retries, compatible fallback routes, secret-safe observability, tests, and CLI verification. ```ts import { createEmailClient } from "@opencoredev/email-sdk"; import { resend } from "@opencoredev/email-sdk/resend"; import { smtp } from "@opencoredev/email-sdk/smtp"; export const email = createEmailClient({ adapters: [ resend({ apiKey: process.env.RESEND_API_KEY! }), smtp({ host: process.env.SMTP_HOST!, port: Number(process.env.SMTP_PORT ?? 587), auth: { user: process.env.SMTP_USER!, pass: process.env.SMTP_PASS!, }, }), ], fallback: { adapters: ["smtp"] }, retry: { maxAttempts: 2 }, }); ``` ## Fallback and retry guidance - Choose fallback routes only after checking the current field support docs or adapter source. - Use fallback only when the backup adapter can send the same class of email and preserve the fields that matter to the app. - Do not treat SMTP as a universal backup; it is best for simple text/html sends with address fields and headers. - Use idempotency keys for externally visible transactional sends that may be retried or sent through fallback routes. - Use hooks or `observabilityPlugin()` for redacted route, attempt, retry, success, and error events. - Add tests with `memoryAdapter()`, `failingAdapter()`, and `capturePlugin()` when fallback or retry behavior matters. - Use the CLI `doctor` and `send --dry-run` before live provider authentication checks. - Use the separate `email-sdk-migrate` skill for v0-to-v1 application migrations instead of applying static find-and-replace rules. Inside this repo, the main public docs for this pattern are: - `apps/fumadocs/content/docs/guides/production-send-pipeline.mdx` - `apps/fumadocs/content/docs/concepts/fallbacks-and-retries.mdx` - `apps/fumadocs/content/docs/adapters/field-support.mdx` ## Validation - For SDK changes, run `bun test` in `packages/email-sdk`. - For docs changes, run `bun run check-types` and `bun run build` from the repo root when practical. - For app integrations, run the narrowest test/typecheck that covers the send path. - For real provider authentication checks, use the repository's non-sending `live:*` scripts when available. Do not send external mail without the user's separate approval. ## Review Checklist - Does every send include `from`, `to`, `subject`, and either `html` or `text`? - Are fallbacks configured only for adapters that can send the same class of email? - Are idempotency keys used for externally visible transactional sends? - Are provider errors surfaced instead of swallowed? - Are hooks used for metadata and status, not secret or full-body logging? - Does each adapter payload have a test when its field mapping changes?