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

# Sending your first email

> Set up a new Node.js project, install the BosonMail SDK, and send your first email with full error handling and status checking.

This guide walks you through creating a fresh Node.js project from an empty folder, installing the BosonMail SDK, and sending your first email. You will write a complete script with error handling, check the submission status, and learn how to interpret the response.

## Prerequisites

You need Node.js 18 or newer because the SDK uses native `fetch`, `FormData`, `Blob`, and `AbortController`. You also need a BosonMail API key with email sending permission. If you do not have one yet, sign up at [BosonMail](https://bosonware.com/products/bosonmail) and contact [support@bosonware.com](mailto:support@bosonware.com) for API key provisioning steps.

**1. Initialize the project**

Create a new folder and initialize it as an ESM Node.js project.

```bash theme={null}
mkdir bosonmail-first-email
cd bosonmail-first-email
npm init -y
```

Open `package.json` and add `"type": "module"` so Node.js treats `.js` and `.ts` files as ESM:

```json package.json theme={null}
{
  "name": "bosonmail-first-email",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "send": "tsx src/send.ts"
  }
}
```

**2. Install the SDK and dev tools**

Install the BosonMail SDK, TypeScript, and `tsx` for running TypeScript without compiling.

```bash theme={null}
npm install @bosonware-ent/bosonmail
npm install --save-dev typescript tsx @types/node
```

Generate a basic `tsconfig.json`:

```bash theme={null}
npx tsc --init
```

**3. Configure environment variables**

Create a `.env` file to store your API key outside source control.

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

Create a `.gitignore` file so the key is never committed.

```text .gitignore theme={null}
node_modules/
.env
dist/
*.log
```

> [!WARNING]
>
> Never commit API keys to version control. Treat `.env` as sensitive and share keys only through a secrets manager.

**4. Write the sender script**

Create `src/send.ts` with a shared client, full error handling, and a status check.

```typescript src/send.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");
}

const client = new BosonMailClient({ apiKey });

async function main() {
  const result = await client.sendEmail(
    "customer@example.com",
    "Welcome to BosonMail",
    { text: "This is your first email sent with the BosonMail SDK." }
  );

  if (!result.success) {
    console.error("Send failed:", result.errorMessage);
    console.error("HTTP status:", result.statusCode ?? "N/A");
    process.exit(1);
  }

  console.log("Email accepted");
  console.log("Message ID:", result.messageId);
  console.log("Status:", result.status);

  if (result.messageId) {
    const status = await client.getEmailStatus(result.messageId);
    if (status.success && status.data) {
      console.log("Current status:", status.data.status);
      console.log("Delivery status:", status.data.delivery_status);
    } else {
      console.error("Status check failed:", status.errorMessage);
    }
  }
}

main();
```

**5. Run the script**

Load the environment variable and execute the sender.

```bash theme={null}
npx dotenv-cli -- npm run send
```

If you do not have `dotenv-cli` installed, you can run:

```bash theme={null}
export BOSONMAIL_API_KEY=your_api_key
npx tsx src/send.ts
```

## Interpreting the output

When `sendEmail` succeeds, the SDK returns an object like this:

```typescript theme={null}
{
  success: true,
  statusCode: 200,
  id: "12345",
  messageId: "msg_abc123",
  status: "queued"
}
```

* `success: true` means the API accepted the message. It does **not** mean the recipient has received it yet.
* `status` is typically `"queued"` immediately after submission.
* `messageId` is the identifier you pass to `getEmailStatus` to poll for delivery progress.

If the call fails, `success` is `false` and you get `errorMessage` plus `statusCode` when the server responded:

```typescript theme={null}
{
  success: false,
  statusCode: 401,
  errorMessage: "unauthorized"
}
```

## Common first-run problems

> [accordion] BOSONMAIL\_API\_KEY is not set
>
> Make sure the environment variable is loaded before the script runs. Using `dotenv-cli` or exporting the variable directly both work. On Windows PowerShell, use `$env:BOSONMAIL_API_KEY = "your_api_key"`.

> [accordion] 'to' must contain at least one recipient
>
> The `to` argument must be a non-empty string or a non-empty array of strings. Double-check for accidental empty strings or arrays.

> [accordion] Request timed out after 30000ms
>
> The default timeout is 30 seconds. A timeout leaves the outcome uncertain: the server may have accepted the message even though the client did not receive the response. Check the email status with the message ID if you have it, or reconcile before retrying to avoid duplicates.

> [accordion] Unauthorized or invalid API key
>
> Verify that your key is active and has the required scope. The exact scopes are not yet documented by BosonWare: contact [support@bosonware.com](mailto:support@bosonware.com) if you are unsure.

## Next steps

> [card] [Sending HTML emails](https://docs.bosonware.com/guides/html-emails.md)
>
> Build rich order confirmations and marketing emails with inline styles and plain-text fallbacks.

> [card] [Sending with attachments](https://docs.bosonware.com/guides/attachments.md)
>
> Attach PDF invoices, CSV exports, and other files to your emails.

> [card] [Multiple recipients](https://docs.bosonware.com/guides/multiple-recipients.md)
>
> Send to many recipients using To, CC, BCC, or individual personalized emails.

> [card] [Monitoring delivery](https://docs.bosonware.com/guides/monitoring-delivery.md)
>
> Poll for delivery status and build a reconciliation workflow around message IDs.


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