{"id":15325,"library":"fake-smtp-server","title":"Fake SMTP Server","description":"Fake SMTP Server is a utility designed for email testing within QA and development workflows. It provides a local, in-memory SMTP server that captures all incoming emails, preventing them from being sent to real recipients. The captured emails can then be inspected manually via a web interface or programmatically through a RESTful API. The package is currently at version 0.8.0. While a strict release cadence isn't published, it appears actively maintained through its GitHub repository. Key differentiators include its ease of installation and use as a standalone server, making it ideal for local development and Continuous Integration (CI) environments where actual email sending is undesirable or complex to mock.","status":"active","version":"0.8.0","language":"javascript","source_language":"en","source_url":"https://github.com/ReachFive/fake-smtp-server","tags":["javascript","smtp","development","test","fake","dummy","mock","email","e-mail"],"install":[{"cmd":"npm install fake-smtp-server","lang":"bash","label":"npm"},{"cmd":"yarn add fake-smtp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add fake-smtp-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary programmatic entry point for creating and managing the server instance. CommonJS users should destructure `createServer` from the `require` call.","wrong":"const FakeSmtpServer = require('fake-smtp-server');","symbol":"createServer","correct":"import { createServer } from 'fake-smtp-server';"},{"note":"Type definition for configuring the server when using `createServer` programmatically.","symbol":"FakeSmtpServerOptions","correct":"import type { FakeSmtpServerOptions } from 'fake-smtp-server';"}],"quickstart":{"code":"import { createServer } from 'fake-smtp-server';\nimport { createTransport } from 'nodemailer';\nimport fetch from 'node-fetch'; // For HTTP API interaction\n\nasync function runEmailTest() {\n  const smtpPort = 2525;\n  const httpPort = 1081;\n\n  console.log(`Starting Fake SMTP Server on SMTP port ${smtpPort}, HTTP port ${httpPort}...`);\n  const server = createServer({\n    smtpPort,\n    httpPort,\n    headers: true // Enable headers for richer email data\n  });\n\n  await server.start();\n  console.log('Fake SMTP Server started.');\n\n  // Configure Nodemailer to send to our fake SMTP server\n  const transporter = createTransport({\n    host: 'localhost',\n    port: smtpPort,\n    secure: false, // Use plain SMTP for testing\n    tls: {\n      rejectUnauthorized: false\n    }\n  });\n\n  const testEmail = {\n    from: 'sender@example.com',\n    to: 'recipient@example.com',\n    subject: 'Test Email from Fake SMTP Server',\n    text: 'This is a test email sent to the fake SMTP server.',\n    html: '<b>This is a test email</b> sent to the fake SMTP server.'\n  };\n\n  console.log('Sending test email...');\n  await transporter.sendMail(testEmail);\n  console.log('Test email sent.');\n\n  console.log('Fetching received emails from API...');\n  const response = await fetch(`http://localhost:${httpPort}/api/emails?to=${testEmail.to}`);\n  const emails = await response.json();\n\n  if (emails.length > 0) {\n    console.log(`Received ${emails.length} email(s):`);\n    console.log(JSON.stringify(emails[0], null, 2));\n    if (emails[0].subject !== testEmail.subject) {\n      console.error('ERROR: Email subject mismatch!');\n    }\n  } else {\n    console.error('ERROR: No emails received!');\n  }\n\n  console.log('Clearing all emails via DELETE API...');\n  await fetch(`http://localhost:${httpPort}/api/emails`, { method: 'DELETE' });\n  const afterDelete = await (await fetch(`http://localhost:${httpPort}/api/emails`)).json();\n  console.log(`Emails after clear: ${afterDelete.length}`);\n\n  console.log('Stopping Fake SMTP Server...');\n  await server.stop();\n  console.log('Fake SMTP Server stopped.');\n}\n\nrunEmailTest().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"fix":"CLI: `fake-smtp-server --headers` or Programmatic: `createServer({ headers: true })`.","message":"Custom email headers are not captured by default and will not appear in API responses. To enable header capture, you must start the server with the `--headers` CLI flag or by passing `headers: true` in the options object if using the programmatic API.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Increase the limit using the `--max` CLI flag (e.g., `--max 500`) or by setting the `max` option in the programmatic API (e.g., `createServer({ max: 500 })`).","message":"The server has a default limit of 100 stored emails. If more emails are received, older ones will be purged. This can lead to unexpected missing emails in automated tests.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Specify alternative ports using `--smtp-port` and `--http-port` CLI flags or `smtpPort` and `httpPort` options in the programmatic API. Ensure previous instances are stopped.","message":"By default, the server listens on standard development ports (SMTP: 1025, HTTP: 1080). These ports can often conflict with other local services or previous instances of `fake-smtp-server`, leading to 'EADDRINUSE' errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use a date formatting utility or `toISOString()` method for JavaScript Date objects to ensure correct input, e.g., `new Date().toISOString()`.","message":"When filtering emails via the API using `since` and `until` parameters, ensure the date formats match the ISO 8601 standard (e.g., `YYYY-MM-DDTHH:mm:ssZ`). Incorrect formats may lead to no results being returned.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Stop 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.","cause":"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.","error":"EADDRINUSE: address already in use :::1025"},{"fix":"Ensure `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`).","cause":"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.","error":"Error: connect ECONNREFUSED 127.0.0.1:1025"},{"fix":"1) 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.","cause":"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.","error":"No emails found when querying the API, even after sending."}],"ecosystem":"npm"}