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 cossCreate 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:
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:
import { } from "coss";
export const = new ();
// or: new Coss({ apiKey: process.env.COSS_API_KEY })Send an email
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:
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
- Sending email: every send option, including tags, categories and React Email
- Delivery status: what each email and recipient status means
- Verifying webhooks with
verifyWebhook - Templates: keep subjects and bodies in coss.com
- Send email from Next.js
Last updated