> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bosonware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client configuration

> Configure the BosonMailClient with apiKey, baseUrl, and timeoutMs. Learn defaults, validation rules, and timeout behavior.

You configure the BosonMail SDK when you construct `BosonMailClient`. All settings are passed through the `BosonMailClientOptions` object. The constructor validates every option immediately and throws descriptive errors for invalid input.

## BosonMailClientOptions

**apiKey** `string` *required*

Your BosonMail API key. Must be a non-empty string after trimming. Keep this in an environment variable or secrets manager, never in source control.

**baseUrl** `string`

The API base URL. Defaults to `https://webmail.bosonware.com/api/v1`. Must be an absolute URL starting with `http://` or `https://`.

**timeoutMs** `number`

Per-request timeout in milliseconds. Defaults to `30000` (30 seconds). Must be a finite number greater than `0`.

## Defaults and normalization

| Option | Default | Normalization |
| - | - | - |
| `apiKey` | none (required) | trimmed |
| `baseUrl` | `https://webmail.bosonware.com/api/v1` | trimmed, trailing slashes stripped |
| `timeoutMs` | `30000` | used as-is after validation |

The normalized `baseUrl` is stored on `client.apiBaseUrl`. The original `apiKey` is stored on `client.apiKey` (trimmed but otherwise unchanged).

## Constructor errors

The constructor throws `Error` with the following exact messages:

| Condition | Error message |
| - | - |
| `apiKey` missing or empty after trim | `'apiKey' must be a non-empty string` |
| `timeoutMs` not a finite number > 0 | `'timeoutMs' must be a positive number` |
| `baseUrl` empty after trim | `'baseUrl' must be a non-empty URL` |
| `baseUrl` not absolute HTTP(S) | `'baseUrl' must be an absolute HTTP(S) URL` |

These are the only errors the SDK throws. Every other failure is returned as a result object.

## Examples

### Default configuration

```typescript lib/bosonmail.ts theme={null}
import BosonMailClient from "@bosonware-ent/bosonmail";

const apiKey = process.env.BOSONMAIL_API_KEY;
if (!apiKey) throw new Error("BOSONMAIL_API_KEY is not set");

export const bosonmail = new BosonMailClient({ apiKey });
```

### Custom timeout

Use a shorter timeout for latency-sensitive paths, or a longer one when sending large attachments:

```typescript theme={null}
const bosonmail = new BosonMailClient({
  apiKey: process.env.BOSONMAIL_API_KEY!,
  timeoutMs: 10_000, // 10 seconds
});
```

### Custom base URL

Point to a staging environment or a self-hosted BosonMail instance:

```typescript theme={null}
const bosonmail = new BosonMailClient({
  apiKey: process.env.BOSONMAIL_API_KEY!,
  baseUrl: "https://staging.webmail.example.com/api/v1",
});
```

## Timeout behavior

Every request uses an `AbortController` with a `setTimeout` equal to `timeoutMs`. If the timer fires before the response arrives, the request is aborted and the method resolves with:

```typescript theme={null}
{
  success: false,
  errorMessage: "Request timed out after <timeoutMs>ms. The outcome may be unknown; check email status before retrying."
}
```

> [!WARNING]
>
> A timeout is ambiguous. The server may have accepted the email even though the client never received the response. Before retrying, check the email status if you have a message ID, or log the timeout for manual reconciliation. Blind retries risk duplicates.

> [card] [BosonMailClient](https://docs.bosonware.com/sdk/client.md)
>
> Class overview, methods, and exported types.

> [card] [Sending emails](https://docs.bosonware.com/sdk/sending-emails.md)
>
> Full sendEmail reference with parameters and examples.

> [card] [Error handling](https://docs.bosonware.com/sdk/error-handling.md)
>
> How to classify and respond to every kind of SDK error.

> [card] [Authentication](https://docs.bosonware.com/authentication.md)
>
> How to obtain and store your API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.