smtp-server

Create SMTP server instances on the fly. This is not a full-blown server application like Haraka but an easy way to add custom SMTP listeners to your app. This module is the successor for the server part of the (now deprecated) SMTP module simplesmtp. For matching SMTP client see smtp-connection.

Requires Node v0.12 or iojs. The module does not run on Node v0.10 as it uses Buffer.compare and TLSSocket.

Beware! This module is not battle tested (yet), I wrote it from scratch to replace simplesmtp server, so I might have overlooked some corner cases. File an issue if you find anything strange going on when using this module.

Support smtp-server development

Usage

Install with npm

npm install smtp-server

Require in your script

var SMTPServer = require('smtp-server');

Create SMTPServer instance

var server = new SMTPserver(options);

Where

• options defines the behavior of the server
  • options.secure defines if the connection should use TLS (if true) or not (the default). See tls.createServer for additional options you can use with the options object to set up the server when using secure. If the server does not start in TLS mode, then it is still possible to upgrade clear text socket to TLS socket with the STARTTLS command (unless you disable support for it)
  • options.name optional hostname of the server, used for identifying to the client (defaults to os.hostname())
  • options.banner optional greeting message. This message is appended to the default ESMTP response.
  • options.authMethods optional array of allowed authentication methods, defaults to ['PLAIN', 'LOGIN']. Only the methods listed in this array are allowed, so if you set it to ['XOAUTH2'] then PLAIN and LOGIN are not available. Use ['PLAIN', 'LOGIN', 'XOAUTH2'] to allow all three. Authentication is only allowed in secure mode (either the server is started with secure: true option or STARTTLS command is used)
  • options.disabledCommands optional array of disabled commands (see all supported commands here). For example if you want to disable authentication, use ['AUTH'] as this value. If you want to allow authentication in clear text, set it to ['STARTTLS'].
  • options.logger optional bunyan compatible logger instance. By default logs to console
  • options.maxClients sets the maximum number of concurrently connected clients, defaults to Infinity
  • options.socketTimeout how many milliseconds of inactivity to allow before disconnecting the client (defaults to 1 minute)
  • onAuth is the callback to handle authentications (see details here)
  • onMailFrom is the callback to validate MAIL FROM commands (see details here)
  • onRcptTo is the callback to validate RCPT TO commands (see details here)
  • onData is the callback to handle incoming messages (see details here)

Additionally you can use the options from net.createServer and tls.createServer (applies if secure is set to true). For example to set a SNICallback for the secure server, just set options.SNICallback.

TLS and STARTLS notice

If you use secure: true option or you do not disable STARTTLS command then you SHOULD also define the key, cert and possibly ca properties to use a proper certificate. If you do no specify your own certificate then a pregenerated self-signed certificate for 'localhost' is used. Any respectful client refuses to accept such certificate.

Example

// This example starts a SMTP server using TLS with your own certificate and key
var server = new SMTPServer({
    secure: true,
    key: fs.readFileSync('private.key'),
    cert: fs.readFileSync('server.crt')
});
server.listen(465);

Start the server instance

server.listen(port[,host][,callback]);

Where

• port is the port number to bound to
• host is the optional host to bound to
• callback is called once the server is bound

Handling errors

Errors can be handled by setting an 'error' event listener to the server instance

server.on('error', function(err){
    console.log('Error %s', err.message);
});

Handling Authentication

Authentication calls can be handled with onAuth handler

var server = new SMTPServer({
    onAuth: function(auth, session, callback){}
});

Where

• auth is an authentication object
  • method indicates the authentication method used, 'PLAIN', 'LOGIN' or 'XOAUTH2'
  • username is the username of the user
  • password is the password if LOGIN or PLAIN was used
  • accessToken is the OAuth2 bearer access token if 'XOAUTH2' was used as the authentication method
• session includes information about the session like remoteAddress for the remote IP, see details here
• callback is the function to run once the user is authenticated. Takes 2 arguments: (error, response)
  • error is an error to return if authentication failed. If you want to set custom error code, set responseCode to the error object
  • response is an object with the authentication results
    • user can be any value - if this is set then the user is considered logged in and this value is used later with the session data to identify the user. If this value is empty, then the authentication is considered failed
    • data is an object to return if XOAUTH2 authentication failed (do not set the error object in this case). This value is serialized to JSON and base64 encoded automatically, so you can just return the object

This module does not support CRAM based authentications since these require access to unencrypted user password during the authentication process. You shouldn't store passwords unencrypted anyway, so supporting it doesn't make much sense.

Examples

Password based authentication

var server = new SMTPServer({
    onAuth: function(auth, session, callback){
        if(auth.username !== 'abc' || auth.password !== 'def'){
            return callback(new Error('Invalid username or password'));
        }
        callback(null, {user: 123}); // where 123 is the user id or similar property
    }
});

Oauth2 authentication

XOAUTH2 support needs to enabled with the authMethods array option to use it as it is disabled by default. If you support multiple authentication mechanisms, then you can check the used mechanism from the method property.

var server = new SMTPServer({
    authMethods: ['XOAUTH2'], // XOAUTH2 is not enabled by default
    onAuth: function(auth, session, callback){
        if(auth.method !== 'XOAUTH'){
            // should never occur in this case as only XOAUTH2 is allowed
            return callback(new Error('Expecting XOAUTH2'));
        }
        if(auth.username !== 'abc' || auth.accessToken !== 'def'){
            return callback(null, {
                data: {
                    status: '401',
                    schemes: 'bearer mac',
                    scope: 'my_smtp_access_scope_name'
                }
            });
        }
        callback(null, {user: 123}); // where 123 is the user id or similar property
    }
});

Validating sender addresses

By default all sender addresses (as long as these are in valid email format) are allowed. If you want to check the address before it is accepted you can set a handler for it with onMailFrom

var server = new SMTPServer({
    onMailFrom: function(address, session, callback){}
});

Where

• address is an address object with the provided email address from MAIL FROM: command
• session includes the envelope object and user data if logged in, see details here
• callback is the function to run after validation. If you return an error object, the address is rejected, otherwise it is accepted

var server = new SMTPServer({
    onMailFrom = function(address, session, callback){
        if(address.address !== 'allowed@example.com'){
            return callback(new Error('Only allowed@example.com is allowed to send mail'));
        }
        return callback(); // Accept the address
    }
});

Validating recipient addresses

By default all recipient addresses (as long as these are in valid email format) are allowed. If you want to check the address before it is accepted you can set a handler for it with onRcptTo

var server = new SMTPServer({
    onRcptTo: function(address, session, callback){}
});

Where

• address is an address object with the provided email address from RCPT TO: command
• session includes the envelope object and user data if logged in, see details here
• callback is the function to run after validation. If you return an error object, the address is rejected, otherwise it is accepted

var server = new SMTPServer({
    onRcptTo = function(address, session, callback){
        if(address.address !== 'allowed@example.com'){
            return callback(new Error('Only allowed@example.com is allowed to receive mail'));
        }
        return callback(); // Accept the address
    }
});

Processing incoming message

You can get the stream for the incoming message with onData handler

var server = new SMTPServer({
    onRcptTo: function(stream, session, callback){}
});

Where

• stream is a readable stream for the incoming message
• session includes the envelope object and user data if logged in, see details here
• callback is the function to run once the stream is ended and you have processed the outcome. If you return an error object, the message is rejected, otherwise it is accepted

var server = new SMTPServer({
    onData = function(stream, session, callback){
        stream.pipe(process.stdout); // print message to console
        stream.on('end', callback);
    }
});

This module does not prepend Received or any other header field to the streamed message. The entire message is streamed as-is with no modifications whatsoever. For compliancy you should add the Received data to the message yourself, see rfc5321 4.4. Trace Information for details.

Session object

Session object that is passed to the handler functions includes the following properties

• id random string identificator generated when the client connected
• remoteAddress the IP address for the connected client
• clientHostname reverse resolved hostname for remoteAddress
• hostNameAppearsAs hostname the client provided with HELO/EHLO call
• envelope includes denvelope data
  • mailFrom includes an address object or is set to false
  • rcptTo includes an array of address objects
• user includes the user value returned with the authentication handler
• transaction number of the current transaction. 1 is for the first message, 2 is for the 2nd message etc.

Address object

Address object in the mailFrom and rcptTo values include the following properties

• address is the address provided with the MAIL FROM or RCPT TO command
• args is an object with additional arguments (all key names are uppercase)

For example if the client runs the following commands:

C: MAIL FROM:<sender@example.com> SIZE=12345 RET=HDRS
C: RCPT TO:<recipient@example.com> NOTIFY=NEVER

then the envelope object is going go look like this:

{
  "mailFrom": {
    "address": "sender@example.com",
    "args": {
      "SIZE": "12345",
      "RET": "HDRS"
    }
  },
  "rcptTo": [
    {
      "address": "receiver@example.com",
      "args": {
        "NOTIFY": "NEVER"
      }
    }
  ]
}

Supported SMTP commands

Commands

• AUTH LOGIN
• AUTH PLAIN
• AUTH XOAUTH2 not enabled by default, add to authMethods: ['XOAUTH2'] to enable
• EHLO
• DATA
• HELO
• HELP returns URL to RFC5321
• MAIL
• NOOP
• QUIT
• RCPT
• RSET clears session info but does not renegotiate TLS session
• STARTTLS
• VRFY always returns positive 252 response

Extensions

• PIPELINING
• 8BITMIME allows 8bit message content
• SMTPUTF8 accepts unicode e-mail addresses like δοκιμή@παράδειγμα.δοκιμή

Most notably, the ENHANCEDSTATUSCODES extension is not supported, all response codes use the standard three digit format and nothing else. I might change this in the future if I have time to revisit all responses and find the appropriate response codes.

CHUNKING is also missing. I might add support for it in the future but not at this moment since DATA already accepts a stream and CHUNKING is not supported everywhere.

License

MIT