> ## 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.

# Configuration

> Configure the BosonMail SDK with API keys, custom base URLs, timeouts, and environment-specific settings for production and development.

The BosonMail SDK is configured entirely through the constructor. There are no global settings, no config files, and no middleware. Create one client per API key and reuse it across your application.

## Constructor options

**apiKey** `string` *required*

Your BosonMail API key. The constructor throws if it is empty or whitespace-only.

**baseUrl** `string`

The BosonMail API base URL. Defaults to `https://webmail.bosonware.com/api/v1`. The constructor strips trailing slashes and validates that the value is an absolute HTTP(S) URL.

**timeoutMs** `number`

Request timeout in milliseconds. Defaults to `30000` (30 seconds). The constructor throws if the value is not a finite number greater than zero.

## 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 });

// Readonly properties
console.log(bosonmail.apiBaseUrl); // https://webmail.bosonware.com/api/v1
console.log(bosonmail.timeoutMs);  // 30000
```

## Per-environment configuration

Use different keys or base URLs for development, staging, and production. Never commit production credentials.

```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,
  baseUrl: process.env.BOSONMAIL_API_URL, // optional override
  timeoutMs: Number(process.env.BOSONMAIL_TIMEOUT_MS || 30000),
});
```

```bash .env.development theme={null}
BOSONMAIL_API_KEY=your_dev_key
BOSONMAIL_API_URL=https://staging.webmail.bosonware.com/api/v1
BOSONMAIL_TIMEOUT_MS=15000
```

```bash .env.production theme={null}
BOSONMAIL_API_KEY=your_prod_key
BOSONMAIL_TIMEOUT_MS=30000
```

## Choosing a timeout

The default 30 seconds is suitable for most transactional email sends, including multipart uploads with attachments. Consider a shorter timeout for health checks or high-volume loops where you want fast failure feedback. Consider a longer timeout only if you routinely send large attachments over slow links.

> [!NOTE]
>
> If a request times out, the SDK returns `success: false` with the message `Request timed out after <timeoutMs>ms. The outcome may be unknown; check email status before retrying.` The server may have accepted the message even though the client did not receive the response.

## Validating configuration at startup

Because the constructor throws for invalid input, initializing the client during application startup is a reliable way to fail fast on misconfiguration.

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

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

  const timeoutMs = Number(process.env.BOSONMAIL_TIMEOUT_MS || 30000);
  const client = new BosonMailClient({ apiKey, timeoutMs });

  console.log(`Email client ready: ${client.apiBaseUrl} (timeout ${client.timeoutMs}ms)`);
  return client;
}

export const bosonmail = createEmailClient();
```

## Common configuration mistakes

> [accordion] Empty or missing apiKey
>
> The constructor throws `Error("'apiKey' must be a non-empty string")`. Guard the environment variable before constructing the client.

> [accordion] Invalid baseUrl
>
> The constructor throws `Error("'baseUrl' must be an absolute HTTP(S) URL")` if the value does not start with `http://` or `https://`. It also throws `Error("'baseUrl' must be a non-empty URL")` if the trimmed value is empty.

> [accordion] Invalid timeoutMs
>
> The constructor throws `Error("'timeoutMs' must be a positive number")` if the value is not a finite number greater than zero.

## Next steps

> [card] [Client reference](https://docs.bosonware.com/sdk/client-configuration.md)
>
> Detailed constructor behavior, properties, and option types.

> [card] [Authentication](https://docs.bosonware.com/authentication.md)
>
> API keys, Bearer tokens, and security best practices.

> [card] [Sending emails](https://docs.bosonware.com/sdk/sending-emails.md)
>
> How to send text and HTML messages with the configured client.

> [card] [Error handling](https://docs.bosonware.com/sdk/error-handling.md)
>
> Interpret failure results and decide when to retry.


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