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

# Security best practices

> Secure your BosonMail integration: server-side key storage, PII handling, input sanitization, attachment safety, and dependency hygiene.

BosonMail handles business email, which often includes sensitive content and recipient data. This page covers practical steps to keep your integration secure.

## Server-side only

The BosonMail SDK is designed for server-side use. Never expose API keys in browser bundles, mobile apps, or client-side JavaScript.

> [!WARNING]
>
> Do not prefix environment variables with `NEXT_PUBLIC_`, `VITE_`, `REACT_APP_`, or similar. Those prefixes embed values into client-side code. Use a server-only variable such as `BOSONMAIL_API_KEY`.

If you need to send email from a browser form, submit the form to your own backend, validate it, and call the SDK server-side.

## Secret storage

Store API keys in environment variables or a dedicated secrets manager. Validate the key at startup and fail fast if it is missing.

```typescript lib/bosonmail.ts theme={null}
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 });
```

For platform-specific guidance, see [Authentication and API keys](https://docs.bosonware.com/advanced/api-keys.md).

## Do not log credentials

The `BosonMailClient` instance exposes `apiKey` as a readonly public property. Avoid logging the client object directly, or redact the key first.

```typescript theme={null}
// Bad: may leak the key into logs
console.log(client);

// Good: log only safe metadata
console.log({ baseUrl: client.apiBaseUrl, timeout: client.timeoutMs });
```

Also avoid logging email content, recipient lists, and attachment filenames at `info` level. Treat them as sensitive data.

## Prevent open relay

If your application accepts user input to determine the recipient or content of an email, protect against abuse:

* **Authenticate send endpoints**: only signed-in or authorized users should trigger emails.
* **Fix the recipient server-side**: for contact forms, do not let the user supply the `to` address. Hardcode it or map it from a trusted identifier.
* **Rate limit**: apply per-user or per-IP rate limits on endpoints that send email.
* **Use CAPTCHA** on public forms to reduce automated abuse.

## Sanitize user input

The SDK passes `subject` through as-is after trimming. Escape or strip user-supplied content before placing it in HTML bodies or subjects.

```typescript theme={null}
function escapeHtml(text: string): string {
  return text
    .replace(/&/g, "&")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;");
}

const userName = escapeHtml(untrustedInput);
const html = `<p>Hello ${userName}</p>`;
```

As defense in depth, strip newline characters from user-supplied subjects to prevent header injection.

## Attachment safety

* Validate file types and sizes in your application before passing them to the SDK.
* Reject executable file types (`.exe`, `.bat`, `.sh`) at the application layer.
* Scan attachments with an antivirus or content scanner if your use case requires it.
* The SDK enforces a 10 MB per-file and 20 MB total limit, but application-level checks should run first.

## HTTPS only

The SDK requires `baseUrl` to be an absolute HTTP(S) URL. Always use `https://` in production. The default base URL is `https://webmail.bosonware.com/api/v1`.

## Dependency hygiene

The BosonMail SDK has zero runtime dependencies, which reduces supply-chain risk. Still, follow these practices:

* Pin the SDK version in `package.json` and use lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`).
* Run `npm audit` regularly.
* Verify the package name exactly: `@bosonware-ent/bosonmail`. Typosquatting is a real risk.
* Upgrade promptly when security fixes are released. See the [Changelog](https://docs.bosonware.com/resources/changelog.md) for release notes.

## Incident response

If you suspect a key leak or unauthorized usage:

1. Revoke the key immediately via the dashboard or by contacting [support@bosonware.com](mailto:support@bosonware.com).
2. Rotate to a new key.
3. Audit recent sends and status checks for unexpected recipients or content.
4. Review application logs for signs of injection or abuse.

## Legal and privacy

* [BosonWare Terms of Service](https://bosonware.com/terms)
* [BosonWare Privacy Policy](https://bosonware.com/privacy)
* [BosonWare SLA](https://bosonware.com/sla)

## Next steps

> [card] [Authentication and API keys](https://docs.bosonware.com/advanced/api-keys.md)
>
> Key scopes, storage, rotation, and leak response.

> [card] [Troubleshooting](https://docs.bosonware.com/advanced/troubleshooting.md)
>
> Fix common runtime and configuration issues.

> [card] [Error codes](https://docs.bosonware.com/advanced/error-codes.md)
>
> Understand every error the SDK can return.

> [card] [Production best practices](https://docs.bosonware.com/guides/production-best-practices.md)
>
> Queues, retries, and safe sending patterns at scale.


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