{"id":21651588,"url":"https://github.com/vithalreddy/node-mailin","last_synced_at":"2025-04-11T20:30:35.835Z","repository":{"id":32437463,"uuid":"139140925","full_name":"vithalreddy/node-mailin","owner":"vithalreddy","description":"Artisanal inbound emails for every web app using nodejs","archived":false,"fork":false,"pushed_at":"2022-12-08T10:09:44.000Z","size":440,"stargazers_count":77,"open_issues_count":18,"forks_count":18,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-25T16:22:43.556Z","etag":null,"topics":["dkim","email","mailn","node-mailer","nodejs","smtp","smtp-server","spf"],"latest_commit_sha":null,"homepage":"https://stackfame.com/receive-inbound-emails-node-js","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vithalreddy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-29T11:22:11.000Z","updated_at":"2025-01-20T20:25:51.000Z","dependencies_parsed_at":"2023-01-14T21:13:14.355Z","dependency_job_id":null,"html_url":"https://github.com/vithalreddy/node-mailin","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vithalreddy%2Fnode-mailin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vithalreddy%2Fnode-mailin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vithalreddy%2Fnode-mailin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vithalreddy%2Fnode-mailin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vithalreddy","download_url":"https://codeload.github.com/vithalreddy/node-mailin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248476079,"owners_count":21110208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dkim","email","mailn","node-mailer","nodejs","smtp","smtp-server","spf"],"created_at":"2024-11-25T07:48:49.095Z","updated_at":"2025-04-11T20:30:35.790Z","avatar_url":"https://github.com/vithalreddy.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Node-Mailin\n\n**Artisanal inbound emails for every web app**\n\u003cimg align=\"right\" src=\"postman.jpg\"/\u003e\n\nNode-Mailin is an smtp server that listens for emails, parses as json.\nIt checks the incoming emails [dkim](http://en.wikipedia.org/wiki/DomainKeys_Identified_Mail), [spf](http://en.wikipedia.org/wiki/Sender_Policy_Framework), spam score (using [spamassassin](http://spamassassin.apache.org/)) and tells you in which language the email is written.\n\nNode-Mailin can be used as a standalone application directly from the command line, or embedded inside a node application.\n\n### Initial setup\n\n#### Dependencies\n\nNode-Mailin can run without any dependencies other than node itself, but having them allow you to use some additional features.\n\nSo first make sure the node is available, and the `node` command as well. On Debian/Ubuntu boxes:\n\n```\nsudo aptitude install nodejs ; sudo ln -s $(which nodejs) /usr/bin/node\n```\n\nTo 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:\n\nSpamassassin is not enabled by default, enable it in with update-rc.d spamassassin enable command.\n\n```bash\nsudo aptitude install spamassassin spamc\nsudo update-rc.d spamassassin enable\nsudo service spamassassin start\n```\n\n\n#### Node versions\n\nCurrent LTS and LTS+ versions.\n\n#### The crux: setting up your DNS correctly\n\nIn 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 `*@subdomain.domain.com`:\n\n- First an MX record: `subdomain.domain.com MX 10 mxsubdomain.domain.com`. This means that the mail server for addresses like `*@subdomain.domain.com` will be `mxsubdomain.domain.com`.\n- Then an A record: `mxsubdomain.domain.com A the.ip.address.of.your.Node-Mailin.server`. This tells at which ip address the mail server can be found.\n\nYou can fire up Node-Mailin (see next section) and use an [smtp server tester](http://mxtoolbox.com/diagnostic.aspx) to verify that everything is correct.\n\n### Using Node-Mailin\n\n#### From the command line\n\nInstall Node-Mailin globally.\n\n```\nsudo npm install -g node-mailin\n```\n\nRun 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.\n\nPorts number under 1000 are reserved to root user. So two options here. Either run Node-Mailin as root:\n\n```\nsudo node-mailin --port 25\n```\n\nOr, prefered choice, use something like `authbind` to run Node-Mailin with a standard user while still using port 25.\nHere comes a [tutorial on how to setup authbind](http://respectthecode.tumblr.com/post/16461876216/using-authbind-to-run-node-js-on-port-80-with-dreamhost). In this case, do something like:\n\n```\nauthbind --deep node-mailin --port 25\n```\n\nand make sure that your user can write to the log file.\n\nAt this point, Node-Mailin will listen for incoming emails, parse them, Then you can store them wherever you want.\n\n##### Gotchas\n\n- `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](http://xkcd.com/149/).\n- `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](http://en.wikipedia.org/wiki/Message_transfer_agent) is already running. Stop it with something like `sudo service exim4 stop` or `sudo service postfix stop` before using Node-Mailin.\n- `error: Unable to compute spam score ECONNREFUSED`: it is likely that spamassassin is not enabled on your machine, check the `/etc/default/spamassassin` file.\n- `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.\n- `Uncaught SenderError: Mail from command failed - 450 4.1.8 \u003can@email.address\u003e: Sender address rejected: Domain not found`: The smtpOption `disableDNSValidation` is set to `false` and an email was sent from an invalid domain.\n\n#### Embedded inside a node application\n\nInstall node-mailin locally.\n\n```\nsudo npm install --save node-mailin\n```\n\nStart the node-mailin server and listen to events.\n\n```javascript\nconst nodeMailin = require(\"node-mailin\");\n\n/* Start the Node-Mailin server. The available options are:\n *  options = {\n *     port: 25,\n *     logFile: '/some/local/path',\n *     logLevel: 'warn', // One of silly, info, debug, warn, error\n *     smtpOptions: { // Set of options directly passed to simplesmtp.createServer(smtpOptions)\n *        SMTPBanner: 'Hi from a custom Node-Mailin instance',\n *        // By default, the DNS validation of the sender and recipient domains is disabled so.\n *        // You can enable it as follows:\n *        disableDNSValidation: false\n *     }\n *  };\n * parsed message. */\nnodeMailin.start({\n  port: 25\n});\n\n/* Access simplesmtp server instance. */\nnodeMailin.on(\"authorizeUser\", function(connection, username, password, done) {\n  if (username == \"johnsmith\" \u0026\u0026 password == \"mysecret\") {\n    done(null, true);\n  } else {\n    done(new Error(\"Unauthorized!\"), false);\n  }\n});\n\n/* Event emitted when the \"From\" address is received by the smtp server. */\nnodeMailin.on('validateSender', async function(session, address, callback) {\n    if (address == 'foo@bar.com') { /*blacklist a specific email adress*/\n        err = new Error('You are blocked'); /*Will be the SMTP server response*/\n        err.responseCode = 530; /*Will be the SMTP server return code sent back to sender*/\n        callback(err);\n    } else {\n        callback()\n    }\n});\n\n/* Event emitted when the \"To\" address is received by the smtp server. */\nnodeMailin.on('validateRecipient', async function(session, address, callback) {\n    console.log(address) \n    /* Here you can validate the address and return an error \n     * if you want to reject it e.g: \n     *     err = new Error('Email address not found on server');\n     *     err.responseCode = 550;\n     *     callback(err);*/\n    callback()\n});\n\n/* Event emitted when a connection with the Node-Mailin smtp server is initiated. */\nnodeMailin.on(\"startMessage\", function(connection) {\n  /* connection = {\n      from: 'sender@somedomain.com',\n      to: 'someaddress@yourdomain.com',\n      id: 't84h5ugf',\n      authentication: { username: null, authenticated: false, status: 'NORMAL' }\n    }\n  }; */\n  console.log(connection);\n});\n\n/* Event emitted after a message was received and parsed. */\nnodeMailin.on(\"message\", function(connection, data, content) {\n  console.log(data);\n  /* Do something useful with the parsed message here.\n   * Use parsed message `data` directly or use raw message `content`. */\n});\n\nnodeMailin.on(\"error\", function(error) {\n  console.log(error);\n});\n```\n\n##### Rejecting an incoming email\n\nYou can reject an incoming email when the **validateRecipient** or **validateSender** event gets called and you run the callback with an error (Can be anything you want, preferably an [actual SMTP server return code](https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes))\n```JavaScript\nnodeMailin.on('validateSender', async function(session, address, callback) {\n    if (address == 'foo@bar.com') {         /*blacklist a specific email adress*/\n        err = new Error('Email address was blacklisted'); /*Will be the SMTP server response*/\n        err.responseCode = 530;             /*Will be the SMTP server return code sent back to sender*/\n        callback(err);                      /*Run callback with error to reject the email*/\n    } else {\n        callback()                          /*Run callback to go to next step*/\n    }\n});\n```\n\n\n##### Events\n\n- **startData** _(connection)_ - DATA stream is opened by the client.\n- **data** _(connection, chunk)_ - E-mail data chunk is passed from the client.\n- **dataReady** _(connection, callback)_ - Client has finished passing e-mail data. `callback` returns the queue id to the client.\n- **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.\n- **validateSender** _(connection, email, callback)_ - Emitted if `validateSender` listener is set up.\n- **senderValidationFailed** _(connection, email, callback)_ - Emitted if a sender DNS validation failed.\n- **validateRecipient** _(connection, email, callback)_ - Emitted if `validateRecipients` listener is set up.\n- **recipientValidationFailed** _(connection, email, callback)_ - Emitted if a recipient DNS validation failed.\n- **close** _(connection)_ - Emitted when the connection to a client is closed.\n- **startMessage** _(connection)_ - Connection with the Node-Mailin smtp server is initiated.\n- **message** _(connection, data, content)_ - Message was received and parsed.\n- **error** _(error)_ - And Error Occured.\n\n### Todo\n\nwebhooks.\n\nDocs: [StackFame Tech Blog](https://stackfame.com/receive-inbound-emails-node-js)\n\n### Credits\n\n- Postman image copyright [Charlie Allen](http://charlieallensblog.blogspot.fr).\n- Heavily Inspired by mailin NPM Module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvithalreddy%2Fnode-mailin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvithalreddy%2Fnode-mailin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvithalreddy%2Fnode-mailin/lists"}