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

# Installation

> Install the official BosonMail SDK for Node.js and TypeScript via npm, Bun, pnpm, or Yarn. Requirements and troubleshooting included.

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

```bash npm theme={null}
npm install @bosonware-ent/bosonmail
```

```bash Bun theme={null}
bun add @bosonware-ent/bosonmail
```

```bash pnpm theme={null}
pnpm add @bosonware-ent/bosonmail
```

```bash Yarn theme={null}
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:

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}
```

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

```json tsconfig.json theme={null}
{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}
```

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

```json package.json theme={null}
{
  "type": "module",
  "dependencies": {
    "@bosonware-ent/bosonmail": "^0.2.1"
  }
}
```

## CommonJS workaround

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

```javascript commonjs.cjs theme={null}
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.

```typescript verify.ts theme={null}
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

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

## Next steps

> [card] [Quickstart](https://docs.bosonware.com/quickstart.md)
>
> Send your first email in under five minutes.

> [card] [Authentication](https://docs.bosonware.com/authentication.md)
>
> Set up your API key and Bearer token security.


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