mailparser - npm Package Compare versions

Comparing version 0.1.2 to 0.2.0

package.json

 {
     "name": "mailparser",
     "description": "Asynchronous and non-blocking parser for mime encoded e-mail messages",
-    "version": "0.1.2",
+    "version": "0.2.0",
     "author" : "Andris Reinman",
@@ -12,25 +12,19 @@ "maintainers":[
     ],
-
     "repository" : {
         "type" : "git",
-        "url" : "http://github.com/andris9/mailparser"
+        "url" : "http://github.com/andris9/mailparser.git"
     },
-
-    "main" : "./mailparser",
+    "main" : "./lib/mailparser",
     "licenses" : [
         {
-            "type": "BSD",
+            "type": "MIT",
             "url": "http://github.com/andris9/mailparser/blob/master/LICENSE"
         }
     ],
-    "dependencies":{
+    "dependencies": {
+        "mimelib": "0.1.7",
         "iconv": "*"
     },
-    "devDependencies":{
-        "expresso": "*"
-    },
-    "scripts":{
-        "test": "expresso test/*.js"
-    },
+    "engines": ["node >=0.6.0"],
     "keywords": ["e-mail", "mime", "parser"]
-}
+}

README.md

@@ -1,11 +0,17 @@
-mailparser
+
+
+MailParser
 ==========
 
-**mailparser** is an asynchronous and non-blocking parser for [node.js](http://nodejs.org) to parse mime encoded e-mail messages. Handles even large
-attachments with ease - attachments are parsed in chunks that can be saved into disk or sent to database while parsing (tested with 16MB attachments).
+**NB!** This version of MailParser is incompatible with pre 0.2.0, do not upgrade from 0.1.x without updating your code, the API is totally different. Also if the source is coming directly from SMTP you need to unescape dots in the beginning of the lines yourself!
 
-**mailparser** parses raw source of e-mail messages to convert mime-stream into a structured object.
 
-No need to worry about charsets or decoding *quoted-printable* or *base64* data, *mailparser* (with the help of *node-iconv*) does all of it for you. All the textual output from *mailparser* (subject line, addressee names, message body) is always UTF-8.
 
+**MailParser** is an asynchronous and non-blocking parser for [node.js](http://nodejs.org) to parse mime encoded e-mail messages. Handles even large
+attachments with ease - attachments can be parsed in chunks and streamed if needed.
+
+**MailParser** parses raw source of e-mail messages into a structured object.
+
+No need to worry about charsets or decoding *quoted-printable* or *base64* data, **MailParser** (with the help of *node-iconv*) does all of it for you. All the textual output from **MailParser** (subject line, addressee names, message body) is always UTF-8.
+
 Installation
@@ -19,118 +25,144 @@ ------------
 
-Create a new *mailparser* object
+Require MailParser module
 
-    var MailParser = require("mailparser").MailParser,
-        mp = new MailParser();
+    var MailParser = require("mailparser").MailParser;
     
-Set up listener for different events
+Create a new MailParser object
 
-  * Get mail headers as a structured object
+    var mailparser = new MailParser();
+
+MailParser object is a writable Stream - you can pipe directly files etc. to it
+or you can send new chunks with `mailparser.write`
     
-        mp.on("headers", function(headers){
-            console.log(headers);
-        });
-  
-  * Get mail body as a structured object
+When the parsing ends an 'end' event is emitted which has an object with parsed e-mail.
+
+    mailparser.on("end", function(mail){
+        mail; // object structure for parsed e-mail
+    });
+
+### Parsed mail object
+
+  * **headers** - an array of headers, in the form of - `[{key: "key", value: "value"}]`
+  * **from** - an array of parsed `From` addresses - `[{address:'[e-mail]',name:'Sender Name'}]`
+  * **to** - an array of parsed `To` addresses
+  * **subject** - the subject line
+  * **text** - text body
+  * **html** - html body
+  * **alternatives** - an array of alternative bodies in addition to the default `html` and `text` - `[{contentType:"text/plain", content: "..."}]`
+  * **attachments** - an array of attachments
     
-        mp.on("body", function(body){
-            console.log(body);
-        });
-  
-  * Get info about binary attachment that is about to start streaming
+### Decode a simple e-mail
+
+This example decodes an e-mail from a string
+
+    var MailParser = require("mailparser").MailParser,
+        mailparser = new MailParser();
+
+    var email = "From: 'Sender Name' <[e-mail]>\r\n"+
+                "To: 'Receiver Name' <[e-mail]>\r\n"+
+                "Subject: Hello world!\r\n"+
+                "\r\n"+
+                "How are you today?";
     
-        mp.on("astart", function(id, headers){
-            console.log("attachment id" + id + " started");
-            console.log(headers);
-        });
-  
-  * Get part of a binary attachment in the form of a Buffer
+    // setup an event listener when the parsing finishes
+    mailparser.on("end", function(mail_object){
+        console.log("From:", mail_object.from); //[{address:'[e-mail]',name:'Sender Name'}]
+        console.log("Subject:", mail_object.subject); // Hello world!
+        console.log("Text body:", mail_object.text); // How are you today?
+    });
     
-        mp.on("astream", function(id, buffer){
-            console.log("attachment id" + id);
-            console.log(buffer);
-        });
-  
-  * Attachment parsing completed
-  
-        mp.on("aend", function(id){
-            console.log("attachment " + id + " finished");
-        });
+    // send the email source to the parser
+    mailparser.write(email);
+    mailparser.end();
 
-Feed the parser with data
+### Pipe file to MailParser
 
-    mp.feed(part1_of_the_message);
-    mp.feed(part2_of_the_message);
-    mp.feed(part3_of_the_message);
-    ...
-    mp.feed(partN_of_the_message);
+This example pipes a `readableStream` file to **MailParser**
 
-Finish the feeding
-
-    mp.end();
+    var MailParser = require("mailparser").MailParser,
+        mailparser = new MailParser(),
+        fs = require("fs");
     
-Outcome
--------
+    mailparser.on("end", function(mail_object){
+        console.log("Subject:", mail_object.subject);
+    });
+    
+    fs.createReadStream("email.eml").pipe(mailparser);
 
-Parser returns the headers object with *"header"* event and it's structured like this
+### Attachments
 
-    { useMime: true
-    , contentType: 'multipart/alternative'
-    , charset: 'us-ascii'
-    , format: 'fixed'
-    , multipart: true
-    , mimeBoundary: 'Apple-Mail-2-1061547935'
-    , messageId: '[e-mail]'
-    , messageDate: 1286458909000
-    , receivedDate: 1286743827944
-    , contentTransferEncoding: '7bit'
-    , addressesFrom: 
-       [ { address: '[e-mail]'
-         , name: 'Andris Reinman'
-         }
-       ]
-    , addressesReplyTo: []
-    , addressesTo: [ { address: '[e-mail]', name: false } ]
-    , addressesCc: []
-    , subject: 'Simple test message with special characters like  \u0161 and \u00f5'
-    , priority: 3
-    }
+By default any attachment found from the e-mail will be included fully in the
+final mail structure object as Buffer objects. With large files this might not
+be desirable so optionally it is possible to redirect the attachments to a Stream
+and keep only the metadata about the file in the mail structure.
 
-Message body is returned with the *"body"* event and is structured like this
+    mailparser.on("end", function(mail_object){
+        for(var i=0; i<mail_object.attachments.length; i++){
+            console.log(mail_object.attachments[i].fileName);
+        }
+    });
 
-    { bodyText: 'Mail message as plain text',
-    , bodyHTML: 'Mail message as HTML',
-    , bodyAlternate: ["list of additional text/* and multipart/* parts of the message"],
-    , attachments: ["list of attachments"]
-    }
+#### Default behavior
 
-Attachments are included full size in the *body* object if the attachments are textual. Binary attachments
-are sent to the client as a stream that can be saved into disk if needed (events *"astream"* and *"aend"*), only the attachment meta-data is included in the *body* object this way.
+By default attachments will be included in the attachment objects as Buffers.
 
-See *test.js* for an actual usage example (parses the source from *mail.txt* and outputs to console)
+    attachments = [{
+        contentType: 'image/png',
+        fileName: 'image.png',
+        contentDisposition: 'attachment',
+        contentId: '5.1321281380971@localhost',
+        transferEncoding: 'base64',
+        length: 126,
+        generatedFileName: 'image.png',
+        checksum: 'e4cef4c6e26037bcf8166905207ea09b',
+        content: <Buffer ...>
+    }];
 
-    node test.js
+The property `generatedFileName` is usually the same but if several different
+attachments with the same name exist, the latter ones names will be modified and
+the generated name will be saved to `generatedFileName`
 
-You need to install node-iconv before running the test!
+    file.txt
+    file-1.txt
+    file-2.txt
+    ...
 
-NB!
----
+Property `content` is always a Buffer object (or SlowBuffer on some occasions)
 
-Messages with attachments are typically formatted as *nested multipart* messages. This means that the *bodyText* and *bodyHTML*
-fields might be left blank. Search for an alternate with content-type *multipart* from the bodyAlternate array and use the bodyText and bodyHTML defined there instead.
+#### Attachment streaming
 
-Feeding Non-SMTP Data
----------------------
+Attachment streaming can be used when providing an optional options parameter
+to the `MailParser` constructor.
 
-By default MailParser assumes an SMTP feed with "." at the start of the line
-replaced with "..". To disable this feature pass the following option to the
-constructor:
+    var mp = new MailParser({
+        streamAttachments: true
+    }
 
-    var mp = new MailParser({fix_smtp_escapes: 0});
+This way there will be no `content` property on final attachment objects (but the other fields will remain).
 
-The default is to fixup those escape sequences, which isn't what you want if
-you already have a mail file on disk, or have already fixed those escapes up.
+To catch the streams you should listen for `attachment` events on the MailParser
+object. The parameter provided includes file information (`contentType`, 
+`fileName`, `contentId`) and a readable Stream object `stream`.
 
-LICENSE
--------
+    var mp = new MailParser({
+        streamAttachments: true
+    }
+    
+    mp.on("attachment", function(attachment){
+        var output = fs.createWriteStream(attachment.fileName);
+        attachment.stream.pipe(output);
+    });
 
-**BSD**
+In this case the `fileName` parameter is equal to `generatedFileName` property
+on the main attachment object, you match attachment streams to the main attachment
+objects through these values.
+
+#### Testing attachment integrity
+
+Attachment objects include `length` property which is the length of the attachment
+in bytes and `checksum` property which is md5 hash of the file.
+
+
+## License
+
+**MIT**

New alerts

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

New author

Supply chain risk

A new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.

Found 1 instance in 1 package

Mixed license

License

(Experimental) Package contains multiple licenses.

Found 1 instance in 1 package

Fixed alerts

Non-existent author

Supply chain risk

The package was published by an npm account that no longer exists.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

2771564

increased by4302.94%

Dev dependency count

0

decreased by-100%

Number of package files

31

increased by210%

Lines of code

2191

increased by69.98%

Number of lines in readme file

167

increased by22.79%

Number of high supply chain risk alerts

0

decreased by-100%

Worsened metrics

Dependency count

2

increased by100%

Number of low license alerts

1

increased byInfinity%

Number of low supply chain risk alerts

2

increased by100%

Number of medium supply chain risk alerts

8

increased byInfinity%

Dependency changes

• + Addedmimelib@0.1.7

• + Addedmimelib@0.1.7(transitive)