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

# Troubleshooting

> Fix common BosonMail SDK problems: ESM imports, missing globals, validation errors, timeouts, attachment issues, and delivery questions.

This page lists common problems you may encounter when installing, configuring, or running the BosonMail SDK, together with their causes and fixes.

> [accordion] ERR\_REQUIRE\_ESM / Cannot use import statement outside a module
>
> The package is ESM-only. CommonJS `require()` will fail.
>
> **Fix**: use dynamic import in CommonJS:
>
> ```javascript theme={null}
> const { default: BosonMailClient } = await import("@bosonware-ent/bosonmail");
> ```
>
> Or convert your project to ESM by adding `"type": "module"` to `package.json`.

> [accordion] fetch / FormData / Blob / AbortController is not defined
>
> These globals are required by the SDK. They are native in Node.js 18+.
>
> **Fix**: upgrade to Node.js 18 or newer. The SDK has zero runtime dependencies and does not polyfill these APIs.

> [accordion] 'apiKey' must be a non-empty string
>
> The constructor received an empty, missing, or whitespace-only API key.
>
> **Causes and fixes**:
>
> * The environment variable is not loaded. Ensure `BOSONMAIL_API_KEY` is set before the process starts.
> * In Next.js, do not use `NEXT_PUBLIC_BOSONMAIL_API_KEY`. That prefix exposes the value to the browser bundle. Use a server-only variable instead.
> * In Cloudflare Workers, read the key from `c.env.BOSONMAIL_API_KEY` inside the handler, not from `process.env`.

> [accordion] 401 / unauthorized
>
> The API rejected the authentication header.
>
> **Fix**: verify the API key is correct, has not expired, and has the required scope. If you recently rotated keys, ensure the new key is deployed everywhere. Contact [support@bosonware.com](mailto:support@bosonware.com) if the key should be valid.

> [accordion] Request timed out after 30000ms
>
> The server did not respond within the configured timeout.
>
> **Fix**: the timeout message warns that the outcome may be unknown. Do not auto-retry blindly. Instead:
>
> 1. If you have a `messageId`, call `getEmailStatus` to check whether the message was accepted.
> 2. If you do not have a `messageId`, log the failure for manual review.
> 3. Only resend after confirming the previous attempt did not succeed, accepting the small risk of duplication.

> [accordion] Email must contain text or HTML content
>
> The `body` argument did not include a non-empty `text` or `html` field.
>
> **Fix**: provide at least one of the two. For best client compatibility, provide both.
>
> ```typescript theme={null}
> await client.sendEmail("to@example.com", "Subject", {
>   text: "Plain text version",
>   html: "<p>HTML version</p>",
> });
> ```

> [accordion] Invalid content for attachment
>
> The attachment `content` is not a `Blob`, `ArrayBuffer`, or `Uint8Array`.
>
> **Common mistake**: passing a string, a `fs.ReadStream`, or a base64 string directly.
>
> **Fix**: read the file into a `Buffer` first.
>
> ```typescript theme={null}
> import { readFileSync } from "fs";
> const content = readFileSync("./invoice.pdf");
> // content is a Buffer, which is a Uint8Array subclass
> ```

> [accordion] Attachment exceeds size limits
>
> Individual attachments are limited to 10 MB, and the total payload to 20 MB.
>
> **Fix**: compress files, split large payloads across multiple emails, or host large files externally and link to them in the HTML body.

> [accordion] sendEmail succeeded but the recipient never received the email
>
> A successful `sendEmail` result means the API accepted the message. It does not mean the message was delivered.
>
> **Fix**:
>
> 1. Call `getEmailStatus` with the `messageId` to track the delivery pipeline.
> 2. Ask the recipient to check spam or junk folders.
> 3. Verify the recipient address is correct.
> 4. If the status is `failed`, `bounced`, or `rejected`, review the error details and correct the request.

> [accordion] messageId is undefined in the result
>
> The API response did not include a `messageId`, `emailId`, or `message_id` field.
>
> **Fix**: this is rare but possible. You cannot look up status without a message ID. Log the `id` field if present, and contact [support@bosonware.com](mailto:support@bosonware.com) with the timestamp and response details.

> [accordion] getEmailStatus returns not\_found
>
> The API could not locate an email for the provided message ID.
>
> **Fix**: confirm the message ID is correct and from the same account. Old messages may be purged. If the ID is recent and correct, contact [support@bosonware.com](mailto:support@bosonware.com).

> [accordion] getEmailStatus returns invalid\_response
>
> The API response is missing required fields such as `id`, `status`, or `delivery_status`.
>
> **Fix**: this indicates an unexpected API response shape. Report it to [support@bosonware.com](mailto:support@bosonware.com) with the message ID, SDK version, and timestamp. Do not retry blindly.

> [accordion] JSON send issues on SDK 0.2.0
>
> Version 0.2.0 sent `to`, `cc`, and `bcc` as arrays in JSON requests. Version 0.2.1 fixed this to send comma-separated strings.
>
> **Fix**: upgrade to `@bosonware-ent/bosonmail@0.2.1` or later.
>
> ```bash theme={null}
> npm install @bosonware-ent/bosonmail@latest
> ```

> [accordion] Content-Type manually set breaking multipart
>
> If you call the API directly and set `Content-Type: multipart/form-data` manually without a boundary, the server cannot parse the body.
>
> **Fix**: let the HTTP client set the multipart header automatically. When using `fetch` with `FormData`, do not set `Content-Type` at all.

## Contacting support

When you open a support request, include:

* SDK version (for example, 0.2.1)
* Runtime and version (Node.js 20, Bun 1.1, etc.)
* `statusCode` and `errorMessage` from the result
* `messageId` if available
* Timestamp of the request (with timezone)

Never include your API key in support emails or public forums.

## Next steps

> [card] [Error codes](https://docs.bosonware.com/advanced/error-codes.md)
>
> Complete catalog of every error code and message.

> [card] [Security best practices](https://docs.bosonware.com/advanced/security.md)
>
> Prevent credential leaks and secure your integration.

> [card] [Request and response formats](https://docs.bosonware.com/advanced/request-response-formats.md)
>
> Understand how the SDK builds requests and parses responses.

> [card] [Support](https://docs.bosonware.com/resources/support.md)
>
> Reach BosonWare support with the details above.


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