Client configuration

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

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.

string

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

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

lib/bosonmail.ts

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:

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:

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:

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

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.

BosonMailClient

Class overview, methods, and exported types.

Sending emails

Full sendEmail reference with parameters and examples.

Error handling

How to classify and respond to every kind of SDK error.

Authentication

How to obtain and store your API key.

Getting Started

SDK Reference

Guides

Advanced

Resources

BosonMailClientOptions

Defaults and normalization

Constructor errors

Examples

Default configuration

Custom timeout

Custom base URL

Timeout behavior

BosonMailClient

Sending emails

Error handling

Authentication

​BosonMailClientOptions

​Defaults and normalization

​Constructor errors

​Examples

​Default configuration

​Custom timeout

​Custom base URL

​Timeout behavior

BosonMailClient

Sending emails

Error handling

Authentication

BosonMailClientOptions

Defaults and normalization

Constructor errors

Examples

Default configuration

Custom timeout

Custom base URL

Timeout behavior