# Client (/docs/v/0.5.0/reference/client)



## `createEmailClient(options)` [#createemailclientoptions]

Creates an email client.

```ts
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?)` [#emailsendmessage-options]

Sends one message.

```ts
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 [#execution-order]

For one send, Email SDK:

1. Runs before-send middleware.
2. Validates the normalized message.
3. Builds the route order from the selected adapter and fallback adapters.
4. Tries the selected adapter.
5. Retries that adapter when retry rules allow it.
6. Moves to the next fallback adapter after final failure.
7. Returns the first successful response.
8. Throws if every route fails.

`provider` and `fallbackProviders` are compatibility aliases only. Prefer `adapter` and `fallbackAdapters` in new code.

## `email.sendBatch(messages, options?)` [#emailsendbatchmessages-options]

Sends messages one at a time and returns one result per item.

```ts
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)` [#emailadaptername]

Returns a registered adapter or throws `EmailProviderNotFoundError`.

```ts
const resendAdapter = email.adapter("resend");
```

`email.provider(name)` is kept as an alias.

## `email.withAdapter(name)` [#emailwithadaptername]

Returns a small client bound to one adapter.

```ts
const transactional = email.withAdapter("postmark");

await transactional.send(message);
```

`email.withProvider(name)` is kept as an alias.