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

# Quickstart

> Send your first transactional email with the BosonMail SDK in minutes. Covers installation, environment setup, sending, and status lookup.

This guide takes you from a blank project to a sent email and a status lookup in a few steps.

**1. Get an API key**

You need a BosonMail API key to send email. Log in to your BosonMail account and generate a key with permission to send email.

> [!WARNING]
>
> The exact steps to create or obtain an API key are not yet documented by BosonWare. Contact [support@bosonware.com](mailto:support@bosonware.com) for guidance.

**2. Install the SDK**

Install the package with npm, Bun, pnpm, or Yarn. The SDK is ESM-only and requires Node.js 18+.

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

See [Installation](https://docs.bosonware.com/installation.md) for TypeScript setup and CommonJS workarounds.

**3. Set your environment variable**

Create a `.env` file in your project root and add your API key.

```bash .env theme={null}
BOSONMAIL_API_KEY=your_api_key
```

For Node.js 20.6 and newer, load it automatically when you run your script:

```bash theme={null}
node --env-file=.env send.mjs
```

Bun loads `.env` automatically by default.

**4. Write and run the send script**

Create a file that sends a plain-text email and prints the result.

```typescript send.ts theme={null}
import BosonMailClient from "@bosonware-ent/bosonmail";

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

const result = await client.sendEmail(
  "customer@example.com",
  "Your order has shipped",
  {
    text: "Hi there. Your order #12345 has shipped and is on its way.",
  }
);

if (result.success) {
  console.log("Accepted:", result.messageId, "Status:", result.status);
} else {
  console.error("Failed:", result.errorMessage, "HTTP", result.statusCode);
  process.exit(1);
}
```

```javascript send.mjs theme={null}
import BosonMailClient from "@bosonware-ent/bosonmail";

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

const result = await client.sendEmail(
  "customer@example.com",
  "Your order has shipped",
  {
    text: "Hi there. Your order #12345 has shipped and is on its way.",
  }
);

if (result.success) {
  console.log("Accepted:", result.messageId, "Status:", result.status);
} else {
  console.error("Failed:", result.errorMessage, "HTTP", result.statusCode);
  process.exit(1);
}
```

Run it:

```bash TypeScript theme={null}
npx tsx send.ts
```

```bash JavaScript (Node 20.6+) theme={null}
node --env-file=.env send.mjs
```

```bash Bun theme={null}
bun send.ts
```

**5. Check the email status**

If `result.success` is true and `result.messageId` is present, you can look up the delivery state.

```typescript status.ts theme={null}
import BosonMailClient from "@bosonware-ent/bosonmail";

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

const status = await client.getEmailStatus("msg_abc123");

if (status.success && status.data) {
  console.log("Status:", status.data.status);
  console.log("Delivery:", status.data.delivery_status);
} else {
  console.error("Lookup failed:", status.errorMessage, status.errorCode);
}
```

The `status` field is the current email state reported by BosonMail. The `delivery_status` reflects the delivery outcome from the receiving server. Values include `queued`, `sent`, `delivered`, `failed`, `bounced`, `rejected`, and `deferred`. The exact meaning and transition order depend on the BosonMail backend implementation.

## What the result means

A successful `sendEmail` response means BosonMail accepted the message for processing. The typical `status` is `"queued"`. It does not guarantee delivery. Persist `messageId` in your database so you can audit or retry later.

> [!NOTE]
>
> 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.` Do not blindly retry after a timeout. Log the attempt and reconcile manually, or accept a small duplicate risk if you choose to resend.

## Next steps

> [card] [Sending emails](https://docs.bosonware.com/sdk/sending-emails.md)
>
> Learn about recipients, CC, BCC, HTML content, and result handling.

> [card] [Email status](https://docs.bosonware.com/sdk/email-status.md)
>
> Poll for delivery, interpret statuses, and build audit trails.

> [card] [Attachments](https://docs.bosonware.com/sdk/attachments.md)
>
> Add files to your messages with size limits and content types.

> [card] [Next.js guide](https://docs.bosonware.com/guides/nextjs.md)
>
> Integrate BosonMail into API routes and server actions.


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