Node JS

Receive Inbound emails using Node.js – Node-Mailin

If you’re setting up, CRM or any Web app and want to receive emails to your domain dynamically without having to setup mail account for every domain subdomain and username, Then you can use this following NPM Module to do so. Node-Mailin

Node-Mailin – Receive Emails

Node-Mailin is an SMTP server that listens for emails, parses them as JSON then you can do whatever you want to do with that data. It checks the incoming emails dkim, spf, spam score (using SpamAssassin) and tells you in which language the email is written.

Node-Mailin can be used as a standalone application directly from the command line or embedded inside a Node.js application.


How to Setup Node-Mailin to Receive Emails

Node-Mailin can run without any dependencies other than Node.js itself, but having them allow you to use some additional features. So make sure Node.js is installed on your system.


So first make sure the node is available, and the node command as well. On Debian/Ubuntu boxes:

sudo aptitude install nodejs ; sudo ln -s $(which nodejs) /usr/bin/node

To handle dkim and spf checking, Node-Mailin depends on Python 2.7. On Linux machines, it is very not likely that you don’t have a decent version of Python available.

To handle the spam score computation, Node-Mailin depends on spamassassin and its server interface spamc. Both should be available as packages on your machine. For instance on Debian/Ubuntu boxes:

sudo aptitude install spamassassin spamc

Spamassassin is not enabled by default, enable it in /etc/default/spamassassin.

Node versions

The latest version of Node-Mailin (^0.0.1) runs on node ~8.0.0.

The crux: setting up your DNS correctly

In order to receive emails, your smtp server address should be made available somewhere. Two records should be added to your DNS records. Let us pretend that we want to receive emails at *

  • First an MX record: MX 10 This means that the mail server for addresses like * will be
  • Then an A record: A the.ip.address.of.your.Node-Mailin.server. This tells at which ip address the mail server can be found.

You can fire up Node-Mailin (see next section) and use an smtp server tester to verify that everything is correct.

Using Node-Mailin

From the command line

Install Node-Mailin globally.

sudo npm install -g node-mailin

Run it, (addtionnal help can be found using node-mailin --help). By default, Node-Mailin will listen on port 25, the standard smtp port. you can change this port for testing purpose using the --port option. However, do not change this port if you want to receive emails from the real world.

Ports number under 1000 are reserved to root user. So two options here. Either run Node-Mailin as root:

sudo node-mailin --port 25

Or, prefered choice, use something like authbind to run Node-Mailin with a standard user while still using port 25. Here comes a tutorial on how to setup authbind. In this case, do something like:

authbind --deep node-mailin --port 25

and make sure that your user can write to the log file.

At this point, Node-Mailin will listen for incoming emails, parse them, Then you can store them wherever you want.

  • error: listen EACCES: your user do not have sufficients privileges to run on the given port. Ports under 1000 are restricted to root user. Try with sudo.
  • error: listen EADDRINUSE: the current port is already used by something. Most likely, you are trying to use port 25 and your machine’s mail transport agent is already running. Stop it with something like sudo service exim4 stop or sudo service postfix stop before using Node-Mailin.
  • error: Unable to compute spam score ECONNREFUSED: it is likely that spamassassin is not enabled on your machine, check the /etc/default/spamassassin file.
  • node: command not found: most likely, your system does not have node installed or it is installed with a different name. For instance on Debian/Ubuntu, the node interpreter is called nodejs. The quick fix is making a symlink: ln -s $(which nodejs) /usr/bin/node to make the node command available.
  • Uncaught SenderError: Mail from command failed - 450 4.1.8 <[email protected]>: Sender address rejected: Domain not found: The smtpOption disableDNSValidation is set to false and an email was sent from an invalid domain.

Embedded inside a node application

Install node-mailin locally.

sudo npm install --save node-mailin

Start the node-mailin server and listen to events.


const nodeMailin = require('node-mailin');

/* Start the Node-Mailin server. The available options are:
 *  options = {
 *     port: 25,
 *     logFile: '/some/local/path',
 *     logLevel: 'warn', // One of silly, info, debug, warn, error
 *     smtpOptions: { // Set of options directly passed to simplesmtp.createServer(smtpOptions)
 *        SMTPBanner: 'Hi from a custom Node-Mailin instance',
 *        // By default, the DNS validation of the sender and recipient domains is disabled so.
 *        // You can enable it as follows:
 *        disableDNSValidation: false
 *     }
 *  };
 * parsed message. */
  port: 25,

/* Access simplesmtp server instance. */
nodeMailin.on('authorizeUser', function(connection, username, password, done) {
  if (username == "johnsmith" && password == "mysecret") {
    done(null, true);
  } else {
    done(new Error("Unauthorized!"), false);

/* Event emitted when a connection with the Node-Mailin smtp server is initiated. */
nodeMailin.on('startMessage', function (connection) {
  /* connection = {
      from: '[email protected]',
      to: '[email protected]',
      id: 't84h5ugf',
      authentication: { username: null, authenticated: false, status: 'NORMAL' }
  }; */

/* Event emitted after a message was received and parsed. */
nodeMailin.on('message', function (connection, data, content) {
  /* Do something useful with the parsed message here.
   * Use parsed message `data` directly or use raw message `content`. */



  • startData (connection) – DATA stream is opened by the client.
  • data (connection, chunk) – E-mail data chunk is passed from the client.
  • dataReady (connection, callback) – Client has finished passing e-mail data. callback returns the queue id to the client.
  • authorizeUser (connection, username, password, callback) – Emitted if requireAuthentication option is set to true. callback has two parameters (err, success) where success is a Boolean and should be true, if user is authenticated successfully.
  • validateSender (connection, email, callback) – Emitted if validateSender listener is set up.
  • senderValidationFailed (connection, email, callback) – Emitted if a sender DNS validation failed.
  • validateRecipient (connection, email, callback) – Emitted if validateRecipients listener is set up.
  • recipientValidationFailed (connection, email, callback) – Emitted if a recipient DNS validation failed.
  • close (connection) – Emitted when the connection to a client is closed.
  • startMessage (connection) – Connection with the Node-Mailin smtp server is initiated.


More info:

About the author

Vithal Reddy

Vithal Reddy is a seasoned technology professional with expertise in Full Stack Web development, Micro services and Scaling infrastructure on Cloud.
More at