smtp-server

You can advertise a maximum message size to clients by setting the size option in the SMTPServer configuration.

When a client declares a size in the MAIL FROM:<addr> SIZE=nnn parameter, the server checks it against your limit. However, the server does not automatically block the transfer; instead, it streams the data to your application. You must handle enforcement within your onData handler by checking the stream.sizeExceeded flag.

To prevent large transfers from consuming too much bandwidth, you can check the stream.sizeExceeded flag during the data event to stop the transfer early, rather than waiting for the end event.

const server = new SMTPServer({
    size: 1024 * 1024, // 1 MiB limit
    onData(stream, session, callback) {
        stream.on('end', () => {
            if (stream.sizeExceeded) {
                const err = new Error('Message too large');
                err.responseCode = 552;
                return callback(err);
            }
            callback(null, 'OK');
        });
        stream.resume(); // Consume the stream
    }
});

Instead of using an event emitter for everything, you can provide shorthand handler functions directly in the options object passed to the SMTPServer constructor. These handlers allow you to intercept different stages of the SMTP lifecycle:

• onConnect(session, callback): Called when a client connects.
• onSecure(socket, session, callback): Called when a connection is secured via TLS.
• onAuth(auth, session, callback): Called when a client attempts to authenticate. auth contains the method and credentials.
• onMailFrom(address, session, callback): Called when the MAIL FROM command is received.
• onRcptTo(address, session, callback): Called when the RCPT TO command is received.
• onData(stream, session, callback): Called when the DATA command is received. The stream argument is a readable stream containing the email content.
• onClose(session): Called when the connection is closed.

const server = new SMTPServer({
    onConnect: (session, callback) => {
        console.log('Client connected');
        callback();
    },
    onData: (stream, session, callback) => {
        stream.on('data', (chunk) => {
            console.log('Received chunk:', chunk.toString());
        });
        stream.on('end', () => {
            callback();
        });
    }
});

To create a basic SMTP server, instantiate SMTPServer from the smtp-server package. You can configure the server using an options object.

Key configuration options used in this example:

• disabledCommands: An array of SMTP commands to disable (e.g., ['STARTTLS', 'AUTH']).
• logger: Set to true to enable logging.
• onData: A callback function triggered when data is received. It receives a stream (the email data), the session object, and a callback to signal completion.

After instantiation, call .listen(port) to start the server on the specified port.

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

const server = new SMTPServer({
    // disable STARTTLS to allow authentication in clear text mode
    disabledCommands: ['STARTTLS', 'AUTH'],
    logger: true,
    onData(stream, session, callback) {
        stream.pipe(process.stdout); // print message to console
        stream.on('end', callback);
    }
});

server.listen(25);

The SMTPServer class is the primary entrypoint for creating and configuring an SMTP or LMTP server instance. You instantiate it by passing an options object containing connection and SMTP settings. The server can be started by calling .listen() and stopped by calling .close().

Common configuration options include:

• secure: Boolean indicating if the server should use TLS.
• authMethods: Array of allowed authentication methods (defaults to ['LOGIN', 'PLAIN']).
• disabledCommands: Array of SMTP commands to disable.
• hideENHANCEDSTATUSCODES: Boolean (defaults to true).
• hideDSN: Boolean (defaults to true).
• hideREQUIRETLS: Boolean (defaults to true).
• closeTimeout: Time in milliseconds to wait for pending connections to close before forcing them shut (defaults to 30,000ms).

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

const server = new SMTPServer({
    host: '127.0.0.1',
    port: 587,
    secure: false,
    auth: async (data, session, callback) => {
        // Implement authentication logic
        callback(null, { user: 'user' });
    }
});

server.listen(587, () => {
    console.log('Server is listening');
});

When an SMTP DATA command is received, you should switch the SMTPStream from command mode to data mode using startDataMode(maxBytes). This allows you to receive the actual email body as a stream.

Workflow:

1. Switch Modes: Call startDataMode(maxBytes) inside your oncommand handler. This returns a PassThrough stream representing the message content.
2. Handle Data: Listen to the returned stream for data. The stream automatically handles unescaping dots (e.g., .. at the start of a line is treated as a literal dot).
3. Monitor Size: The returned stream has two useful properties you can monitor mid-transfer:
   • byteLength: The current number of bytes received.
   • sizeExceeded: A boolean that becomes true if the received bytes exceed the maxBytes limit you provided.
4. Finish Processing: Once you have finished processing the data stream, call continue() on the SMTPStream instance to return to command mode.

// Inside your oncommand override:
if (cmd === 'DATA') {
    const dataStream = this.startDataMode(10 * 1024 * 1024); // 10MB limit

    dataStream.on('data', (chunk) => {
        console.log('Received chunk:', chunk.length, 'bytes');
        if (dataStream.sizeExceeded) {
            console.warn('Warning: Message size exceeded limit');
        }
    });

    dataStream.on('end', () => {
        console.log('Data transfer complete');
        this.continue(); // Return to command mode
    });
}