@nan0web/mail

A tiny, type-safe mail helper built on nodemailer. It provides ready-made classes for addresses, attachments, e-mail composition and a tiny DB helper.

|Package name|Status|Documentation|Test coverage|Features|Npm version| |---|---|---|---|---|---| |@nan0web/mail |🟢 98.0% |🧪 English 🏴󠁧󠁢󠁥󠁮󠁧󠁿Українською 🇺🇦 |🟡 89.4% |✅ d.ts 📜 system.md 🕹️ playground |— |

Installation

How to install with npm?

npm install @nan0web/mail

How to install with pnpm?

pnpm add @nan0web/mail

How to install with yarn?

yarn add @nan0web/mail

Usage – Address

Simple value object for e-mail, telephone or any address.

How to create an Address from a string?

import { Address } from '@nan0web/mail'
const addr = Address.from("John Doe <[email protected]>")
console.info(String(addr))
// John Doe <[email protected]>

*/ How to create an Address from an object?

import { Address } from '@nan0web/mail'
const addr = Address.from({ address: "[email protected]", name: "Test User" })
console.info(String(addr))
// Test User <[email protected]>

Usage – Attachment

Build a Nodemailer attachment, placeholders are replaced by the replace function.

How to create an Attachment and format it for Nodemailer?

import { Attachment } from '@nan0web/mail'
const att = new Attachment({
	filename: "invoice-{{id}}.pdf",
	path: "./invoices/{{id}}.pdf",
	contentDisposition: "inline",
})
const formatted = att.formatForNodemailer({ id: "123" })
console.info(JSON.stringify(formatted))
// {"filename":"invoice-123.pdf","path":"./invoices/123.pdf","contentDisposition":"inline"}

Usage – Email composition

Create an Email object, add attachments and render it for Nodemailer.

How to build an Email with placeholders and attachments?

import { Email, Attachment } from '@nan0web/mail'
const mail = new Email({
	subject: "Invoice {{id}}",
	html: "<p>Dear {{name}}, see attached.</p>",
	from: "Billing <[email protected]>",
	to: "Customer <[email protected]>",
	attachments: [
		{
			filename: "invoice-{{id}}.pdf",
			path: "./invoices/{{id}}.pdf",
		},
	],
})
const formatted = mail.formatForNodemailer({ id: "001", name: "Alice" })
console.info(JSON.stringify(formatted))
// {"from":"Billing <[email protected]>","to":"Customer <[email protected]>","cc":"","bcc":"","subject":"Invoice 001","html":"<p>Dear Alice, see attached.</p>","attachments":[{"filename":"invoice-001.pdf","path":"./invoices/001.pdf","contentDisposition":"attachment"}]}

Usage – Target

Handle multiple recipients: to, cc, bcc.

How to create a Target with multiple recipients?

import { Target, Address } from '@nan0web/mail'
const target = new Target()
target.add("[email protected]", "to")
target.add("[email protected]", "cc")
target.add("[email protected]", "bcc")
const formatted = target.formatForNodemailer()
console.info(JSON.stringify(formatted))
// {"to":"<[email protected]>","cc":"<[email protected]>","bcc":"<[email protected]>"}

*/ How to create Target from object?

import { Target } from '@nan0web/mail'
const target = Target.from({
	to: ["[email protected]", "[email protected]"],
	cc: "[email protected]",
})
const formatted = target.formatForNodemailer()
console.info(JSON.stringify(formatted))
// {"to":"<[email protected]>, <[email protected]>","cc":"<[email protected]>","bcc":""}

Usage – MailDB transformation

• Turn a raw record into an enriched object. */ How to transform data with MailDB?

import { MailDB } from '@nan0web/mail'
const db = new MailDB()
const source = { name: "John Smith", gender: 1, mail: "[email protected]" }
const config = {
	formattedName: [item => item.name.split(" ")[0]],
	genderText: [item => item.gender === 1 ? "male" : "female"],
	email: { $ref: "mail" },
	certificateNo: [item => "001"],
}
const result = await db.transform(source, config, {})
console.info(JSON.stringify(result))
// {"formattedName":"John","genderText":"male","email":"[email protected]","certificateNo":"001"}

Usage – Message

Build a message with sender, recipient and attachments.

How to create and use a Message?

import { Message, Attachment } from '@nan0web/mail'
const msg = new Message({
	body: "test message",
	from: "[email protected]",
	to: "[email protected]",
	attachments: [
		new Attachment({ filename: "note.txt", content: "Hello!" })
	]
})
console.info(String(msg))
// 2025-10-28T10:09:11.143Z test message
console.info(String(msg.from))
// <[email protected]>
console.info(String(msg.to))
// <[email protected]>
console.info(JSON.stringify(msg.attachments))
// [{"filename":"note.txt","content":"Hello!","path":"","href":"","httpHeaders":"","contentType":"","contentDisposition":"attachment","cid":"","encoding":"","headers":"","raw":""}]

Usage – createMailer

Helper that returns a Nodemailer transport.

How to create a Nodemailer transport with createMailer?

import { createMailer } from '@nan0web/mail'
const transport = createMailer({ jsonTransport: true })
console.info(transport.constructor.name) // ← Mail

Usage – send mail

The mail function composes everything and sends it.

How to send an email using the mail helper?

import { mail, Email } from '@nan0web/mail'
class DummyMailer {
	from
	subject
	html
	attachments
	async sendMail(msg) {
		Object.assign(this, msg)
		return { ok: true }
	}
}
const dummy = new DummyMailer()
const email = new Email({
	subject: "Hi {{user}}",
	html: "<p>Hello {{user}}</p>",
	from: "Me <[email protected]>",
	to: "You <[email protected]>",
})
const data = { user: "Bob" }
const info = await mail(email, data, { mailer: dummy })
console.info(info)
// { ok: true }

API reference

Address

• Properties address, name, type

• Methods toString(), toObject(), static from()

Attachment

• Properties filename, content, path, href, httpHeaders, contentType, contentDisposition, cid, encoding, headers, raw

• Methods formatForNodemailer(), static from()

Email

• Properties subject, html, from, target, attachments, text, style, dir, fields

• Methods attach(), formatForNodemailer(), static from()

Target

• Methods add(), addObject(), formatForNodemailer(), toString(), static from()

Message

• Properties body, time, from, to, dir, attachments

• Methods attach(), static from()

MailDB

• Methods transform(), loadFromReference(), static findNestedElement()

createMailer

Returns a Nodemailer transport. @param {object} trasportConfig The nodemailer config

mail

Sends a composed email. @param {Email} email Email instance @param {object} data Data to fill placeholders @param {object} opts Options like mailer and htmlEol

All exported symbols are defined

Java•Script

Uses d.ts files for autocompletion

Playground

Run a quick experiment.

How to run the playground script?

Contributing

How to contribute? - CONTRIBUTING.md

License

How to use license? - LICENSE