Client
Reference for createEmailClient, send, sendBatch, and adapter helpers.
createEmailClient(options)
Creates an email client.
const email = createEmailClient({
adapters,
defaultAdapter,
fallback,
retry,
hooks,
plugins,
});| Option | Type | Default |
|---|---|---|
adapters | EmailProvider[] | [] |
providers | EmailProvider[] | Alias for adapters |
defaultAdapter | string | First adapter |
defaultProvider | string | First adapter |
fallback | string[] | [] |
retry | EmailRetryConfig | No retries |
hooks | EmailHooks | No hooks |
plugins | EmailPlugin[] | [] |
Routing names must be unique. At least one adapter must be registered directly or through a plugin.
fallback is an ordered list of adapter routing names tried after the selected adapter fails. retry applies inside the current adapter before Email SDK advances to a fallback route.
email.send(message, options?)
Sends one message.
const result = await email.send(message, {
adapter: "resend",
fallbackAdapters: ["smtp"],
retries: 2,
idempotencyKey: "receipt:order_123",
metadata: {
route: "checkout.receipt",
},
});| Option | Type | Notes |
|---|---|---|
adapter | string | Override the default routing name. |
provider | string | Alias for adapter. |
fallbackAdapters | string[] | Replace client-level fallback for this send. Pass [] for no fallback. |
fallbackProviders | string[] | Alias for fallbackAdapters. |
retries | number | Replace client-level retry count for this send. |
signal | AbortSignal | Abort provider work when supported. |
idempotencyKey | string | Passed to adapters that support it. |
metadata | Record<string, unknown> | Passed to hooks. |
Execution order
For one send, Email SDK:
- Runs before-send middleware.
- Validates the normalized message.
- Builds the route order from the selected adapter and fallback adapters.
- Tries the selected adapter.
- Retries that adapter when retry rules allow it.
- Moves to the next fallback adapter after final failure.
- Returns the first successful response.
- Throws if every route fails.
provider and fallbackProviders are compatibility aliases only. Prefer adapter and fallbackAdapters in new code.
email.sendBatch(messages, options?)
Sends messages one at a time and returns one result per item.
const results = await email.sendBatch([messageA, messageB]);sendBatch does not throw for the first failed item. Failed sends are returned as { ok: false, index, error }.
email.adapter(name)
Returns a registered adapter or throws EmailProviderNotFoundError.
const resendAdapter = email.adapter("resend");email.provider(name) is kept as an alias.
email.withAdapter(name)
Returns a small client bound to one adapter.
const transactional = email.withAdapter("postmark");
await transactional.send(message);email.withProvider(name) is kept as an alias.