Installation

Install the BosonMail SDK with your preferred package manager. The package is ESM-only and ships with its own TypeScript declarations, so no separate @types package is needed.

Package managers

npm install @bosonware-ent/bosonmail

bun add @bosonware-ent/bosonmail

pnpm add @bosonware-ent/bosonmail

yarn add @bosonware-ent/bosonmail

Requirements

Node.js 18 or newer (the SDK uses native fetch, FormData, Blob, and AbortController)
ESM module resolution (see TypeScript setup below)
A valid BosonMail API key

The SDK has zero runtime dependencies.

TypeScript setup

Because the package is ESM-only, your project must resolve it as an ES module. In tsconfig.json, use one of these combinations:

tsconfig.json

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

Or, if you are bundling with Vite, esbuild, or a similar tool:

tsconfig.json

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

For plain Node.js without a bundler, also set "type": "module" in your package.json:

package.json

{
  "type": "module",
  "dependencies": {
    "@bosonware-ent/bosonmail": "^0.2.1"
  }
}

CommonJS workaround

If your project uses CommonJS (require), dynamically import the default export:

commonjs.cjs

const { default: BosonMailClient } = await import("@bosonware-ent/bosonmail");

const client = new BosonMailClient({
  apiKey: process.env.BOSONMAIL_API_KEY,
});

Verify the installation

Create a small script that constructs the client and prints the base URL. If this runs without errors, the package is installed correctly.

verify.ts

import BosonMailClient from "@bosonware-ent/bosonmail";

const client = new BosonMailClient({
  apiKey: "your_api_key",
});

console.log(client.apiBaseUrl);
// Expected: https://webmail.bosonware.com/api/v1

Troubleshooting

ERR_REQUIRE_ESM

You are trying to require() an ESM-only package. Switch to import, add "type": "module" to package.json, or use the dynamic import workaround shown above.

fetch is not defined

Upgrade to Node.js 18 or newer. The SDK relies on the global fetch implementation and does not bundle a polyfill.

Cannot find module

Ensure your tsconfig.json uses "moduleResolution": "NodeNext" or "bundler", and that the package is listed in package.json dependencies. Delete node_modules and lockfiles and reinstall if needed.

Getting Started

SDK Reference

Guides

Advanced

Resources

Package managers

Requirements

TypeScript setup

CommonJS workaround

Verify the installation

Troubleshooting

Next steps

Quickstart

Authentication

​Package managers

​Requirements

​TypeScript setup

​CommonJS workaround

​Verify the installation

​Troubleshooting

​Next steps

Quickstart

Authentication

Package managers

Requirements

TypeScript setup

CommonJS workaround

Verify the installation

Troubleshooting

Next steps