smtpsaurus 💌 🦕

Introduction

smtpsaurus is a local SMTP server built for Deno 2 for testing purposes. It implements basic functionality for receiving and storing e-mails, and provides an API for fetching stored e-mails.

⚠️ Warning: This library is meant to be used in tests only and should absolutely not be used in production systems. It currently lacks features such as TLS, authentication, and has minimal validation and error handling.

Installation

To add smtpsaurus to your Deno project:

deno add jsr:@smtpsaurus/smtpsaurus

smtpsaurus uses Deno KV as for storing e-mails in memory for retrieval, you will need to add the --unstable-kv CLI flag when running code that uses smtpsaurus.

Usage

Starting an SMTP server with default settings (port: 2525, domain: smtpsaurus.email) and retrieving sent e-mails:

import { SmtpServer } from "jsr:@smtpsaurus/smtpsaurus";

// Creating a new instance and starting the server.
const server = new SmtpServer();

// Start the server.
server.start();

// Retrieving e-mails.
const messageId = "<[email protected]>";
const senderEmail = "[email protected]";
const recipientEmails = ["[email protected]", "[email protected]"];

server.mailbox.get(messageId);
server.mailbox.getBySender(senderEmail);
server.mailbox.getByRecipient(recipientEmails[0]);

// Stopping the server.
await server.stop();

Starting a server with custom settings:

const server = new SmtpServer({
	domain: "happy-smtpsaurus.email",
	port: 65535,
});

server.start();

API documentation

Please see the automatically generated API documentation on JSR: https://jsr.io/@smtpsaurus/smtpsaurus/doc.

Examples

Using smtpsaurus in tests

import { SmtpServer } from "jsr:@smtpsaurus/smtpsaurus";
import { expect } from "jsr:@std/expect";
import { afterEach, beforeEach, describe, it } from "jsr:@std/testing/bdd";
// @ts-types="npm:@types/nodemailer"
import nodemailer from "nodemailer";

describe("SmtpServer", () => {
	let server: SmtpServer;

	beforeEach(() => {
		// Setting `findPortOnConflict` to `true` may be useful when running
		// tests in parallel, as it allows `smtpsaurus` to find an open
		// automatically if the one specified is in use.
		server = new SmtpServer({
			port: 42024,
			findPortOnConflict: true
			quiet: true
		});

		server.start();
	});

	afterEach(async () => {
		await server.stop();
	});

	it("process a well-formed sequence of commands", async () => {
		const transporter = nodemailer.createTransport({
			host: server.hostname,
			port: server.port,
			secure: false,
		});

		// Send an e-mail with nodemailer.
		const info = await transporter.sendMail({
			from: `"smtpsaurus" <[email protected]>`,
			to: "[email protected]",
			subject: "Test Email",
			text: "Hello, world!",
		});

		expect(info.response).toBe("250 OK");

		// Retrieve the sent e-mail from smtpsaurus.
		const data = await server.mailbox.get(info.messageId);

		assertExists(data);

		expect(data.messageId).toBe(info.messageId);
		expect(data.senderEmail).toBe(info.envelope.from);
		expect(data.recipientEmails).toEqual(
			expect.arrayContaining(info.envelope.to),
		);

		transporter.close();
	});
});