Configuration Options

Server Behavior

name

String

Server hostname used in the greeting banner. Defaults to os.hostname().

{ name: 'mail.example.com' }

banner

String

Additional text to display in the server greeting.

{ banner: 'Welcome to My SMTP Server' }

heloResponse

String

Custom HELO/EHLO response format. Use %s for placeholders (server name, client hostname). Defaults to "%s Nice to meet you, %s".

{ heloResponse: '%s at your service, %s' }

size

Number

Maximum message size in bytes. If set, the SIZE extension is advertised.

{ size: 10 * 1024 * 1024 } // 10 MB

hideSize

Boolean

default:"false"

If true, advertises SIZE without the maximum size value.

lmtp

Boolean

default:"false"

If true, operates as an LMTP server instead of SMTP.

{ lmtp: true }

logger

Boolean | Object

Enable logging. Set to true for console logging or provide a custom logger object.

{ logger: true }
// or
{ logger: customLoggerInstance }

component

String

default:"'smtp-server'"

Component identifier used in logs.

TLS/Security

secure

Boolean

default:"false"

If true, server accepts connections on TLS (SMTPS). Use with key and cert.

{
  secure: true,
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem')
}

needsUpgrade

Boolean

default:"false"

Used internally for delayed TLS upgrade. Set to true with secure: true to start TLS after connection.

secured

Boolean

Internal flag indicating TLS is already established on the socket.

key

String | Buffer

Private key for TLS (PEM format).

cert

String | Buffer

Certificate for TLS (PEM format).

String | Buffer | Array

Certificate authority certificates for TLS.

ciphers

String

Cipher suite specification for TLS.

requestCert

Boolean

Request client certificate during TLS handshake.

rejectUnauthorized

Boolean

Reject connections with invalid client certificates.

sniOptions

Object | Map

SNI (Server Name Indication) options for multiple certificates. Map domain names to TLS options.

{
  sniOptions: {
    'mail.example.com': {
      key: fs.readFileSync('example-key.pem'),
      cert: fs.readFileSync('example-cert.pem')
    },
    'mail.other.com': {
      key: fs.readFileSync('other-key.pem'),
      cert: fs.readFileSync('other-cert.pem')
    }
  }
}

SNICallback

Function

Custom SNI callback function (servername, cb) => { cb(null, secureContext) }.

hideSTARTTLS

Boolean

default:"false"

If true, does not advertise STARTTLS capability.

allowInsecureAuth

Boolean

default:"false"

If true, allows authentication over non-TLS connections.

Authentication

authMethods

Array<String>

default:"['LOGIN', 'PLAIN']"

Allowed authentication methods. Available: 'PLAIN', 'LOGIN', 'CRAM-MD5', 'XOAUTH2'.

{ authMethods: ['PLAIN', 'LOGIN', 'CRAM-MD5'] }

authOptional

Boolean

default:"false"

If true, authentication is optional (allows unauthenticated mail).

authRequiredMessage

String

Custom error message when authentication is required.

{ authRequiredMessage: 'Please authenticate first' }

maxAllowedUnauthenticatedCommands

Number

default:"10"

Maximum number of commands allowed before authentication. Set to false to disable limit.

SMTP Extensions

disabledCommands

Array<String>

default:"[]"

List of SMTP commands to disable. Example: ['AUTH', 'STARTTLS'].

{ disabledCommands: ['STARTTLS'] }

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.

hideENHANCEDSTATUSCODES

Boolean

default:"true"

If true, does not include enhanced status codes in responses.

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).

Connection Management

socketTimeout

Number

default:"60000"

Socket inactivity timeout in milliseconds.

{ socketTimeout: 120000 } // 2 minutes

closeTimeout

Number

default:"30000"

Time to wait for pending connections to close before forcing shutdown (milliseconds).

{ closeTimeout: 60000 } // 1 minute

maxClients

Number

Maximum number of concurrent connections. New connections are rejected with 421 if exceeded.

{ maxClients: 100 }

disableReverseLookup

Boolean

default:"false"

If true, skips DNS reverse lookup for client IP addresses.

resolver

Object

Custom DNS resolver with a reverse(ip, callback) method.

Proxy Support

useProxy

Boolean | Array

Enable PROXY protocol support. Set to true for all connections or provide array of allowed IP addresses.

{ useProxy: ['127.0.0.1', '10.0.0.1'] }
// or
{ useProxy: true }

ignoredHosts

Array<String>

IP addresses to silently ignore (no logging or connection events).

{ ignoredHosts: ['127.0.0.1'] }

useXClient

Boolean

default:"false"

Enable XCLIENT extension for trusted clients to override connection properties.

Only enable for trusted proxies. XCLIENT allows clients to impersonate other connections.

useXForward

Boolean

default:"false"

Enable XFORWARD extension for forwarding connection metadata.

Only enable for trusted proxies.

Handler Methods

These can be set as options or defined as methods on the server instance. See Handler Methods for details.

onConnect

Function

Called when a client connects. Signature: (session, callback)

onSecure

Function

Called after TLS is established. Signature: (socket, session, callback)

onAuth

Function

Called for authentication. Signature: (auth, session, callback)

onMailFrom

Function

Called for MAIL FROM command. Signature: (address, session, callback)

onRcptTo

Function

Called for RCPT TO command. Signature: (address, session, callback)

onData

Function

Called for DATA command. Signature: (stream, session, callback)

onClose

Function

Called when connection closes. Signature: (session)

Example: Complete Configuration

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

const server = new SMTPServer({
  // Server identity
  name: 'mail.example.com',
  banner: 'Welcome to Example Mail Server',
  
  // TLS configuration
  secure: true,
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
  
  // Size limits
  size: 25 * 1024 * 1024, // 25 MB
  
  // Authentication
  authMethods: ['PLAIN', 'LOGIN'],
  authOptional: false,
  
  // Connection limits
  maxClients: 100,
  socketTimeout: 120000,
  
  // Logging
  logger: true,
  
  // Extensions
  hideDSN: false,
  hideENHANCEDSTATUSCODES: false,
  
  // Handlers
  onAuth(auth, session, callback) {
    // Implement authentication
    callback(null, { user: auth.username });
  },
  
  onData(stream, session, callback) {
    // Process message
    stream.on('end', () => {
      callback(null, 'Message accepted');
    });
  }
});

server.listen(465);

Core API

Advanced

Configuration Options

Server Behavior

TLS/Security

Authentication

SMTP Extensions

Connection Management

Proxy Support

Handler Methods

Example: Complete Configuration

Build docs developers (and LLMs) love

Core API

Advanced

​Server Behavior

​TLS/Security

​Authentication

​SMTP Extensions

​Connection Management

​Proxy Support

​Handler Methods

​Example: Complete Configuration

Build docs developers (and LLMs) love

Server Behavior

TLS/Security

Authentication

SMTP Extensions

Connection Management

Proxy Support

Handler Methods

Example: Complete Configuration