Sending emails to multiple recipients

You can reach multiple recipients with a single BosonMail send or by sending individual emails per recipient. This guide compares the approaches, shows how to use CC and BCC, and provides a concurrency-limited loop for personalized sends so you stay within your plan allowance and respect any unpublished rate limits.

One email with many To recipients

Pass an array to the to field when every recipient sees the same content and each knows the others are included.

send-many-to.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 sendTeamUpdate() {
  const result = await client.sendEmail(
    ["alice@example.com", "bob@example.com", "carol@example.com"],
    "Weekly team update",
    {
      text: "The weekly update is now available on the shared drive.",
    }
  );

  if (!result.success) {
    console.error("Send failed:", result.errorMessage);
    return;
  }

  console.log("Team update sent. Message ID:", result.messageId);
}

sendTeamUpdate();

The SDK does not validate email address format. The API validates addresses and enforces recipient limits server-side. The exact maximum recipients per message is not published by BosonWare. Contact support@bosonware.com if you need to know the limit.

CC and BCC

Use cc to copy recipients openly and bcc to copy them privately. Both accept a single string or an array of strings.

send-cc-bcc.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 sendWithCopies() {
  const result = await client.sendEmail(
    "manager@example.com",
    "Project status report",
    {
      text: "The latest project status report is attached.",
      cc: ["pm@example.com", "cto@example.com"],
      bcc: "audit@example.com",
    }
  );

  if (!result.success) {
    console.error("Send failed:", result.errorMessage);
    return;
  }

  console.log("Report sent. Message ID:", result.messageId);
}

sendWithCopies();

Individual emails per recipient

When recipients should not see each other, or when content must be personalized, send one email per recipient. A naive Promise.all can overwhelm the API and your plan allowance, so use a small concurrency limit.

send-individual.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 });

interface Recipient {
  email: string;
  name: string;
  amount: number;
}

async function sendPersonalizedInvoices(recipients: Recipient[]) {
  const results: Array<{
    email: string;
    success: boolean;
    messageId?: string;
    error?: string;
  }> = [];

  const CONCURRENCY = 3;
  let index = 0;

  async function worker() {
    while (index < recipients.length) {
      const i = index++;
      const r = recipients[i];

      const result = await client.sendEmail(
        r.email,
        `Invoice for ${r.name}`,
        {
          text: `Hi ${r.name}, your invoice of KSh ${r.amount.toFixed(2)} is ready.`,
        }
      );

      results.push({
        email: r.email,
        success: result.success,
        messageId: result.messageId,
        error: result.errorMessage,
      });
    }
  }

  const workers = Array.from({ length: CONCURRENCY }, () => worker());
  await Promise.all(workers);

  return results;
}

async function main() {
  const recipients: Recipient[] = [
    { email: "alice@example.com", name: "Alice", amount: 1200 },
    { email: "bob@example.com", name: "Bob", amount: 1500 },
    { email: "carol@example.com", name: "Carol", amount: 900 },
  ];

  const results = await sendPersonalizedInvoices(recipients);

  for (const r of results) {
    if (r.success) {
      console.log("Sent to", r.email, "Message ID:", r.messageId);
    } else {
      console.error("Failed to send to", r.email, "Error:", r.error);
    }
  }
}

main();

Normalize and deduplicate addresses

Before sending, normalize addresses to lowercase and remove duplicates to avoid double-sends and wasted quota.

normalize.ts

function normalizeEmails(input: string | string[]): string[] {
  const arr = Array.isArray(input) ? input : [input];
  return Array.from(new Set(arr.map((e) => e.trim().toLowerCase()))).filter(
    (e) => e.length > 0
  );
}

// Usage
const to = normalizeEmails(["Alice@Example.COM", "alice@example.com", "Bob@Example.COM"]);
// => ["alice@example.com", "bob@example.com"]

Plan allowance and rate limits

Each BosonMail inbox includes 500 outbound emails per month. Emails sent through the SDK likely count against this allowance, but BosonWare has not confirmed this officially.

The SDK and API rate limits are not published. If you send large batches, start with low concurrency and monitor for HTTP 429 responses. Contact support@bosonware.com to confirm how SDK sends affect your plan quota.

Next steps

Monitoring delivery

Track delivery status for every recipient in a batch send.

Sending with attachments

Attach invoices or documents to personalized emails.

Production best practices

Manage concurrency, retries, and quotas safely in production.

SDK reference: CC and BCC

Read the concise SDK reference for CC and BCC parameters.

Getting Started

SDK Reference

Guides

Advanced

Resources

Sending emails to multiple recipients

One email with many To recipients

CC and BCC

Individual emails per recipient

Normalize and deduplicate addresses

Plan allowance and rate limits

Next steps

Monitoring delivery

Sending with attachments

Production best practices

SDK reference: CC and BCC

​One email with many To recipients

​CC and BCC

​Individual emails per recipient

​Normalize and deduplicate addresses

​Plan allowance and rate limits

​Next steps

Monitoring delivery

Sending with attachments

Production best practices

SDK reference: CC and BCC

One email with many To recipients

CC and BCC

Individual emails per recipient

Normalize and deduplicate addresses

Plan allowance and rate limits

Next steps