# Email SDK — Documentation

> Scoped index of the Email SDK documentation. For the full machine guide (overview, constraints, agent usage) see /llms.txt; for every page inlined see /llms-full.txt.

## Documentation

- [Email SDK](/docs): Send transactional email through 23 adapters with one typed TypeScript SDK.
- Get started
  - [Install](/docs/getting-started/install): Install the ESM-only SDK for Node.js 20+ or Bun 1.1+.
  - [Quickstart](/docs/getting-started/quickstart): Create a Resend client and send your first email.
  - [Provider credentials](/docs/getting-started/credentials): Configure adapter credentials in the server environment and verify required values with the CLI.
  - [Coding-agent skill](/docs/getting-started/agent-skill): Install dynamic Email SDK guidance for coding agents that integrate, review, or document the package.
- Adapters
  - [Adapters](/docs/adapters): Configure one of 22 provider API adapters or the built-in SMTP transport, 23 adapters total.
  - [Resend](/docs/adapters/resend): Send through the Resend API with attachments, tags, and native idempotency keys.
  - [Sequenzy](/docs/adapters/sequenzy): Send through the Sequenzy transactional API with metadata variables, template slugs, and URL or base64 attachments.
  - [JetEmail](/docs/adapters/jetemail): Send through the JetEmail transactional API with CC, BCC, reply-to, custom headers, base64 attachments, and idempotent retries.
  - [Primitive](/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](/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.
  - [Postmark](/docs/adapters/postmark): Send through the Postmark Email API with message streams, metadata, and Postmark's single-tag model.
  - [SendGrid](/docs/adapters/sendgrid): Send through the Twilio SendGrid Mail Send API with the fullest field support of any adapter.
  - [Cloudflare Email Sending](/docs/adapters/cloudflare): Send through Cloudflare's Email Sending REST API with plain-address recipients and a 50-recipient cap.
  - [Unosend](/docs/adapters/unosend): Send through the Unosend REST API, a single Bearer-authenticated endpoint with CC, BCC, tags, and attachments.
  - [AWS SES](/docs/adapters/ses): Send through the SES v2 SendEmail API with built-in SigV4 signing and no AWS SDK dependency.
  - [Mailgun](/docs/adapters/mailgun): Send through the Mailgun Messages API with domain-scoped multipart sends, h:/v:/o: field mapping, and full field support.
  - [MailerSend](/docs/adapters/mailersend): Send through the MailerSend Email API with cc/bcc, headers, tags, attachments, and a single reply-to address.
  - [Brevo](/docs/adapters/brevo): Send through the Brevo transactional email API with full field support and metadata mapped to template params.
  - [Mailchimp Transactional](/docs/adapters/mailchimp): Send through Mailchimp Transactional (Mandrill) with typed recipients, tags, and metadata, but no replyTo field.
  - [SparkPost](/docs/adapters/sparkpost): Send through the SparkPost Transmissions API with metadata, substitution data from tags, and a provider-side sandbox mode.
  - [Iterable](/docs/adapters/iterable): Trigger an Iterable campaign template for one recipient, with message content delivered as dataFields.
  - [Loops](/docs/adapters/loops): Trigger a published Loops transactional email for one recipient, with metadata delivered as dataVariables.
  - [Plunk](/docs/adapters/plunk): Send through the Plunk API with reply-to, headers, attachments, and metadata mapped to Plunk data.
  - [Mailtrap](/docs/adapters/mailtrap): Send through the Mailtrap Email Sending API with full field support and provider-side message inspection.
  - [Scaleway](/docs/adapters/scaleway): Send through Scaleway Transactional Email with region-scoped endpoints and header-based reply-to.
  - [ZeptoMail](/docs/adapters/zeptomail): Send through Zoho ZeptoMail with automatic send-mail token prefixing.
  - [MailPace](/docs/adapters/mailpace): Send through the MailPace API, a deliberately minimal adapter for address fields and body content.
  - [SMTP](/docs/adapters/smtp): Send over raw SMTP with the built-in TCP/TLS transport. No Nodemailer, no HTTP API.
  - [Field support](/docs/adapters/field-support): Source-derived support for normalized message fields across all built-in adapters.
  - [Delivery capabilities](/docs/adapters/capability-groups): Decide when an adapter can preserve repeated headers, idempotency, scheduled delivery, or personalized fanout.
  - [How adapters are tested](/docs/adapters/verification): See what Verified means and how adapter checks run.
- Concepts
  - [Adapters](/docs/concepts/adapter-model): How adapters turn one Email SDK message into a provider request.
  - [Retries and fallback](/docs/concepts/fallbacks-and-retries): Retry one provider, then decide when it is safe to try another.
  - [Hooks and middleware](/docs/concepts/hooks): Observe sends with hooks or change them with middleware.
  - [Sending modes](/docs/concepts/sending-modes): Pick the right method for batches, personalization, schedules, and idempotency.
- Plugins
  - [Plugin system](/docs/plugins): Transform send options, select routes, observe lifecycle events, enforce time bounds, and extend the typed client.
  - Built-in plugins
    - [Defaults plugin](/docs/plugins/built-in/defaults): Apply reply-to, headers, tags, metadata, send metadata, and idempotency defaults before validation.
    - [Routing plugin](/docs/plugins/built-in/routing): Select a registered adapter from the prepared message and send options before route validation.
    - [Timeout plugin](/docs/plugins/built-in/timeout): Bound one logical send, including retries and fallback, while preserving caller cancellation.
    - [Observability plugin](/docs/plugins/built-in/observability): Emit send, retry, and error events through isolated log, metric, and trace callbacks.
    - [Capture plugin](/docs/plugins/built-in/capture): Record lifecycle events in memory and expose the store through a typed client extension.
  - [Community plugins and adapters](/docs/plugins/community): Evaluate third-party Email SDK extensions without treating them as core-maintained integrations.
- UI
  - [Email UI](/docs/ui): Browse complete, email-safe templates by the job they need to do.
  - [Components](/docs/ui/components): The small set of email-safe primitives used by every template.
  - Account
    - [Verification code](/docs/ui/account/verification-code): A focused one-time code with a clear expiry.
    - [Password reset](/docs/ui/account/password-reset): A secure reset action with request context.
    - [Team invite](/docs/ui/account/team-invite): A personal invitation to join a workspace.
  - Product
    - [Welcome](/docs/ui/product/welcome): A useful first step after account creation.
    - [Trial ending](/docs/ui/product/trial-ending): An honest reminder before a trial expires.
    - [Usage alert](/docs/ui/product/usage-alert): A calm limit warning with a direct next action.
  - Commerce
    - [Receipt](/docs/ui/commerce/receipt): A compact payment confirmation and receipt link.
    - [Invoice due](/docs/ui/commerce/invoice-due): A clear invoice summary before payment is due.
    - [Refund confirmed](/docs/ui/commerce/refund-confirmed): A reassuring refund status with timing details.
- Integrations
  - Convex
    - [Convex](/docs/integrations/convex): Durable, provider-portable transactional email for Convex applications.
    - [Install and configure](/docs/integrations/convex/setup): Mount the Convex component, map provider secrets, create the server client, and set safe defaults.
    - [Send and track email](/docs/integrations/convex/sending-and-status): Queue email from Convex mutations, expose reactive status, and inspect the complete event timeline.
    - [Process webhooks](/docs/integrations/convex/webhooks): Verify provider webhook requests in application code and store normalized delivery events in the Convex component.
    - [Test and recover](/docs/integrations/convex/testing-and-recovery): Redirect recipients, use in-memory delivery, inspect failure history, cancel queued work, and retry terminal failures.
  - [Chat SDK](/docs/integrations/chat-sdk): Send transactional email from Chat SDK handlers while keeping identity, authorization, and delivery policy in application code.
  - [AI SDK](/docs/integrations/ai-sdk): Add one narrow, approval-gated sendEmail tool to a Vercel AI SDK agent.
- For agents
  - [Machine-readable Email SDK docs](/docs/agents): Give agents current Email SDK documentation without scraping rendered HTML.
  - [Machine-readable documentation](/docs/agents/machine-readable-docs): Use raw Markdown, LLM indexes, JSONL entities, and the schema map for agent retrieval.
- Guides
  - [Schedule an email](/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](/docs/guides/production-send-pipeline): Validate before queueing, preserve durable state, and use retries and fallback without hiding delivery uncertainty.
  - [Test email behavior](/docs/guides/test-email-behavior): Assert normalized messages, retries, fallback routes, and lifecycle events without sending real email.
  - [Troubleshoot failed sends](/docs/guides/troubleshoot-failed-sends): Diagnose failures by the exported error class, stable code, adapter, and delivery classification.
  - Migration guides
    - [Upgrade from Email SDK 0.x to v1](/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](/docs/guides/migrate/resend): Replace direct Resend calls with a typed Email SDK client while keeping Resend as the delivery adapter.
    - [Migrate from Nodemailer](/docs/guides/migrate/nodemailer): Replace a Nodemailer transporter with Email SDK's dependency-free SMTP adapter.
    - [Migrate from SendGrid](/docs/guides/migrate/sendgrid): Replace direct Mail Send payloads with normalized messages and explicit personalized sending.
  - Extend
    - [Create your first plugin](/docs/guides/authoring/create-first-plugin): Add typed middleware and a client extension without changing adapter behavior.
    - [Create an adapter](/docs/guides/authoring/create-adapter): Implement a literal route name, capabilities, no-network validation, sending, and typed failures.
    - [Publish a community plugin](/docs/guides/authoring/publish-community-plugin): Package a v1-compatible plugin with explicit peer versions, tests, and support documentation.
    - [Publish a community adapter](/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](/docs/reference/client): Exact construction options, methods, routing helpers, validation results, and send results for the v1 client.
  - [Message reference](/docs/reference/message): Exact v1 address, envelope, body, header, attachment, metadata, tag, and schedule types.
  - [Adapter contract](/docs/reference/adapter-contract): Exact v1 adapter capabilities, validation context, send context, personalized operation, and result contract.
  - [Plugin API](/docs/reference/plugin-api): Exact plugin context, hooks, middleware, adapter registration, and typed client extension contracts.
  - [Community registry](/docs/reference/community-registry): Static registry schema, trust labels, and validation for third-party adapters and plugins.
  - [Compatibility subpath](/docs/reference/compatibility): Temporary v0 source compatibility available only during the v1 major.
  - [Telemetry and privacy](/docs/reference/telemetry): Anonymous SDK and CLI analytics, redacted error reporting, storage, and opt-out behavior.
  - CLI commands
    - [CLI reference](/docs/reference/cli): Commands, runtime, aliases, telemetry, adapter detection, and exit behavior for the email-sdk binary.
    - [email-sdk adapters](/docs/reference/cli/adapters): List every bundled CLI adapter with required environment variables and provider notes.
    - [email-sdk doctor](/docs/reference/cli/doctor): Check whether required adapter configuration is present without authenticating to the provider.
    - [email-sdk send](/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](/docs/reference/errors): Closed v1 error codes, exported classes, retryability, delivery certainty, and route failure structure.
    - [validation_error](/docs/reference/errors/validation-error): The message, route, schedule, capability, or adapter-specific input is invalid before dispatch.
    - [adapter_not_found](/docs/reference/errors/adapter-not-found): A runtime route name does not match a registered adapter.
    - [adapter_error](/docs/reference/errors/adapter-error): One adapter or transport failed with explicit retryability and delivery certainty.
    - [route_error](/docs/reference/errors/route-error): Every attempted adapter route failed without producing a successful normalized result.
    - [all_recipients_failed](/docs/reference/errors/all-recipients-failed): A personalized send accepted no recipients on any route allowed by delivery policy.
    - [middleware_error](/docs/reference/errors/middleware-error): Plugin middleware threw while preparing a send or handling its outcome.
    - [aborted](/docs/reference/errors/aborted): An AbortSignal stopped active adapter work or retry backoff and cancelled the remaining route.