Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createServer
✓ import { createServer } from 'fake-smtp-server';
✗ const FakeSmtpServer = require('fake-smtp-server');
The primary programmatic entry point for creating and managing the server instance. CommonJS users should destructure `createServer` from the `require` call.
FakeSmtpServerOptions
✓ import type { FakeSmtpServerOptions } from 'fake-smtp-server';
Type definition for configuring the server when using `createServer` programmatically.
This quickstart demonstrates how to programmatically start the `fake-smtp-server`, send an email to it using Nodemailer, and then retrieve and verify the captured email via its HTTP API. It also shows how to clear the mailbox.
import { createServer } from 'fake-smtp-server';
import { createTransport } from 'nodemailer';
import fetch from 'node-fetch'; // For HTTP API interaction
async function runEmailTest() {
const smtpPort = 2525;
const httpPort = 1081;
console.log(`Starting Fake SMTP Server on SMTP port ${smtpPort}, HTTP port ${httpPort}...`);
const server = createServer({
smtpPort,
httpPort,
headers: true // Enable headers for richer email data
});
await server.start();
console.log('Fake SMTP Server started.');
// Configure Nodemailer to send to our fake SMTP server
const transporter = createTransport({
host: 'localhost',
port: smtpPort,
secure: false, // Use plain SMTP for testing
tls: {
rejectUnauthorized: false
}
});
const testEmail = {
from: 'sender@example.com',
to: 'recipient@example.com',
subject: 'Test Email from Fake SMTP Server',
text: 'This is a test email sent to the fake SMTP server.',
html: '<b>This is a test email</b> sent to the fake SMTP server.'
};
console.log('Sending test email...');
await transporter.sendMail(testEmail);
console.log('Test email sent.');
console.log('Fetching received emails from API...');
const response = await fetch(`http://localhost:${httpPort}/api/emails?to=${testEmail.to}`);
const emails = await response.json();
if (emails.length > 0) {
console.log(`Received ${emails.length} email(s):`);
console.log(JSON.stringify(emails[0], null, 2));
if (emails[0].subject !== testEmail.subject) {
console.error('ERROR: Email subject mismatch!');
}
} else {
console.error('ERROR: No emails received!');
}
console.log('Clearing all emails via DELETE API...');
await fetch(`http://localhost:${httpPort}/api/emails`, { method: 'DELETE' });
const afterDelete = await (await fetch(`http://localhost:${httpPort}/api/emails`)).json();
console.log(`Emails after clear: ${afterDelete.length}`);
console.log('Stopping Fake SMTP Server...');
await server.stop();
console.log('Fake SMTP Server stopped.');
}
runEmailTest().catch(console.error);
fake-smtp-server --version
Errors
Common errors & fixes
EADDRINUSE: address already in use :::1025
Another process is already listening on the default SMTP port (1025) or the HTTP port (1080). This could be a previous instance of `fake-smtp-server` or another application.
fixStop the conflicting process or start `fake-smtp-server` on different ports using `fake-smtp-server --smtp-port 2525 --http-port 1081` (CLI) or by specifying `smtpPort` and `httpPort` options programmatically.
Error: connect ECONNREFUSED 127.0.0.1:1025
Your email client or test code is trying to connect to the SMTP server, but the `fake-smtp-server` is either not running or not listening on the expected IP address and port.
fixEnsure `fake-smtp-server` is running. Verify the SMTP host and port configured in your email client or test code match the server's settings (default: `localhost:1025`).
No emails found when querying the API, even after sending.
Several potential causes: 1) Email was sent to the wrong SMTP port/host. 2) The `--max` limit was reached, and older emails were purged. 3) API filters (`from`, `to`, `since`, `until`) are too restrictive or incorrect. 4) The email was malformed and not processed.
fix1) Double-check SMTP port/host settings. 2) Increase `--max` limit. 3) Remove API filters or simplify them to `GET /api/emails` to see all emails. 4) Check the email content and format being sent.
Audit
Dependencies
No dependency data recorded yet.