Configuration

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

string

required

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

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.

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

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

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

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

.env.development

BOSONMAIL_API_KEY=your_dev_key
BOSONMAIL_API_URL=https://staging.webmail.bosonware.com/api/v1
BOSONMAIL_TIMEOUT_MS=15000

.env.production

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.

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.

server.ts

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

Empty or missing apiKey

The constructor throws Error("'apiKey' must be a non-empty string"). Guard the environment variable before constructing the client.

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.

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

Client reference

Detailed constructor behavior, properties, and option types.

Authentication

API keys, Bearer tokens, and security best practices.

Sending emails

How to send text and HTML messages with the configured client.

Error handling

Interpret failure results and decide when to retry.

Getting Started

SDK Reference

Guides

Advanced

Resources

Constructor options

Default configuration

Per-environment configuration

Choosing a timeout

Validating configuration at startup

Common configuration mistakes

Next steps

Client reference

Authentication

Sending emails

Error handling

​Constructor options

​Default configuration

​Per-environment configuration

​Choosing a timeout

​Validating configuration at startup

​Common configuration mistakes

​Next steps

Client reference

Authentication

Sending emails

Error handling

Constructor options

Default configuration

Per-environment configuration

Choosing a timeout

Validating configuration at startup

Common configuration mistakes

Next steps