Sending emails

sendEmail is the primary method for submitting messages through the BosonMail API. It accepts a recipient list, a subject, and a body object that can contain text, HTML, CC, BCC, and attachments. The method always resolves, even on failure, and returns a Result object that tells you whether the API accepted the message.

Signature

sendEmail(
  to: string | string[],
  subject: string,
  body: SendEmailBody
): Promise<Result>

Parameters

string | string[]

required

Primary recipient(s). A single email address or an array of addresses. Must contain at least one non-empty string after trimming. The SDK does not validate email address format; the API checks that server-side.

string

required

Email subject line. Must be a non-empty string after trimming.

SendEmailBody

required

The email content and optional fields.

SendEmailBody fields

string

Plain text content. Either text or html (or both) must be provided as a non-empty string after trimming.

string

HTML content. Either text or html (or both) must be provided as a non-empty string after trimming.

string | string[]

Carbon-copy recipients. Accepts a single address or an array.

string | string[]

Blind carbon-copy recipients. Accepts a single address or an array.

SendAttachment[]

File attachments. When present, the request switches to multipart/form-data. See Attachments for full details.

Return value

boolean

required

true when the API accepted the email. false for any validation, network, API, or timeout failure.

string

Human-readable description when success is false.

number

HTTP status code from the API response. Absent for client-side validation errors and network/timeout failures.

string

BosonMail message ID, returned as a string when present in the API response.

string

API message identifier. May be undefined even on success, so always check it before calling getEmailStatus.

EmailSentStatus

Initial status from the API. Defaults to "queued" when the API omits it.

Transport: JSON vs multipart

The SDK chooses the request format automatically:

No attachments: Content-Type: application/json, POST /emails/send. Body fields to, cc, bcc are joined with , (no space) when arrays.
With attachments: multipart/form-data (boundary set by fetch), POST /emails/send. Fields: to, subject, textContent, htmlContent, cc, bcc, and one attachments field per file. Array fields are joined with , (comma + space) after trimming each element.

The SDK does not set the Content-Type header for multipart requests; fetch handles the boundary automatically.

The published README lists the endpoint as POST /mail/send, but the SDK source code (v0.2.0 and v0.2.1) calls POST /emails/send. The code is authoritative. Contact BosonWare at support@bosonware.com to confirm the intended endpoint.

Client-side validation

Before any network request, the SDK validates the input. These errors return { success: false, errorMessage } with no statusCode:

Validation rule	Exact error message
`to` is empty or all elements empty after trim	`'to' must contain at least one recipient`
`subject` is empty after trim	`'subject' must be a non-empty string`
`body` is not an object	`'body' must be an object`
`text` or `html` is not a string	`'text' and 'html' must be strings`
Neither `text` nor `html` is non-empty after trim	`Email must contain text or HTML content`
`attachments` is not an array	`'attachments' must be an array`
More than 10 attachments	`A maximum of 10 attachments is allowed`
Attachment missing `filename`	`Each attachment must have a filename`
Attachment `content` is not Blob, ArrayBuffer, or Uint8Array	`Invalid content for attachment "<filename>"`
Attachment exceeds 10 MiB	`Attachment "<filename>" exceeds the 10 MB per-attachment limit`
Total attachment size exceeds 20 MiB	`Total attachment size exceeds the 20 MB limit`
Request body preparation fails	`Failed to prepare email: <message>`

What success means

A successful sendEmail means the BosonMail API accepted the message. The typical initial status is "queued". It does not mean the email has been delivered, read, or that the recipient address is valid. Use getEmailStatus to track delivery progress.

Examples

Plain text email

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 confirmation",
  { text: "Thank you for your order. We will notify you when it ships." }
);

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

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 confirmation",
  { text: "Thank you for your order. We will notify you when it ships." }
);

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

HTML email with CC

send-html-cc.ts

import BosonMailClient from "@bosonware-ent/bosonmail";

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

const result = await client.sendEmail(
  ["customer@example.com", "partner@example.com"],
  "Monthly report",
  {
    html: "<h1>Monthly report</h1><p>Your report is attached.</p>",
    cc: "manager@example.com"
  }
);

if (result.success && result.messageId) {
  console.log("Message ID:", result.messageId);
}

With attachments

send-with-attachments.ts

import BosonMailClient from "@bosonware-ent/bosonmail";
import { readFile } from "node:fs/promises";

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

const pdf = await readFile("./invoice.pdf");

const result = await client.sendEmail(
  "billing@example.com",
  "Invoice for October",
  {
    text: "Your invoice is attached.",
    html: "<p>Your invoice is attached.</p>",
    attachments: [
      { filename: "invoice-october.pdf", content: pdf, contentType: "application/pdf" }
    ]
  }
);

HTML emails

Best practices for HTML content, multipart compatibility, and escaping user input.

Attachments

Supported content types, size limits, and security considerations.

Multiple recipients

How arrays are serialized and when to send individual emails instead.

Error handling

How to classify failures and decide when to retry.

Getting Started

SDK Reference

Guides

Advanced

Resources

Signature

Parameters

SendEmailBody fields

Return value

Transport: JSON vs multipart

Client-side validation

What success means

Examples

Plain text email

HTML email with CC

With attachments

HTML emails

Attachments

Multiple recipients

Error handling

​Signature

​Parameters

​SendEmailBody fields

​Return value

​Transport: JSON vs multipart

​Client-side validation

​What success means

​Examples

​Plain text email

​HTML email with CC

​With attachments

HTML emails

Attachments

Multiple recipients

Error handling

Signature

Parameters

SendEmailBody fields

Return value

Transport: JSON vs multipart

Client-side validation

What success means

Examples

Plain text email

HTML email with CC

With attachments