Quickstart

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

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.

The exact steps to create or obtain an API key are not yet documented by BosonWare. Contact support@bosonware.com for guidance.

Install the SDK

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

npm

npm install @bosonware-ent/bosonmail

See Installation for TypeScript setup and CommonJS workarounds.

Set your environment variable

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

.env

BOSONMAIL_API_KEY=your_api_key

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

node --env-file=.env send.mjs

Bun loads .env automatically by default.

Write and run the send script

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

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);
}

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:

TypeScript

npx tsx send.ts

JavaScript (Node 20.6+)

node --env-file=.env send.mjs

Bun

bun send.ts

Check the email status

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

status.ts

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.

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

Sending emails

Learn about recipients, CC, BCC, HTML content, and result handling.

Email status

Poll for delivery, interpret statuses, and build audit trails.

Attachments

Add files to your messages with size limits and content types.

Next.js guide

Integrate BosonMail into API routes and server actions.

Getting Started

SDK Reference

Guides

Advanced

Resources

What the result means

Next steps

Sending emails

Email status

Attachments

Next.js guide

​What the result means

​Next steps

Sending emails

Email status

Attachments

Next.js guide

What the result means

Next steps