email-bounce-parser 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Crisp IM SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# Email Bounce Parser
+
+[![Test and Build](https://github.com/crisp-oss/email-bounce-parser/workflows/Test%20and%20Build/badge.svg?branch=master)](https://github.com/crisp-oss/email-bounce-parser/actions?query=workflow%3A%22Test+and+Build%22) [![Build and Release](https://github.com/crisp-oss/email-bounce-parser/workflows/Build%20and%20Release/badge.svg)](https://github.com/crisp-oss/email-bounce-parser/actions?query=workflow%3A%22Build+and+Release%22) [![NPM](https://img.shields.io/npm/v/email-bounce-parser.svg)](https://www.npmjs.com/package/email-bounce-parser) [![Downloads](https://img.shields.io/npm/dt/email-bounce-parser.svg)](https://www.npmjs.com/package/email-bounce-parser)
+
+Parses bounce emails and extracts details.
+
+**😘 Maintainer**: [@eliottvincent](https://github.com/eliottvincent)
+
+## Who uses it?
+
+<table>
+<tr>
+<td align="center"><a href="https://crisp.chat/"><img src="https://crisp.chat/favicon-256x256.png" height="64" /></a></td>
+</tr>
+<tr>
+<td align="center">Crisp</td>
+</tr>
+</table>
+
+_👋 You use this library and you want to be listed there? [Contact us](https://crisp.chat/)._
+
+## Features
+
+This library is used at [Crisp](https://crisp.chat/) everyday to parse bounce emails.
+It supports most variations of bounce emails (Postfix, Dovecat, Gmail, Outlook).
+
+## Usage
+
+```js
+const EmailBounceParse = require("email-bounce-parser");
+
+const result = new EmailBounceParse().read(MY_EMAIL_STRING);
+
+console.log(result);
+```
+
+## API
+
+### Parse a bounce email
+
+`read(body)` parses the bounce email and extracts available information (error code and type, server, original recipient, etc.):
+* `body` must be a string representing the bounce email body (as returned by [mailparser](https://github.com/nodemailer/mailparser), for example)
+
+```js
+const EmailBounceParse = require("email-bounce-parser");
+
+const result = new EmailBounceParse().read(MY_EMAIL_STRING);
+
+console.log(result);
+// {
+//   bounce: true,
+//
+//   email: {
+//     body: "This is the mail system at host mailer.acme.email [...] (in reply to RCPT TO command)",
+//     intro: "This is the mail system at host mailer.acme.email [...] The mail system",
+//     error: "<support@yipee.com>: host smtp.secureserver.net[92.240.81.0] said: [...] (in reply to RCPT TO command)"
+//   },
+//
+//   data: {
+//     error: {
+//       code: {
+//         basic: "550",
+//         enhanced: "5.1.1"
+//       },
+//       label: "<support@yipee.com> Recipient not found.",
+//
+//       type: "action_not_taken",
+//
+//       temporary: false,
+//       permanent: true,
+//
+//       data: {
+//         type: "no_such_user",
+//       }
+//     },
+//
+//     server: {
+//       hostname: "smtp.secureserver.net",
+//       ip: "92.240.81.0",
+//       port: "25"
+//     },
+//
+//     command: "RCPT TO"
+//   }
+// }
+```
+
+Head over to `/test/fixtures/` for more bounce examples and parsing results (anonymized data).
+
+## Contributing
+
+Feel free to fork this project and submit fixes. We may adapt your code to fit the codebase.
+
+You can run unit tests using:
+
+```
+npm test
+```
+
+## License
+
+email-bounce-parser is released under the MIT License. See the bundled LICENSE file for details.

package/lib/index.js

@@ -0,0 +1,59 @@
+"use strict";
+
+
+var Parser = require("./parser");
+
+
+/**
+ * EmailBounceParser
+ * @class
+ */
+class EmailBounceParser {
+  /**
+   * Constructor
+   */
+  constructor() {
+    this.parser = new Parser();
+  }
+
+  /**
+   * Attempts to parse a bounce email
+   * @public
+   * @param  {string} body
+   * @return {object} The parsed email
+   */
+  read(body) {
+    if (!body) {
+      return {
+        bounce : false
+      };
+    }
+
+    var _result = this.parser.parseBody(body);
+
+    var _data   = this.parser.parseBounceData(_result.body, _result.error)
+
+    return {
+      bounce  : true,
+
+      email   : {
+        body  : _result.body,
+        intro : _result.intro || null,
+        error : _result.error || null
+      },
+
+      data    : {
+        error     : _data.error,
+
+        recipient : _data.recipient,
+
+        server    : _data.server,
+        command   : _data.command
+      }
+    }
+  };
+};
+
+
+module.exports = EmailBounceParser;
+

package/lib/parser.js

@@ -0,0 +1,426 @@
+"use strict";
+
+
+var RE2                         = require("re2");
+var { loopRegexes, trimString } = require("./utils");
+
+var ERROR_CODES_TYPES = {
+  "421"        : "service_not_available",
+  "421 4.3.0"  : "temporary_system_problem",
+  "421 4.4.5"  : "server_busy",
+  "432 4.7.12" : "password_needed",
+  "450"        : "mailbox_unavailable",
+  "451"        : "local_error",
+  "452"        : "insufficient_system_storage",
+  "503"        : "bad_commands_sequence",
+  "550"        : "action_not_taken",
+  "550 5.1.1"  : "no_such_recipient",
+  "550 5.2.1"  : "recipient_disabled_or_recipient_rate_limited",
+  "550 5.7.1"  : "spam_content",
+  "554"        : "transaction_failed",
+  "554 5.7.1"  : "spam_content",
+};
+
+var REGEXES = {
+  line_break_double : /(\n\n)/gm,
+  carriage_return : /\r\n/gm,
+  byte_order_mark : /\uFEFF/gm,
+  trailing_non_breaking_space : /\u00A0$/gm,
+  non_breaking_space : /\u00A0/gm,
+  line_break_double_indent_single : /(\n\n\ {2})/gm,
+  line_break_single_indent_double : /(\n\ {4})/gm,
+  indent_long : /(\ {14,})/gm,
+
+  separator : [
+    /(The mail system)/m,
+    /(The following address\(es\) failed\:)/m
+  ],
+
+  command : [
+    /\(in reply to end of ([A-Z\s]+) command\)$/m, // 'end of' command
+    /\(in reply to ([A-Z\s]+) command\)$/m, // default
+    /timed out while sending ([A-Z\s]+)$/m, // command timed out
+    /error after ([A-Z\s]+)/m // 'after' command
+  ],
+
+  email_server : [
+    /host (\S+)\[([\d\.]+)\](?:\:(\d+)\:)? said/m,
+    /\: connect to (.+)\[(.+)\](?:\:(\d+)\:)?/m,
+    /Name service error for name\=(\S+)\s/m,
+    /RCPT TO\:\<(.+?)\>/m,
+    /Message rejected by\:\s+([\S\.]+?)$/m, // Outlook error
+    /from (\S+) \[([\d\.]+)\](?:\:(\d+)\:)?/m
+  ],
+
+  error : [
+    /said\: (\d{3}(?:[\s\-]\d\.\d\.\d\d?)?) (.+) \(in reply to/m,
+    /LMTP error after (?:.+?)\:\<.+?\>\: (\d{3}(?:[\s\-]\d\.\d\.\d\d?)?) <.+?\>(.+)$/m,
+    /Remote Server returned \'(\d{3}(?:[\s\-]\d\.\d\.\d\d?)?) (.+)\'/m,
+    /The response from the remote server was:\s(\d{3}(?:[\s\-]\d\.\d\.\d\d?)?) (.+)/m,
+    /Error\:\s*?(\d{3}(?:[\s\-]\d\.\d\.\d\d?)?) (.+)/m,
+    /reason: (\d{3}[\s\-]\d\.\d\.\d\d?) (.+)/m,
+    /(\d{3}[\s\-]\d\.\d\.\d\d?)/m
+  ],
+
+  recipient : [
+    /The following addresses had permanent fatal errors (?:.*?)\s\<(.+?)\>/,
+    /^\<(.+?)\>:/m,
+    /^(.+?)\s?\n?\s*[\[|<]mailto\:(.+?)[\]|>]/m,
+    /^Your message wasn't delivered to (.+?)\s/m,
+    /^Your message to (.+?) couldn\'t/m,
+    /\<(.+?)\>:/
+  ],
+
+  error_code : [
+    /(\d{3})[\s\-](\d\.\d\.\d)/,
+    /(\d{3})/
+  ],
+
+  mailbox_address : [
+    /^(([^\s@]+)@([^\s@]+)\.([^\s@]+))$/
+  ]
+};
+
+
+/**
+ * Parser
+ * @class
+ */
+class Parser {
+  /**
+   * Constructor
+   */
+  constructor() {
+    this.__regexes = {};
+
+    this.__initRegexes();
+  }
+
+
+  /**
+   * Parses the body of the email
+   * @public
+   * @param  {string} body
+   * @return {object} The result
+   */
+  parseBody(body) {
+    // Replace carriage return by regular line break
+    var _body = body.replace(this.__regexes.carriage_return, "\n");
+
+    // Remove Byte Order Mark
+    _body = _body.replace(this.__regexes.byte_order_mark, "");
+
+    // Remove trailing Non-breaking space
+    _body = _body.replace(this.__regexes.trailing_non_breaking_space, "");
+
+    // Replace Non-breaking space with regular space
+    _body = _body.replace(this.__regexes.non_breaking_space, " ");
+
+    var _match = loopRegexes(this.__regexes.separator, _body, "split");
+
+    if (_match && _match.length > 2) {
+      var _intro = trimString(_match[0] + _match[1]),
+        _error = trimString(_match[2]);
+
+      // Flatten intro?
+      if (this.__lineLengthRestricted(_intro, 75)) {
+        _intro = this.__flattenText(_intro);
+      }
+
+      // Flatten error?
+      if (this.__lineLengthRestricted(_error, 80)) {
+        _error = this.__flattenText(_error);
+      }
+
+      _body = _intro + "\n\n" + _error;
+
+      return {
+        body    : _body,
+        intro   : _intro,
+        error   : _error
+      };
+    }
+
+    return {
+      body : trimString(_body)
+    };
+  }
+
+
+  /**
+   * Parses the bounce email data
+   * @public
+   * @param  {string} body
+   * @param  {string} [error]
+   * @return {object} The parsed data
+   */
+  parseBounceData(body, error=null) {
+    var _str = error || body;
+
+    return {
+      error     : this.__parseBounceDataError(_str),
+      recipient : this.__parseBounceDataRecipient(_str),
+
+      server    : this.__parseBounceDataEmailServer(_str),
+      command   : this.__parseBounceDataCommand(_str)
+    };
+  }
+
+
+  /**
+   * Initializes regexes
+   * @private
+   * @return {undefined}
+   */
+  __initRegexes() {
+    for (var _key in REGEXES) {
+      var _key_line = `${_key}_line`;
+      var _entry    = REGEXES[_key];
+
+      if (Array.isArray(_entry)) {
+        this.__regexes[_key]      = [];
+        this.__regexes[_key_line] = [];
+
+        for (var _i = 0; _i < _entry.length; _i++) {
+          var _regex = _entry[_i];
+
+          this.__regexes[_key].push(
+            new RE2(_regex)
+          );
+        }
+      } else {
+        var _regex = _entry;
+
+        this.__regexes[_key] = new RE2(_regex);
+      }
+    }
+  }
+
+
+  /**
+   * Parses the bounce error
+   * @private
+   * @param  {string} str
+   * @return {object} The bounce error
+   */
+  __parseBounceDataError(str) {
+    var _code = {
+      basic    : null,
+      enhanced : null
+    },
+      _label = null,
+      _temporary = false,
+      _permanent = false;
+
+    var _match = loopRegexes(this.__regexes.error, str, "match", false);
+
+    if (_match && _match.length > 1) {
+      _code  = this.__parseErrorCode(_match[1]);
+      _label = trimString(_match[2]);
+    }
+
+    // Check temporary / permanent
+    if (_code.basic[0] === "4") {
+      _temporary = true;
+    } else if (_code.basic[0] === "5") {
+      _permanent = true;
+    }
+
+    // Extract further data
+    var _data = this.__parseErrorData(str, _code, _label);
+
+    return {
+      code      : _code,
+      label     : _label,
+
+      type      : ERROR_CODES_TYPES[(_code || {}).basic],
+
+      temporary : _temporary,
+      permanent : _permanent,
+
+      data      : _data
+    }
+  }
+
+
+  /**
+   * Parses the error code
+   * @private
+   * @param  {string} code
+   * @return {object} The error code
+   */
+  __parseErrorCode(code) {
+    var _basic = null,
+      _enhanced = null;
+
+    var _match = loopRegexes(this.__regexes.error_code, code);
+
+    if (_match && _match.length > 1) {
+      _basic = _match[1];
+      _enhanced = _match[2] || null;
+    }
+
+    // Basic code is the enhanced code? This is wrong and should be fixed
+    if (_basic === "511") {
+      _basic = "550";
+      _enhanced = "5.1.1";
+    }
+
+    return {
+      basic    : _basic,
+      enhanced : _enhanced
+    }
+  }
+
+
+  /**
+   * Parses the error data
+   * @private
+   * @param  {string} str
+   * @param  {object} code
+   * @param  {string} label
+   * @return {object} The error data
+   */
+  __parseErrorData(str, code, label) {
+    var _type = null;
+
+    if (code.basic && code.enhanced) {
+      _type = ERROR_CODES_TYPES[`${code.basic} ${code.enhanced}`] || null;
+    }
+
+    return {
+      type : _type
+    }
+  }
+
+
+  /**
+   * Parses the recipient
+   * @private
+   * @param  {string} str
+   * @return {object} The recipient email address
+   */
+  __parseBounceDataRecipient(str) {
+    var _recipient = null;
+
+    var _match = loopRegexes(this.__regexes.recipient, str);
+
+    if (_match && _match.length > 1) {
+      _recipient = trimString(_match[1]);
+    }
+
+    return _recipient;
+  }
+
+
+  /**
+   * Parses the email server
+   * @private
+   * @param  {string} str
+   * @return {object} The email server
+   */
+  __parseBounceDataEmailServer(str) {
+    var _hostname = null,
+      _ip = null,
+      _port = null;
+
+    var _match = loopRegexes(this.__regexes.email_server, str);
+
+    if (_match && _match.length > 1) {
+      _hostname = this.__parseHostname(_match[1]);
+      _ip       = _match[2] || null;
+      _port     = _match[3] || null;
+    }
+
+    return {
+      hostname : _hostname,
+      ip       : _ip,
+      port     : _port || null
+    }
+  }
+
+
+  /**
+   * Parses the server hostname
+   * @private
+   * @param  {string} hostname
+   * @return {object} The server hostname
+   */
+  __parseHostname(hostname) {
+    if (hostname.includes("@")) {
+      return hostname.split("@")[1];
+    }
+
+    return hostname;
+  }
+
+
+  /**
+   * Parses the command
+   * @private
+   * @param  {string} str
+   * @return {object} The parsed command
+   */
+  __parseBounceDataCommand(str) {
+    var _command = null;
+
+    var _match = loopRegexes(this.__regexes.command, str);
+
+    if (_match && _match.length > 1) {
+      _command = _match[1];
+    }
+
+    return _command;
+  }
+
+
+  /**
+   * Checks whether line length is restricted
+   * @private
+   * @param  {string}  str
+   * @param  {string}  length
+   * @return {boolean} Whether line length is restricted or not
+   */
+  __lineLengthRestricted(str, length) {
+    var _lines = str.split("\n");
+
+    for (var _i = 0; _i < _lines.length; _i++) {
+      var _line = _lines[_i];
+
+      // Skip lines with URL, as they are usually not restricted in length
+      if (_line.length > length && !_line.includes("http")) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+
+  /**
+   * Flattens text
+   * @private
+   * @param  {string} str
+   * @return {string} Flattened text
+   */
+  __flattenText(str) {
+    var _str = str;
+
+    // Replace Line-break followed by double indent with regular space
+    _str = _str.replace(this.__regexes.line_break_single_indent_double, " ");
+
+    // Replace double Line-break followed by single indent with double Line-break
+    _str = _str.replace(this.__regexes.line_break_double_indent_single, "\n\n");
+
+    // Replace single Line-break with regular space
+    _str = _str.replace(/(?<!\n)\n(?!\n)/gm, " ");
+
+    // Replace long indent with double Line-break
+    _str = _str.replace(this.__regexes.indent_long, "\n\n");
+
+    return _str;
+  }
+}
+
+
+module.exports = Parser;

package/lib/utils.js

@@ -0,0 +1,108 @@
+"use strict";
+
+/**************************************************************************
+ * IMPORTS
+ ***************************************************************************/
+
+var RE2 = require("re2");
+
+/**************************************************************************
+ * FUNCTIONS
+ ***************************************************************************/
+
+/**
+ * Executes multiple regular expressions until one succeeds
+ * @public
+ * @param  {object}  regexes
+ * @param  {string}  str
+ * @param  {string}  [mode]
+ * @param  {boolean} [highestPosition]
+ * @return {object}  The result of the first successfull regular expression
+ */
+var loopRegexes = function(
+  regexes, str, mode = "match", highestPosition = true
+) {
+  var _match;
+
+  for (var _i = 0; _i < regexes.length; _i++) {
+    var _regex = regexes[_i];
+
+    if (typeof regexes[_i] === "string") {
+      // Build the regex
+      _regex = new RE2(regexes[_i]);
+    }
+
+    var _currentMatch = (
+      _regex[mode](str || "", mode === "replace" ? "" : undefined)
+    );
+
+    if (mode === "replace") {
+      _match = _currentMatch;
+
+      // A successfull replace must return a smaller string than the input
+      var _maxLength = str.length;
+
+      if (_match.length < _maxLength) {
+        break;
+      }
+    } else if (mode === "split" || mode === "match") {
+      // A successfull split must return an array with at least two items
+      var _minLength = mode === "split" ? 1 : 0;
+
+      if ((_currentMatch || []).length > _minLength) {
+        if (highestPosition === true) {
+          // No previous match?
+          if (!_match) {
+            // Save match and continue looking for other matches
+            _match = _currentMatch;
+          } else {
+            var _higher;
+
+            if (mode === "match") {
+              _higher = _match.index > _currentMatch.index;
+            } else if (mode === "split") {
+              _higher = _match[0].length > _currentMatch[0].length;
+            }
+
+            // Match positioned higher than previous one?
+            if (_higher) {
+              // Replace match and continue looking for other matches
+              _match = _currentMatch;
+            }
+          }
+        } else {
+          // Save match and stop
+          _match = _currentMatch;
+
+          break;
+        }
+      }
+    }
+  }
+
+  return (_match || []);
+}
+
+
+/**
+ * Trims a string
+ * @public
+ * @param  {string} str
+ * @return {string} The trimed string
+ */
+var trimString = function(str) {
+  return ((str || "").trim() || null)
+}
+
+
+/**************************************************************************
+ * EXPORTS
+ ***************************************************************************/
+
+exports.loopRegexes = loopRegexes;
+exports.trimString  = trimString;
+
+exports.default = {
+  loopRegexes : loopRegexes,
+  trimString  : trimString
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "email-bounce-parser",
+  "version": "1.0.1",
+  "description": "Parses bounce emails and extract errors",
+  "author": "Eliott Vincent <eliott@crisp.chat>",
+  "main": "lib/index.js",
+  "homepage": "https://github.com/crisp-oss/email-bounce-parser",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/crisp-oss/email-bounce-parser"
+  },
+  "bugs": {
+    "url": "https://github.com/crisp-oss/email-bounce-parser/issues"
+  },
+  "engineStrict": true,
+  "engines": {
+    "node": ">=14.18.0"
+  },
+  "scripts": {
+    "test": "nodeunit ./test/index.js"
+  },
+  "devDependencies": {
+    "nodeunit-x": "0.15.0"
+  },
+  "dependencies": {
+    "re2": "1.20.1"
+  },
+  "keywords": [
+    "parser",
+    "mail",
+    "email",
+    "bounce",
+    "bounces"
+  ],
+  "license": "MIT"
+}