Send emails with Node.js

In this quickstart, you'll learn how to send transactional emails from your Node.js project with Sidemail. You'll set up the SDK, send your first email, and see examples for common use cases like welcome emails, password resets, and scheduled reports.

Before you start

1. Create a Sidemail account → get your API key
2. Add a sending domain → set up your domain for sending

1. Install

npm install sidemail

2. Setup

Initialize the client. The SDK automatically reads SIDEMAIL_API_KEY from your environment variables if you don't provide it explicitly, but passing it is recommended for clarity.

Option A: Simple setup

Use this for simple scripts.

const configureSidemail = require("sidemail");

const sidemail = configureSidemail({
	apiKey: process.env.SIDEMAIL_API_KEY,
});

Option B: Shared instance (Module)

For larger applications, create a sidemail.js file that exports the configured instance.

// create file -> sidemail.js

const configureSidemail = require("sidemail");

const sidemail = configureSidemail({
	apiKey: process.env.SIDEMAIL_API_KEY,
});

module.exports = sidemail;

Usage:

const sidemail = require("./sidemail");

await sidemail.sendEmail({
	/* ... */
});

3. Send a welcome email

await sidemail.sendEmail({
	toAddress: user.email,
	fromAddress: "[email protected]",
	fromName: "Your App",
	templateName: "Welcome",
	templateProps: {
		firstName: user.name,
	},
});

4. Send a password reset email

const { email } = req.body;

await sidemail.sendEmail({
	toAddress: email,
	fromAddress: "[email protected]",
	fromName: "Your App",
	templateName: "Password Reset",
	templateProps: {
		actionUrl: "https://myapp.com/reset/token123",
	},
});

5. Send a weekly report (Cron Task)

Create a standalone script to run via cron or use a library like node-cron.

// scripts/send-weekly-report.js
const sidemail = require("../sidemail");

async function init() {
	// In a real app, fetch this from your database
	const newSignups = 150;
	const chartData = [100, 200, 300, 400, 200, 300, 200, 500];

	await sidemail.sendEmail({
		toAddress: "[email protected]",
		fromAddress: "[email protected]",
		fromName: "My App",
		templateName: "Weekly Report",
		templateProps: {
			signups: newSignups,
			chart: chartData,
		},
	});
}

init();

Run it via cron:

# Run every Monday at 8:00 AM
0 8 * * 1 node /path/to/scripts/send-weekly-report.js

6. Send HTML email

You can use template literals to render HTML directly in your code.

const amount = 99;
const html = `
  <div>
    <h1>Invoice</h1>
    <p>Amount due: $${amount}</p>
  </div>
`;

await sidemail.sendEmail({
	toAddress: "[email protected]",
	fromAddress: "[email protected]",
	fromName: "Your App",
	subject: "Your Invoice",
	html: html,
});

7. Send Markdown email

Store your markdown content in a file and load it (learn more).

const fs = require("fs");
const path = require("path");

const markdown = fs.readFileSync(
	path.join(__dirname, "templates/emails/welcome.md"),
	"utf8"
);

// Subject and sender are defined in the markdown frontmatter
await sidemail.sendEmail({
	toAddress: "[email protected]",
	markdown: markdown,
	templateProps: {
		name: "John",
		link: "https://example.com",
	},
});

8. Send plain text email

await sidemail.sendEmail({
	toAddress: "[email protected]",
	fromAddress: "[email protected]",
	fromName: "Your App",
	subject: "Hello",
	text: "Hello! 👋",
});

9. Schedule email

Send email later. Set scheduledAt to an ISO date string.

// Schedule for 1 hour from now
const scheduledAt = new Date(Date.now() + 60 * 60 * 1000).toISOString();

await sidemail.sendEmail({
	toAddress: "[email protected]",
	fromAddress: "[email protected]",
	fromName: "Your App",
	templateName: "Welcome",
	templateProps: { firstName: "Alex" },
	scheduledAt: scheduledAt,
});

10. Send with attachment

Use the sidemail.fileToAttachment helper to attach files.

const fs = require("fs");
const pdfData = fs.readFileSync("./invoice.pdf");
const attachment = sidemail.fileToAttachment("invoice.pdf", pdfData);

await sidemail.sendEmail({
	toAddress: "[email protected]",
	fromAddress: "[email protected]",
	fromName: "Your App",
	subject: "Your invoice",
	text: "See attached.",
	attachments: [attachment],
});

11. Handle errors

try {
	await sidemail.sendEmail({
		/* ... */
	});
} catch (error) {
	// Log error to file or monitoring system
	console.error("Sidemail error:", error.message);
}