# Email SDK > Email for TypeScript apps. Send transactional email with your existing provider account, validate messages, test without sending, and inspect failures in a server-side SDK. Email SDK is an open-source, server-side TypeScript library (npm: `@opencoredev/email-sdk`) for transactional email. Send with your existing provider account, validate message fields, test with no-network adapters, and inspect common error types. It ships 26 provider API adapters plus SMTP, 27 adapters total, so changing providers later is optional. It is a library installed in your app, not a hosted API or a service you sign up for. Your provider still handles credentials, billing, and delivery. ## When to use Email SDK Use it in a Node.js 20+ or Bun 1.1+ app when you want field-support validation, memory and failing test adapters, common errors, or configurable retry and fallback policies. Start with one provider. Changing adapters later keeps the message shape, but field support and provider behavior differ. ## When not to use it - A direct provider SDK is sufficient if you only need its send API and already handle tests and failures. Prefer it for provider-specific APIs outside the common message model. - It is not a marketing/campaign builder, CRM, or hosted email service. - It is not for browser bundles. Do not assume edge/Workers compatibility with the server-side package. ## How AI agents should use it Install the package, import the adapter for the provider whose credentials the app already holds, and call `send()`. There is nothing to authenticate against at email-sdk.dev — per-provider credentials live at https://email-sdk.dev/docs/getting-started/credentials. Give models the `send_email` tool from `@opencoredev/email-sdk/agent-tools`, and follow the constraints below. ## Constraints - Server-side Node.js 20+ or Bun 1.1+ only. Keep provider credentials out of browser bundles. - Bring your own provider credentials and keep them in environment variables. Never hardcode or log API keys, passwords, tokens, full message bodies, or recipient lists. - Import each adapter from its own entry point (`@opencoredev/email-sdk/resend`, `/smtp`, …); do not add Nodemailer — the SDK ships its own SMTP transport. - Configure fallback only between adapters that support the same fields (see https://email-sdk.dev/docs/adapters/field-support). Start with `retry: { maxAttempts: 1 }`. Enabled retries can repeat unknown outcomes when errors are retryable; fallback stopping on unknown delivery does not prevent those retries. Inspect uncertain outcomes before resending. Idempotency support is provider-specific, not a universal duplicate-prevention guarantee. - A send receipt records provider acceptance, not delivery. Default doctor checks local configuration. Explicit `doctor --live` checks authentication for supported adapters; Resend additionally supports sender-domain readiness with `--from`. These checks do not prove key-level sending permission or delivery. - The CLI does not load .env files. Export credentials into the server process. Local checks and dry runs can send opt-out telemetry; set `EMAIL_SDK_TELEMETRY=0` or `DO_NOT_TRACK=1` for network-free local validation. - Gate agent-initiated sends behind explicit human approval. Run the CLI `doctor` and `send --dry-run` before any live send. The CLI sends if `--dry-run` is omitted; only the standalone first-send starter requires an explicit `--send` flag. ## Documentation Append `.md` to any documentation URL (for example https://email-sdk.dev/docs/adapters/resend.md) to fetch the same page as raw markdown. - [Email SDK](https://email-sdk.dev/docs): Email for TypeScript apps. Send transactional email through 27 adapters with one typed SDK. - Get started - [Install](https://email-sdk.dev/docs/getting-started/install): Install Email SDK for Node.js or Bun using ESM imports or CommonJS require. - [Quickstart](https://email-sdk.dev/docs/getting-started/quickstart): Create a Resend client and send your first email. - [Provider credentials](https://email-sdk.dev/docs/getting-started/credentials): Configure adapter credentials in the server environment and verify required values with the CLI. - [AI agent skill](https://email-sdk.dev/docs/getting-started/agent-skill): Install dynamic Email SDK guidance for AI agents that integrate, review, or document the package. - Adapters - [Adapters](https://email-sdk.dev/docs/adapters): Configure one of 26 provider API adapters or the built-in SMTP transport, 27 adapters total. - [Adapter pricing](https://email-sdk.dev/docs/adapters/pricing): Compare estimated monthly prices for 26 provider APIs from 1,000 to 1 million sends; SMTP costs depend on your service. - [Resend](https://email-sdk.dev/docs/adapters/resend): Send through the Resend API with attachments, tags, and native idempotency keys. - [Sequenzy](https://email-sdk.dev/docs/adapters/sequenzy): Send through the Sequenzy transactional API with metadata variables, template slugs, and URL or base64 attachments. - [JetEmail](https://email-sdk.dev/docs/adapters/jetemail): Send through the JetEmail transactional API with CC, BCC, reply-to, custom headers, base64 attachments, and idempotent retries. - [Primitive](https://email-sdk.dev/docs/adapters/primitive): Send through Primitive's email API for AI agents, with base64 attachments, idempotent retries, and fail-fast validation for fields it cannot represent. - [Lettermint](https://email-sdk.dev/docs/adapters/lettermint): Send through Lettermint's European transactional email API with CC, BCC, reply-to, headers, metadata, tags, base64 attachments, idempotent retries, and routes. - [Lettr](https://email-sdk.dev/docs/adapters/lettr): Send through Lettr's SaaS email API with CC, BCC, reply-to, headers, metadata, a single tag, attachments, and scheduled delivery. - [Postmark](https://email-sdk.dev/docs/adapters/postmark): Send through the Postmark Email API with message streams, metadata, and Postmark's single-tag model. - [SendGrid](https://email-sdk.dev/docs/adapters/sendgrid): Send through the Twilio SendGrid Mail Send API with the fullest field support of any adapter. - [Cloudflare Email Sending](https://email-sdk.dev/docs/adapters/cloudflare): Send through Cloudflare's Email Sending REST API or Worker binding with plain-address recipients and a 50-recipient cap. - [Unosend](https://email-sdk.dev/docs/adapters/unosend): Send through the Unosend REST API, a single Bearer-authenticated endpoint with CC, BCC, tags, and attachments. - [AWS SES](https://email-sdk.dev/docs/adapters/ses): Send through the SES v2 SendEmail API with built-in SigV4 signing and no AWS SDK dependency. - [Mailgun](https://email-sdk.dev/docs/adapters/mailgun): Send through the Mailgun Messages API with domain-scoped multipart sends, h:/v:/o: field mapping, and full field support. - [MailerSend](https://email-sdk.dev/docs/adapters/mailersend): Send through the MailerSend Email API with cc/bcc, headers, tags, attachments, and a single reply-to address. - [Brevo](https://email-sdk.dev/docs/adapters/brevo): Send through the Brevo transactional email API with full field support and metadata mapped to template params. - [Mailchimp Transactional](https://email-sdk.dev/docs/adapters/mailchimp): Send through Mailchimp Transactional (Mandrill) with typed recipients, tags, and metadata, but no replyTo field. - [SparkPost](https://email-sdk.dev/docs/adapters/sparkpost): Send through the SparkPost Transmissions API with metadata, substitution data from tags, and a provider-side sandbox mode. - [Iterable](https://email-sdk.dev/docs/adapters/iterable): Trigger an Iterable campaign template for one recipient, with message content delivered as dataFields. - [Microsoft Graph](https://email-sdk.dev/docs/adapters/graph): Send through Microsoft Graph's sendMail API with OAuth 2.0 client credentials or custom token providers for managed identity and certificate authentication. - [Loops](https://email-sdk.dev/docs/adapters/loops): Trigger a published Loops transactional email for one recipient, with metadata delivered as dataVariables. - [Plunk](https://email-sdk.dev/docs/adapters/plunk): Send through the Plunk API with reply-to, headers, attachments, and metadata mapped to Plunk data. - [Mailtrap](https://email-sdk.dev/docs/adapters/mailtrap): Send through the Mailtrap Email Sending API with full field support and provider-side message inspection. - [Scaleway](https://email-sdk.dev/docs/adapters/scaleway): Send through Scaleway Transactional Email with region-scoped endpoints and header-based reply-to. - [ZeptoMail](https://email-sdk.dev/docs/adapters/zeptomail): Send through Zoho ZeptoMail with automatic send-mail token prefixing. - [MailPace](https://email-sdk.dev/docs/adapters/mailpace): Send through the MailPace API, a deliberately minimal adapter for address fields and body content. - [SendHeron](https://email-sdk.dev/docs/adapters/sendheron): Send through the SendHeron transactional email API with native idempotency, scheduling, and suppressed sends reported as errors. - [Helo](https://email-sdk.dev/docs/adapters/helo): Send individual emails through Helo's transactional endpoint with native idempotency, Channel routing, tags, and metadata. - [SMTP](https://email-sdk.dev/docs/adapters/smtp): Send over SMTP with a standards-compliant MIME transport. No HTTP API. - [Field support](https://email-sdk.dev/docs/adapters/field-support): Source-derived support for normalized message fields across all built-in adapters. - [Delivery capabilities](https://email-sdk.dev/docs/adapters/capability-groups): Decide when an adapter can preserve repeated headers, idempotency, scheduled delivery, or personalized fanout. - [How adapters are tested](https://email-sdk.dev/docs/adapters/verification): Separate contract tests and configured authentication probes from dated auth, send, and delivery evidence for all 27 adapters. - Concepts - [Adapter model](https://email-sdk.dev/docs/concepts/adapter-model): How adapters turn one Email SDK message into a provider request. - [Retries and fallback](https://email-sdk.dev/docs/concepts/fallbacks-and-retries): Retry one provider, then decide when it is safe to try another. - [Hooks and middleware](https://email-sdk.dev/docs/concepts/hooks): Observe sends with hooks or change them with middleware. - [Sending modes](https://email-sdk.dev/docs/concepts/sending-modes): Pick the right method for batches, personalization, schedules, and idempotency. - Plugins - [Plugin system](https://email-sdk.dev/docs/plugins): Transform send options, select routes, observe lifecycle events, enforce time bounds, and extend the typed client. - Built-in plugins - [Defaults plugin](https://email-sdk.dev/docs/plugins/built-in/defaults): Apply reply-to, headers, tags, metadata, send metadata, and idempotency defaults before validation. - [Routing plugin](https://email-sdk.dev/docs/plugins/built-in/routing): Select a registered adapter from the prepared message and send options before route validation. - [Timeout plugin](https://email-sdk.dev/docs/plugins/built-in/timeout): Bound one logical send, including retries and fallback, while preserving caller cancellation. - [Observability plugin](https://email-sdk.dev/docs/plugins/built-in/observability): Emit send, retry, and error events through isolated log, metric, and trace callbacks. - [Capture plugin](https://email-sdk.dev/docs/plugins/built-in/capture): Record lifecycle events in memory and expose the store through a typed client extension. - [Community plugins and adapters](https://email-sdk.dev/docs/plugins/community): Evaluate third-party Email SDK extensions without treating them as core-maintained integrations. - UI - [Email UI](https://email-sdk.dev/docs/ui): Browse complete, email-safe templates by the job they need to do. - [Components](https://email-sdk.dev/docs/ui/components): The small set of email-safe primitives used by every template. - Account - [Verification code](https://email-sdk.dev/docs/ui/account/verification-code): A focused one-time code with a clear expiry. - [Password reset](https://email-sdk.dev/docs/ui/account/password-reset): A secure reset action with request context. - [Team invite](https://email-sdk.dev/docs/ui/account/team-invite): A personal invitation to join a workspace. - Product - [Welcome](https://email-sdk.dev/docs/ui/product/welcome): A useful first step after account creation. - [Trial ending](https://email-sdk.dev/docs/ui/product/trial-ending): An honest reminder before a trial expires. - [Usage alert](https://email-sdk.dev/docs/ui/product/usage-alert): A calm limit warning with a direct next action. - Commerce - [Receipt](https://email-sdk.dev/docs/ui/commerce/receipt): A compact payment confirmation and receipt link. - [Invoice due](https://email-sdk.dev/docs/ui/commerce/invoice-due): A clear invoice summary before payment is due. - [Refund confirmed](https://email-sdk.dev/docs/ui/commerce/refund-confirmed): A reassuring refund status with timing details. - Integrations - Convex - [Convex](https://email-sdk.dev/docs/integrations/convex): Durable, provider-portable transactional email for Convex applications. - [Install and configure](https://email-sdk.dev/docs/integrations/convex/setup): Mount the Convex component, map provider secrets, create the server client, and set safe defaults. - [Send and track email](https://email-sdk.dev/docs/integrations/convex/sending-and-status): Queue email from Convex mutations, expose reactive status, and inspect the complete event timeline. - [Process webhooks](https://email-sdk.dev/docs/integrations/convex/webhooks): Verify provider webhook requests in application code and store normalized delivery events in the Convex component. - [Test and recover](https://email-sdk.dev/docs/integrations/convex/testing-and-recovery): Redirect recipients, use in-memory delivery, inspect failure history, cancel queued work, and retry terminal failures. - [Chat SDK](https://email-sdk.dev/docs/integrations/chat-sdk): Send transactional email from Chat SDK handlers while keeping identity, authorization, and delivery policy in application code. - [AI SDK](https://email-sdk.dev/docs/integrations/ai-sdk): Add one narrow, approval-gated sendEmail tool to a Vercel AI SDK agent. - For agents - [Machine-readable Email SDK docs](https://email-sdk.dev/docs/agents): Give agents current Email SDK documentation without scraping rendered HTML. - [Machine-readable documentation](https://email-sdk.dev/docs/agents/machine-readable-docs): Use raw Markdown, LLM indexes, JSONL entities, and the schema map for agent retrieval. - Guides - [Schedule an email](https://email-sdk.dev/docs/guides/schedule-email): Use sendAt for a simple future send, and use an app-owned scheduler when you need more control. - [Build a production send pipeline](https://email-sdk.dev/docs/guides/production-send-pipeline): Validate before queueing, preserve durable state, and use retries and fallback without hiding delivery uncertainty. - [Test email behavior](https://email-sdk.dev/docs/guides/test-email-behavior): Assert normalized messages, retries, fallback routes, and lifecycle events without sending real email. - [Troubleshoot failed sends](https://email-sdk.dev/docs/guides/troubleshoot-failed-sends): Diagnose failures by the exported error class, stable code, adapter, and delivery classification. - Migration guides - [Upgrade from Email SDK 2.x to v3](https://email-sdk.dev/docs/guides/migrate/v2-to-v3): Update send-option metadata, webhook payload reads, and SMTP TLS options for the stricter v3 types. - [Upgrade from Email SDK 0.x to v1](https://email-sdk.dev/docs/guides/migrate/v0-to-v1): Migrate constructor options, send options, results, errors, batches, personalization, headers, attachments, dates, and ESM usage. - [Migrate from the Resend SDK](https://email-sdk.dev/docs/guides/migrate/resend): Replace direct Resend calls with a typed Email SDK client while keeping Resend as the delivery adapter. - [Migrate from Nodemailer](https://email-sdk.dev/docs/guides/migrate/nodemailer): Replace a Nodemailer transporter with Email SDK's typed SMTP adapter. - [Migrate from SendGrid](https://email-sdk.dev/docs/guides/migrate/sendgrid): Replace direct Mail Send payloads with normalized messages and explicit personalized sending. - Extend - [Create your first plugin](https://email-sdk.dev/docs/guides/authoring/create-first-plugin): Add typed middleware and a client extension without changing adapter behavior. - [Create an adapter](https://email-sdk.dev/docs/guides/authoring/create-adapter): Implement a literal route name, capabilities, no-network validation, sending, and typed failures. - [Publish a community plugin](https://email-sdk.dev/docs/guides/authoring/publish-community-plugin): Package a v1-compatible plugin with explicit peer versions, tests, and support documentation. - [Publish a community adapter](https://email-sdk.dev/docs/guides/authoring/publish-community-adapter): Ship a provider adapter with literal routes, capabilities, no-network validation, typed failures, and evidence-backed claims. - Reference - [Client reference](https://email-sdk.dev/docs/reference/client): Exact construction options, methods, routing helpers, validation results, and send results for the v1 client. - [Message reference](https://email-sdk.dev/docs/reference/message): Exact v1 address, envelope, body, header, attachment, metadata, tag, and schedule types. - [Adapter contract](https://email-sdk.dev/docs/reference/adapter-contract): Exact v1 adapter capabilities, validation context, send context, personalized operation, and result contract. - [Plugin API](https://email-sdk.dev/docs/reference/plugin-api): Exact plugin context, hooks, middleware, adapter registration, and typed client extension contracts. - [Webhooks](https://email-sdk.dev/docs/reference/webhooks): Verify Resend and Mailgun webhook requests and normalize Resend, Postmark, and Mailgun delivery events. - [Community registry](https://email-sdk.dev/docs/reference/community-registry): Static registry schema, trust labels, and validation for third-party adapters and plugins. - [Compatibility subpath](https://email-sdk.dev/docs/reference/compatibility): Temporary v0 source compatibility available only during the v1 major. - [Telemetry and privacy](https://email-sdk.dev/docs/reference/telemetry): Opt-out SDK and CLI analytics, redacted error reporting, storage, and privacy behavior. - CLI commands - [CLI reference](https://email-sdk.dev/docs/reference/cli): Commands, runtime, aliases, telemetry, adapter detection, and exit behavior for the email-sdk binary. - [email-sdk adapters](https://email-sdk.dev/docs/reference/cli/adapters): List every bundled CLI adapter with required environment variables and provider notes. - [email-sdk doctor](https://email-sdk.dev/docs/reference/cli/doctor): Check configuration safely by default; explicitly authenticate and inspect Resend sender readiness without sending. - [email-sdk send](https://email-sdk.dev/docs/reference/cli/send): Build one message from flags or JSON, validate it with the selected adapter, and optionally send it. - Error codes - [Error reference](https://email-sdk.dev/docs/reference/errors): Closed v1 error codes, exported classes, retryability, delivery certainty, and route failure structure. - [validation_error](https://email-sdk.dev/docs/reference/errors/validation-error): The message, route, schedule, capability, or adapter-specific input is invalid before dispatch. - [adapter_not_found](https://email-sdk.dev/docs/reference/errors/adapter-not-found): A runtime route name does not match a registered adapter. - [adapter_error](https://email-sdk.dev/docs/reference/errors/adapter-error): One adapter or transport failed with explicit retryability and delivery certainty. - [route_error](https://email-sdk.dev/docs/reference/errors/route-error): Every attempted adapter route failed without producing a successful normalized result. - [all_recipients_failed](https://email-sdk.dev/docs/reference/errors/all-recipients-failed): A personalized send accepted no recipients on any route allowed by delivery policy. - [middleware_error](https://email-sdk.dev/docs/reference/errors/middleware-error): Plugin middleware threw while preparing a send or handling its outcome. - [aborted](https://email-sdk.dev/docs/reference/errors/aborted): An AbortSignal stopped active adapter work or retry backoff and cancelled the remaining route. ## Provider comparisons Per-pair message field support, fallback compatibility, and adapter code for both providers. Append `.md` to any comparison URL (for example https://email-sdk.dev/compare/resend-vs-postmark.md) to fetch the same page as raw markdown. - [All provider comparisons](https://email-sdk.dev/compare) - [Resend vs Postmark](https://email-sdk.dev/compare/resend-vs-postmark) - [Resend vs SendGrid](https://email-sdk.dev/compare/resend-vs-sendgrid) - [Resend vs AWS SES](https://email-sdk.dev/compare/resend-vs-ses) - [Resend vs Mailgun](https://email-sdk.dev/compare/resend-vs-mailgun) - [Resend vs Loops](https://email-sdk.dev/compare/resend-vs-loops) - [Resend vs MailerSend](https://email-sdk.dev/compare/resend-vs-mailersend) - [Postmark vs SendGrid](https://email-sdk.dev/compare/postmark-vs-sendgrid) - [Postmark vs Mailgun](https://email-sdk.dev/compare/postmark-vs-mailgun) - [Postmark vs AWS SES](https://email-sdk.dev/compare/postmark-vs-ses) - [SendGrid vs Mailgun](https://email-sdk.dev/compare/sendgrid-vs-mailgun) - [SendGrid vs AWS SES](https://email-sdk.dev/compare/sendgrid-vs-ses) - [SendGrid vs Brevo](https://email-sdk.dev/compare/sendgrid-vs-brevo) - [Mailgun vs AWS SES](https://email-sdk.dev/compare/mailgun-vs-ses) - [Brevo vs MailerSend](https://email-sdk.dev/compare/brevo-vs-mailersend) - [MailerSend vs AWS SES](https://email-sdk.dev/compare/mailersend-vs-ses) ## Blog posts Append `.md` to any post URL (for example https://email-sdk.dev/blog/email-sdk-v1-safer-typescript-transactional-email.md) to fetch the same post as raw markdown. - [Email SDK v1: A Safer TypeScript API for Transactional Email](https://email-sdk.dev/blog/email-sdk-v1-safer-typescript-transactional-email): Switching transactional email providers looks like an import change. Preserving behavior across failures and uncertain delivery is the difficult part. - [Three New Adapters, a Security Patch, and a New License: Email SDK Week in Review](https://email-sdk.dev/blog/three-new-adapters-security-patch-new-license-email-sdk-week-in-review): It has been a busy week for Email SDK. Versions 0.6.2 through 0.6.5 shipped in rapid succession, bringing three brand-new provider adapters, a critical… ## Tools - [Email DNS checker](https://email-sdk.dev/tools/email-dns-checker): look up the SPF, DKIM, DMARC, and MX records of a sending domain. - [All tools](https://email-sdk.dev/tools) ## Machine-readable entry points - [Agent guide](https://email-sdk.dev/agents.md): install, send, and agent tool usage in one page. - [Authentication model](https://email-sdk.dev/auth.md): why there is no platform credential, and where provider credentials live. - [Agent discovery](https://email-sdk.dev/.well-known/agent.json) and [skill descriptor](https://email-sdk.dev/.well-known/agent-skills). - [Every documentation and comparison page inlined](https://email-sdk.dev/llms-full.txt) and [documentation-only index](https://email-sdk.dev/docs/llms.txt). - [Schema map](https://email-sdk.dev/schemamap.xml) with the [content schema feed](https://email-sdk.dev/feeds/docs.jsonl): schema.org entities for documentation, comparisons, and blog posts, for natural-language retrieval. - [Blog](https://email-sdk.dev/blog) with [RSS](https://email-sdk.dev/rss.xml) and [JSON Feed](https://email-sdk.dev/feed.json).