Sending your first email

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 and contact support@bosonware.com for API key provisioning steps.

Initialize the project

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

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:

package.json

{
  "name": "bosonmail-first-email",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "send": "tsx src/send.ts"
  }
}

Install the SDK and dev tools

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

npm install @bosonware-ent/bosonmail
npm install --save-dev typescript tsx @types/node

Generate a basic tsconfig.json:

npx tsc --init

Configure environment variables

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

.env

BOSONMAIL_API_KEY=your_api_key

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

.gitignore

node_modules/
.env
dist/
*.log

Never commit API keys to version control. Treat .env as sensitive and share keys only through a secrets manager.

Write the sender script

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

src/send.ts

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

Run the script

Load the environment variable and execute the sender.

npx dotenv-cli -- npm run send

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

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:

{
  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:

{
  success: false,
  statusCode: 401,
  errorMessage: "unauthorized"
}

Common first-run problems

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

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

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.

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 if you are unsure.

Next steps

Sending HTML emails

Build rich order confirmations and marketing emails with inline styles and plain-text fallbacks.

Sending with attachments

Attach PDF invoices, CSV exports, and other files to your emails.

Multiple recipients

Send to many recipients using To, CC, BCC, or individual personalized emails.

Monitoring delivery

Poll for delivery status and build a reconciliation workflow around message IDs.

Getting Started

SDK Reference

Guides

Advanced

Resources

Sending your first email

Prerequisites

Interpreting the output

Common first-run problems

Next steps

Sending HTML emails

Sending with attachments

Multiple recipients

Monitoring delivery

​Prerequisites

​Interpreting the output

​Common first-run problems

​Next steps

Sending HTML emails

Sending with attachments

Multiple recipients

Monitoring delivery

Prerequisites

Interpreting the output

Common first-run problems

Next steps