Client reference

Exact construction options, methods, routing helpers, validation results, and send results for the v1 client.

`createEmailClient(options)`

Construction is synchronous and requires at least one adapter after plugins register their routes.

types.ts

type EmailClientOptions<Adapters, Plugins> = {
  adapters?: Adapters;
  defaultAdapter?: Adapters[number]["name"];
  fallback?: EmailFallbackConfig<Adapters[number]["name"]>;
  retry?: EmailRetryConfig;
  hooks?: EmailHooks;
  plugins?: Plugins;
  telemetry?: boolean;
};

Option	Default	Behavior
`adapters`	`[]`	Literal-named adapter routes. Plugins may add routes.
`defaultAdapter`	First registered adapter	Primary route for operations without an override.
`fallback`	No fallback	Candidate adapters and unknown-delivery policy.
`retry`	`{ maxAttempts: 1 }`	Client-level retry policy.
`hooks`	None	Best-effort lifecycle observers.
`plugins`	`[]`	Synchronous route, hook, middleware, and extension composition.
`telemetry`	`true`	Anonymous SDK analytics unless an environment opt-out applies.

Duplicate adapter names, duplicate plugin ids, unknown default/fallback names, maxAttempts < 1, async plugin adapters, and extension-key collisions throw during construction.

Client properties

types.ts

readonly adapters: ReadonlyMap<RouteName, EmailAdapter>;
readonly defaultAdapter: RouteName;

`validate(message, options?)`

Runs common message, route, capability, adapter-specific, schedule, and personalized checks without calling an adapter's send method.

types.ts

type EmailValidationResult<Name extends string> = {
  adapter: Name;
  warnings: readonly { code: string; message: string }[];
};

Built-in validation currently returns an empty warnings array on success.

`send(message, options?)`

types.ts

type EmailSendOptions<Name extends string> = {
  adapter?: Name;
  fallback?: {
    adapters: readonly Name[];
    onUnknownDelivery?: "stop" | "continue";
  };
  retry?: {
    maxAttempts?: number;
    delay?: (attempt: number, error: EmailSdkError) => number;
    shouldRetry?: (error: EmailSdkError, attempt: number) => boolean;
  };
  signal?: AbortSignal;
  idempotencyKey?: string;
  metadata?: EmailSendMetadata;
};

Per-send retry and fallback objects replace the client objects. adapter selects the primary route. metadata is lifecycle context, separate from provider-facing message.metadata. The SDK passes it unchanged to hooks, plugins, and adapter contexts.

By default EmailSendMetadata is EmailMetadataRecord: strings, numbers, booleans, null, undefined, Date, and arrays or plain objects of those. To give it your own shape, augment EmailMetadataRegister once in your app:

email-metadata.d.ts

// The import makes this file a module, so the block below augments the SDK types instead of replacing them.
import "@opencoredev/email-sdk";

declare module "@opencoredev/email-sdk" {
  interface EmailMetadataRegister {
    metadata: { tenantId: string; traceId?: string };
  }
}

After that, send() requires that shape and hooks read event.metadata?.tenantId as a string.

types.ts

type EmailSendResult<Name extends string = string, Raw = unknown> = {
  adapter: Name;
  id?: string;
  accepted?: readonly string[];
  rejected?: readonly string[];
  raw?: Raw;
};

`sendMany(items, options?)`

types.ts

type EmailSendItem<Name extends string> = {
  message: EmailMessage;
  options?: EmailSendOptions<Name>;
};

type EmailSendSettledResult<Name extends string> =
  | { ok: true; index: number; result: EmailSendResult<Name> }
  | { ok: false; index: number; error: EmailSdkError };

Items run sequentially in input order. Item options shallowly override method options. The method always returns one settled result per item.

`sendPersonalized(input, options?)`

types.ts

type EmailPersonalizedInput = {
  message: Omit<EmailMessage, "to" | "cc" | "bcc">;
  recipients: readonly {
    to: EmailAddress;
    variables: Readonly<Record<string, string | number | boolean>>;
  }[];
};

At least one accepted recipient resolves with accepted and rejected. Zero accepted recipients throws EmailAllRecipientsFailedError.

`adapter(name)`

Returns the exact adapter type for a registered literal name. Unknown runtime names throw EmailAdapterNotFoundError.

`withAdapter(name)`

Returns validate, send, sendMany, and sendPersonalized bound to one adapter.

src/email.ts

const backup = email.withAdapter("backup");
await backup.send(message);

`flush()`

Waits for in-flight opt-out telemetry and never rejects. Serverless runtimes freeze the process on response and drop those requests, so await this (or pass it to waitUntil) before a handler returns. Long-running servers do not need it, and it resolves immediately when telemetry is disabled.

app/api/send/route.ts

await email.send(message);
waitUntil(email.flush());

Message reference

Look up every normalized message field.

Error reference

Handle the closed v1 error union.

Message reference

Error reference

On this page