Skip to main content

​
Overview

The SMTP Server library provides extensive configuration options to customize server behavior, security settings, protocol features, and message handling. All options are passed to the SMTPServer constructor.

​
Basic Configuration

const { SMTPServer } = require('smtp-server');

const server = new SMTPServer({
  name: 'smtp.example.com',
  banner: 'Welcome to My SMTP Server',
  size: 10 * 1024 * 1024, // 10 MB
  logger: true
});

server.listen(2525);

​
Core Server Options

​
name
string
default:"os.hostname()"
Server hostname used in greeting messages and SMTP responses.
​
banner
string
default:"undefined"
Custom banner text displayed in the initial greeting after hostname.
banner: 'Welcome to My Awesome SMTP Server'
​
size
number
default:"undefined"
Maximum message size in bytes. Server advertises this via SIZE extension.
size: 10 * 1024 * 1024 // 10 MB limit
​
hideSize
boolean
default:"false"
If true, advertises SIZE extension without specifying the limit.
​
logger
boolean | object
default:"false"
Enable logging. Set to true for console logging or provide a custom logger object.
logger: true // Console logging
// or
logger: customLoggerObject
​
component
string
default:"'smtp-server'"
Component name for log messages.

​
TLS/Security Options

​
secure
boolean
default:"false"
If true, server requires TLS from the start (implicit TLS on port 465).
​
needsUpgrade
boolean
default:"false"
Used with secure: true to require immediate TLS upgrade after connection.
​
key
Buffer | string
Private key for TLS. Required for secure connections.
key: fs.readFileSync('/path/to/private.key')
​
cert
Buffer | string
Server certificate for TLS. Required for secure connections.
cert: fs.readFileSync('/path/to/server.crt')
​
ca
Array<Buffer | string>
Certificate authority certificates.
ca: [fs.readFileSync('/path/to/ca.crt')]
​
sniOptions
Map | object
SNI (Server Name Indication) options for serving different certificates per domain.
sniOptions: {
  'mail.example.com': {
    key: fs.readFileSync('example-key.pem'),
    cert: fs.readFileSync('example-cert.pem')
  },
  'mail.another.com': {
    key: fs.readFileSync('another-key.pem'),
    cert: fs.readFileSync('another-cert.pem')
  }
}
​
SNICallback
function
Custom SNI handler function. Default implementation uses sniOptions.
SNICallback: (servername, cb) => {
  cb(null, tlsContext);
}

​
Protocol Features

​
lmtp
boolean
default:"false"
Enable LMTP (Local Mail Transfer Protocol) instead of SMTP.
LMTP mode changes protocol behavior and disables HELO/EHLO in favor of LHLO.
​
hideSTARTTLS
boolean
default:"false"
If true, does not advertise STARTTLS extension (disables opportunistic TLS).
​
hidePIPELINING
boolean
default:"false"
If true, does not advertise PIPELINING extension.
​
hide8BITMIME
boolean
default:"false"
If true, does not advertise 8BITMIME extension.
​
hideSMTPUTF8
boolean
default:"false"
If true, does not advertise SMTPUTF8 extension (UTF-8 email addresses).
​
hideENHANCEDSTATUSCODES
boolean
default:"true"
If true, does not advertise or include enhanced status codes (RFC 3463).
Enhanced status codes are disabled by default. Set to false to enable them.
​
hideDSN
boolean
default:"true"
If true, does not advertise DSN (Delivery Status Notification) extension.
​
hideREQUIRETLS
boolean
default:"true"
If true, does not advertise REQUIRETLS extension (RFC 8689).
​
disabledCommands
Array<string>
default:"[]"
Array of SMTP commands to disable.
disabledCommands: ['AUTH', 'STARTTLS']

​
Connection Limits

​
maxClients
number
default:"undefined"
Maximum number of concurrent connections. Server returns 421 when limit exceeded.
maxClients: 100
​
socketTimeout
number
default:"60000"
Socket timeout in milliseconds (default: 60 seconds).
​
closeTimeout
number
default:"30000"
Time to wait for pending connections to close when server.close() is called.

​
Security Options

​
allowInsecureAuth
boolean
default:"false"
If false, requires TLS before allowing authentication.
Setting to true allows credentials to be sent in plain text over unencrypted connections.
​
authOptional
boolean
default:"false"
If true, allows mail transactions without authentication.
​
authRequiredMessage
string
Custom error message when authentication is required.
authRequiredMessage: 'Please authenticate before sending mail'
​
maxAllowedUnauthenticatedCommands
number
default:"10"
Maximum commands allowed before authentication. Connection closed when exceeded. Set to false to disable this limit.

​
Proxy Support

​
useProxy
boolean | Array<string>
default:"false"
Enable PROXY protocol support. Can be true, false, or array of allowed IP addresses.
useProxy: ['127.0.0.1', '::1'] // Only accept from localhost
// or
useProxy: ['*'] // Accept from any IP
​
useXClient
boolean
default:"false"
Enable XCLIENT extension for connection property override (Postfix).
Useful when running behind a proxy to preserve original client information.
​
useXForward
boolean
default:"false"
Enable XFORWARD extension for forwarding client data (Postfix).
​
ignoredHosts
Array<string>
Array of IP addresses for connections to ignore/skip logging.
ignoredHosts: ['127.0.0.1', '::1']

​
DNS Configuration

​
disableReverseLookup
boolean
default:"false"
If true, skips reverse DNS lookup for client IP addresses.
Enable this to improve connection speed if reverse DNS is not needed.
​
resolver
object
Custom DNS resolver object with a reverse method.
resolver: {
  reverse: (ip, callback) => {
    // Custom reverse DNS logic
    callback(null, ['hostname.example.com']);
  }
}

​
Greeting Customization

​
heloResponse
string
default:"'%s Nice to meet you, %s'"
Custom HELO/EHLO response format. Use %s placeholders for server name and client hostname.
heloResponse: '%s Ready to serve, %s'
// Output: "smtp.example.com Ready to serve, client.example.com"

​
Event Handlers

Event handlers can be set as constructor options. See Handling Messages and Session Management for details. 
const server = new SMTPServer({
  onConnect: (session, callback) => { /* ... */ },
  onAuth: (auth, session, callback) => { /* ... */ },
  onMailFrom: (address, session, callback) => { /* ... */ },
  onRcptTo: (address, session, callback) => { /* ... */ },
  onData: (stream, session, callback) => { /* ... */ },
  onSecure: (socket, session, callback) => { /* ... */ },
  onClose: (session) => { /* ... */ }
});

​
Complete Example

const { SMTPServer } = require('smtp-server');
const fs = require('fs');

const server = new SMTPServer({
  // Server identity
  name: 'smtp.example.com',
  banner: 'Welcome to Example SMTP Server',
  
  // TLS configuration
  secure: false,
  key: fs.readFileSync('private.key'),
  cert: fs.readFileSync('server.crt'),
  
  // Size limits
  size: 25 * 1024 * 1024, // 25 MB
  
  // Authentication
  authMethods: ['PLAIN', 'LOGIN'],
  authOptional: false,
  allowInsecureAuth: false,
  
  // Connection limits
  maxClients: 100,
  socketTimeout: 60000,
  
  // Protocol features
  hideENHANCEDSTATUSCODES: false,
  hideDSN: false,
  
  // Logging
  logger: true,
  
  // Handlers
  onAuth: require('./handlers/auth'),
  onData: require('./handlers/data')
});

server.listen(587);

Build docs developers (and LLMs) love

Get started for freeTalk to us