Send email with Node.js

Send email from Node.js with the coss SDK, with attachments, scheduled sends, batches and an Express route, or keep Nodemailer and swap its transport.

The coss package sends email from Node.js 22 or later over HTTPS. It has zero dependencies, is ESM-only (use import), and returns { data, error } instead of throwing.

Install the SDK

npm install coss

Create an API key in the dashboard, in your project's Development environment, and make it available as COSS_API_KEY, for example in a .env file that you load with node --env-file=.env:

.env
COSS_API_KEY=coss_test_...

npx coss-cli init does both steps for you: it approves a development key in the dashboard, writes it to .env and installs the SDK (CLI).

Create the client

new Coss() reads COSS_API_KEY from the environment. Create one client and reuse it:

coss.mjs
import {  } from "coss";

export const  = new ();
// or: new Coss({ apiKey: process.env.COSS_API_KEY })

Send an email

send.mjs
import {  } from "coss";

const  = new ();

const { ,  } = await ..({
  : "Acme <hello@acme.com>",
  : "ada@example.com",
  : "Your order has shipped",
  : "<p>Your order is on its way.</p>",
  : "Your order is on its way.",
});

if () {
  .(., .);
} else {
  .(., .);
}

to, cc, bcc and reply_to take one address or an array, as "ada@example.com" or "Ada Lovelace <ada@example.com>". The email comes back queued and is handed to the delivery provider moments later. API and network failures are returned as error, never thrown, and the SDK retries the temporary ones itself (errors and retries).

Test with a development key, send live from your domain

Development keys start with coss_test_: emails are recorded but never delivered, any from address works, and bounce@simulator.amazonses.com simulates a bounce (sandbox behaviour). To deliver real email, use a coss_live_ key from the Production environment and send from a domain your organization has verified. Sending from any other domain returns domain_not_verified.

Send attachments

Attachments are base64 in attachments. coss.com never fetches files from a URL, so read them yourself:

import {  } from "node:fs/promises";

const  = await ("invoice-1042.pdf");

const { ,  } = await ..({
  : "Acme Billing <billing@acme.com>",
  : "ada@example.com",
  : "Invoice 1042",
  : "Your invoice is attached.",
  : [{ : "invoice-1042.pdf", : .("base64") }],
});

Every filename needs an extension, and content_type defaults from it. A content_id makes an attachment inline, for <img src="cid:…"> in html. See attachments for the limits and blocked file types.

Schedule an email

Pass scheduled_at, an ISO 8601 timestamp with a time zone offset, up to 30 days ahead:

const  = new (.() + 24 * 60 * 60 * 1000);

const { :  } = await ..({
  : "Acme <hello@acme.com>",
  : "ada@example.com",
  : "Your trial ends tomorrow",
  : "Pick a plan to keep your projects.",
  : .(),
});

// Changed your mind?
if () await ..(.);

Until it is sent, move it with coss.email.reschedule(id, { scheduled_at }) or cancel it. See scheduling.

Send emails in a batch

coss.email.sendBatch() sends up to 100 emails in one request, each with its own sender, recipients and content:

const  = [
  { : "Ada", : "ada@example.com" },
  { : "Grace", : "grace@example.com" },
];

const { ,  } = await ..(
  .(() => ({
    : "Acme <notifications@acme.com>",
    : .,
    : "Your weekly summary",
    : `<p>Hi ${.}, here is your week.</p>`,
  })),
  { : "weekly-summary-2026-11-16" },
);

.(?..(() => .));

A batch is all or nothing: if one email is invalid, none is sent, and error.issues names it by position, such as emails.1.to. For larger lists, send several batches, each with its own key.

Send email from an Express route

Call the SDK from your handler and answer once the email is accepted:

server.mjs
import  from "express";
import {  } from "coss";

const  = ();
const  = new ();
.(.());

.("/password-reset", async (, ) => {
  const { ,  } = .;

  const {  } = await ..(
    {
      : "Acme <security@acme.com>",
      : ,
      : "Reset your password",
      : `Reset your password: https://acme.com/reset?token=${}`,
      : "account",
    },
    { : `password-reset-${}` },
  );

  if () {
    .(., .);
    return .(502).({ : "Could not send the email" });
  }
  .(202).({ : true });
});

.(3000);

The idempotency key makes a retried request safe: for 24 hours, a send with the same key returns the original email instead of sending another (idempotency).

Already using Nodemailer?

Keep your sendMail calls and swap the transport for coss/nodemailer. It sends over HTTPS, so it also works where outgoing SMTP ports are blocked:

import  from "nodemailer";
import {  } from "coss/nodemailer";

const  = .(());

await .({
  : '"Acme" <hello@acme.com>',
  : "ada@example.com",
  : "Your receipt",
  : "Thanks for your order.",
});

See Nodemailer for options and the supported fields.

Check delivery

Each recipient has its own delivery status. Read it with coss.email.get(), or add a webhook endpoint to be told when it changes:

const { :  } = await ..("email_01k7c8m4q2f3e9v6t5r1n0p8yz");

for (const  of ?. ?? []) {
  .(., .);
}

Next steps

Last updated