nodemailer - npm Package Compare versions

Comparing version 0.2.4 to 0.3.0

examples/example_ses.js

 var nodemailer = require('../lib/mail');
 
-// Set up SES settings
-nodemailer.SES = {
-	AWSAccessKeyID: "AKIAEXAMPLE",
-	AWSSecretKey: "ZEXAMPLE"
-};
+// Create an Amazon SES transport object
+var transport = new nodemailer.Transport("SES", {
+        AWSAccessKeyID: "AWSACCESSKEY",
+        AWSSecretKey: "/AWS/SECRET",
+        ServiceUrl: "https://email.us-east-1.amazonaws.com" // optional
+    });
+
 console.log('SES Configured');
 
-// unique cid value for the embedded image
-var cid = Date.now() + '.image.png';
-
 // Message object
 var message = {
-    sender: '"Sender Name" <[e-mail]>',
-    to: '"Receiver Name" <[e-mail]>',
-    subject: 'Nodemailer is unicode friendly ✔',
+    
+    // define transport to deliver this message
+    transport: transport, 
+    
+    // sender info
+    from: 'Sender Name <[e-mail]>',
+    
+    // Comma separated list of recipients
+    to: '"Receiver Name" <[e-mail]>',
+    
+    // Subject of the message
+    subject: 'Nodemailer is unicode friendly ✔', //
 
-    body: 'Hello to myself!',
-    html:'<p><b>Hello</b> to myself <img src="cid:' + cid + '"/></p>',
-    debug: true,
+    // plaintext body
+    text: 'Hello to myself!',
+    
+    // HTML body
+    html:'<p><b>Hello</b> to myself <img src="cid:note@node"/></p>'+
+         '<p>Here\'s a nyan cat for you as an embedded attachment:<br/><img src="cid:nyan@node"/></p>',
+    
+    // An array of attachments
     attachments:[
+        
+        // String attachment
         {
-            filename: 'notes.txt',
-            contents: 'Some notes about this e-mail'
+            fileName: 'notes.txt',
+            contents: 'Some notes about this e-mail',
+            contentType: 'text/plain' // optional, would be detected from the filename
         },
+        
+        // Binary Buffer attachment
         {
-            filename: 'image.png',
+            fileName: 'image.png',
             contents: new Buffer('iVBORw0KGgoAAAANSUhEUgAAABAAAAAQAQMAAAAlPW0iAAAABlBMVEUAAAD/' +
                                  '//+l2Z/dAAAAM0lEQVR4nGP4/5/h/1+G/58ZDrAz3D/McH8yw83NDDeNGe4U' +
                                  'g9C9zwz3gVLMDA/A6P9/AFGGFyjOXZtQAAAAAElFTkSuQmCC', 'base64'),
-            cid: cid
+            
+            cid: 'note@node' // should be as unique as possible
+        },
+        
+        // File Stream attachment
+        {
+            fileName: 'nyancat.gif',
+            filePath: __dirname+"/nyan.gif",
+            cid: 'nyan@node' // should be as unique as possible
         }
@@ -37,4 +63,5 @@ ]
 
-// Callback to be run after the sending is completed
-var callback = function(error, success){
+console.log('Sending Mail');
+
+nodemailer.send_mail(message, function(error){
     if(error){
@@ -45,28 +72,3 @@ console.log('Error occured');
     }
-    if(success){
-        console.log('Message sent successfully!');
-    }else{
-        console.log('Message failed, reschedule!');
-    }
-};
-
-console.log('Sending Mail');
-
-// Catch uncaught errors
-process.on('uncaughtException', function(e){
-    console.log('Uncaught Exception', e.stack);
-});
-
-// Send the e-mail
-var mail;
-try{
-    mail = nodemailer.send_mail(message, callback);
-}catch(e) {
-    console.log('Caught Exception',e);
-}
-
-var oldemit = mail.emit;
-mail.emit = function(){
-    console.log('Mail.emit', arguments);
-    oldemit.apply(mail, arguments);
-};
+    console.log('Message sent successfully!');
+});

examples/example_smtp.js

 var nodemailer = require('../lib/mail');
 
-// Set up SMTP server settings
-nodemailer.SMTP = {
-    host: 'smtp.gmail.com',
-    port: 465,
-    use_authentication: true,
-    ssl: true,
-    user: undefined,
-    pass: undefined,
-    debug: true
-};
+// Create a SMTP transport object
+var transport = new nodemailer.Transport("SMTP", {
+        service: 'Gmail', // use well known service
+        auth: {
+            user: "[e-mail]",
+            pass: "Nodemailer123"
+        }
+    });
 
 console.log('SMTP Configured');
-// unique cid value for the embedded image
-var cid = Date.now() + '.image.png';
 
 // Message object
 var message = {
-    sender: 'Sender Name <[e-mail]>',
-    to: '"Receiver Name" <[e-mail]>',
-    subject: 'Nodemailer is unicode friendly ✔',
+    
+    // define transport to deliver this message
+    transport: transport, 
+    
+    // sender info
+    from: 'Sender Name <[e-mail]>',
+    
+    // Comma separated list of recipients
+    to: '"Receiver Name" <[e-mail]>',
+    
+    // Subject of the message
+    subject: 'Nodemailer is unicode friendly ✔', //
 
-    body: 'Hello to myself!',
-    html:'<p><b>Hello</b> to myself <img src="cid:' + cid + '"/></p>',
-    debug: true,
+    headers: {
+        'X-Laziness-level': 1000,
+    },
+
+    // plaintext body
+    text: 'Hello to myself!',
+    
+    // HTML body
+    html:'<p><b>Hello</b> to myself <img src="cid:note@node"/></p>'+
+         '<p>Here\'s a nyan cat for you as an embedded attachment:<br/><img src="cid:nyan@node"/></p>',
+    
+    // An array of attachments
     attachments:[
+        
+        // String attachment
         {
-            filename: 'notes.txt',
-            contents: 'Some notes about this e-mail'
+            fileName: 'notes.txt',
+            contents: 'Some notes about this e-mail',
+            contentType: 'text/plain' // optional, would be detected from the filename
         },
+        
+        // Binary Buffer attachment
         {
-            filename: 'image.png',
+            fileName: 'image.png',
             contents: new Buffer('iVBORw0KGgoAAAANSUhEUgAAABAAAAAQAQMAAAAlPW0iAAAABlBMVEUAAAD/' +
                                  '//+l2Z/dAAAAM0lEQVR4nGP4/5/h/1+G/58ZDrAz3D/McH8yw83NDDeNGe4U' +
                                  'g9C9zwz3gVLMDA/A6P9/AFGGFyjOXZtQAAAAAElFTkSuQmCC', 'base64'),
-            cid: cid
+            
+            cid: 'note@node' // should be as unique as possible
+        },
+        
+        // File Stream attachment
+        {
+            fileName: 'nyan cat ✔.gif',
+            filePath: __dirname+"/nyan.gif",
+            cid: 'nyan@node' // should be as unique as possible
         }
@@ -42,4 +69,4 @@ ]
 
-// Callback to be run after the sending is completed
-var callback = function(error, success){
+console.log('Sending Mail');
+nodemailer.sendMail(message, function(error){
     if(error){
@@ -50,28 +77,4 @@ console.log('Error occured');
     }
-    if(success){
-        console.log('Message sent successfully!');
-    }else{
-        console.log('Message failed, reschedule!');
-    }
-};
-
-console.log('Sending Mail');
-
-// Catch uncaught errors
-process.on('uncaughtException', function(e){
-    console.log('Uncaught Exception', e.stack);
-});
-
-// Send the e-mail
-var mail;
-try{
-    mail = nodemailer.send_mail(message, callback);
-}catch(e) {
-    console.log('Caught Exception',e);
-}
-
-var oldemit = mail.emit;
-mail.emit = function(){
-    console.log('Mail.emit', arguments);
-    oldemit.apply(mail, arguments);
-};
+    console.log('Message sent successfully!');
+    transport.close(); // close the connection pool
+});

lib/engines/sendmail.js

@@ -1,30 +0,38 @@
-var exec;
+var spawn = require('child_process').spawn;
 
-try{
-    exec = require('child_process').exec;
-}catch(E){
-    // probably on Windows Node.js v0.5.0 - v0.5.2
+// Expose to the world
+module.exports = SendmailTransport;
+
+/**
+ * <p>Generates a Transport object for Sendmail</p>
+ * 
+ * @constructor
+ * @param {String} [config] path to the sendmail command
+ */
+function SendmailTransport(config){
+    this.path = typeof config=="string"?config:"sendmail";
 }
 
-exports.send = function(emailMessage, config, callback) {
-    emailMessage.prepareVariables();
+/**
+ * <p>Spawns a <code>'sendmail -t'</code> command and streams the outgoing
+ * message to sendmail stdin. Return callback checks if the sendmail process
+ * ended with 0 (no error) or not.</p>
+ * 
+ * @param {Object} emailMessage MailComposer object
+ * @param {Function} callback Callback function to run when the sending is completed
+ */
+SendmailTransport.prototype.sendMail = function(emailMessage, callback) {
+
+    // sendmail strips this header line by itself
+    emailMessage.options.keepBcc = true;
     
-    if(!exec){
-        return callback && callback(new Error("No support for child processes in this version of Node.JS, use SMTP instead"));
-    }
+    var sendmail = spawn(this.path, ["-t"]);
     
-    var headers = emailMessage.generateHeaders(),
-        body = emailMessage.generateBody();
+    sendmail.on('exit', function (code) {
+        callback(code?new Error("Sendmail exited with "+code):null, {});
+    });
     
-    var path = typeof config=="string"?config:"sendmail";
-    exec('echo "'+(headers+"\r\n\r\n"+body).replace(/"/g,'\\"')+'" | '+path+" -t", function(error){
-        process.nextTick(function(){
-            if(error){
-                callback && callback(error, null);
-            }else{
-                callback && callback(null, true);
-            }
-        });
-    });
-    return;
-};
+    emailMessage.pipe(sendmail.stdin);
+    emailMessage.streamMessage();
+    
+};

package.json

 {
     "name": "nodemailer",
     "description": "Easy to use module to send e-mails, supports unicode and SSL/TLS",
-    "version": "0.2.4",
+    "version": "0.3.0",
     "author" : "Andris Reinman",
@@ -12,3 +12,3 @@ "maintainers":[
     ],
-    "homepage": "http://www.nodemailer.org",
+    "homepage": "http://github.com/andris9/nodemailer",
     "repository" : {
@@ -18,3 +18,6 @@ "type" : "git",
     },
-    "main" : "./lib/mail",
+    "scripts":{
+        "test": "node ./run_tests.js"
+    },
+    "main" : "./lib/nodemailer",
     "licenses" : [
@@ -27,6 +30,12 @@ {
     "dependencies": {
-        "mimelib-noiconv":"*"
+        "mailcomposer": "*",
+        "simplesmtp": "*"
     },
-    "engine": [ "node >=0.3.0" ],
-    "keywords": ["e-mail", "mime", "email", "sendmail"]
+    "devDependencies": {
+        "nodeunit": "*"
+    },
+    "engine": {
+        "node": ">=0.5"
+    },
+    "keywords": ["e-mail", "mime", "email", "sendmail", "ses"]
 }

README.md

 Nodemailer
 ==========
 
-**Nodemailer** is an easy to use module to send e-mails with Node.JS (using SMTP or sendmail) and it's Unicode friendly - You can use any characters you like ✔
+**Nodemailer** is an easy to use module to send e-mails with Node.JS (using 
+SMTP or sendmail) and is unicode friendly - You can use any characters you like ✔
 
-Nodemailer supports
--------------------
+This version of Nodemailer is built from scratch and might break some existing scripts, so beware while upgrading.
 
-  - **Unicode** to use any characters
-  - **HTML content** as well as **plain text** alternative
-  - **Attachments**
-  - **Embedded images** in HTML
-  - **SSL/TLS** for secure e-mail delivery
-  - **SMTP**, **sendmail** and **Amazon SES**
+[Autogenerated docs](http://www.node.ee/maildoc/)
 
-Installation
-------------
+Use [DocumentUp](http://documentup.com/andris9/nodemailer/) to read this README
+in a more structured way (with TOC).
 
-Install through *NPM*
+[![Build Status](https://secure.travis-ci.org/andris9/Nodemailer.png)](http://travis-ci.org/andris9/Nodemailer)
 
+## Nodemailer supports
+
+  * **Unicode** to use any characters
+  * **HTML content** as well as **plain text** alternative
+  * **Attachments** (including attachment **streaming** for sending larger files)
+  * **Embedded images** in HTML
+  * **SSL/STARTTLS** for secure e-mail delivery
+  * Different transport methods - **SMTP**, **sendmail** and **Amazon SES**
+  * SMTP **Connection pool** and connection reuse for rapid delivery
+  * **Preconfigured** services for using SMTP with Gmail, Hotmail etc.
+
+## Check out my other mail related modules
+
+If you want to parse generated or received e-mail instead of sending it, check 
+out [MailParser](https://github.com/andris9/mailparser).
+
+If you only want to generate the raw e-mail stream, check out 
+[MailComposer](https://github.com/andris9/mailcomposer).
+
+If you only want to communicate with the SMTP (both as client and the server),
+check out [simplesmtp](https://github.com/andris9/simplesmtp).
+
+## Example
+
+This is a complete example to send an e-mail with plaintext and HTML body
+
+    var nodemailer = require("nodemailer");
+    
+    var transport = new nodemailer.Transport("SMTP",{
+        service: "Gmail",
+        auth: {
+            user: "[e-mail]",
+            pass: "userpass"
+        }
+    });
+    
+    var mailOptions = {
+        transport: transport, // transport method to use
+        from: "Sender Name <[e-mail]>", // sender address
+        to: "[e-mail], [e-mail]", // list of receivers
+        subject: "Hello!", // Subject line
+        text: "Hello world!", // plaintext body
+        html: "<b>Hello world!</b>" // html body
+    }
+
+    nodemailer.sendMail(mailOptions, function(error){
+        if(error){
+            console.log(error);
+        }else{
+            console.log("Message sent!");
+        }
+        transport.close(); // let's shut down the connection pool
+    });
+
+## Installation
+
+Install through NPM
+
     npm install nodemailer
 
-or download [ZIP archive](https://github.com/andris9/Nodemailer/zipball/master).
+Currently v0.3 is not published on NPM so you should install it manually
 
-The source for Nodemailer is available at [GitHub](https://github.com/andris9/Nodemailer).
+Use the easy way
 
-### Compatibility
+    npm install https://github.com/andris9/Nodemailer/tarball/v0.3
 
-Nodemailer is fully compatible with Node.js versions 0.3.x, 0.4.x and 0.5.x on *nix and 0.5.x on Windows
+Or the more complicated way
 
-Usage
------
+    cd ~/node_modules
+    git clone [e-mail]:andris9/Nodemailer.git nodemailer
+    cd nodemailer
+    git fetch origin v0.3:v0.3
+    git checkout v0.3
+    npm install
 
-**nodemailer.send_mail(mail_params, callback)**
+## Usage
 
+Include the module
+
+    var nodemailer = require("nodemailer");
+
+An e-mail can be sent with `sendMail(mailOptions, callback)` command
+
+    nodemailer.send_mail(mailOptions, callback);
+
 Where
 
-  * **mail_params** defines the e-mail (set its subject, body text, receivers etc.), see *E-mail Message Fields* for details
-  * **callback** is the callback function that will be run after the e-mail is sent or the sending failed
+  * **mailOptions** defines the e-mail (set its subject, body text, receivers etc.), see **E-mail Message Fields** for details
+  * **callback** is the callback function that will be run after the e-mail is sent or the sending failed (see **Return callback** for details)
 
-Simple use case to send a HTML e-mail with plaintext alternative
+## Setting up a transport method
 
-    var nodemailer = require('nodemailer');
+Before you can send any e-mails you need to set up a transport method. This can
+be done with `new nodemailer.Transport(type, options)` where `type` indicates
+the transport protocol and `options` defines how it used.
 
-    // one time action to set up SMTP information
-    nodemailer.SMTP = {
-        host: 'smtp.example.com'
-    }
+    var transport = new nodemailer.Transport("SMTP", {smtp_options});
 
-    // send an e-mail
-    nodemailer.send_mail(
-        // e-mail options
-        {
-            sender: '[e-mail]',
-            to:'[e-mail]',
-            subject:'Hello!',
-            html: '<p><b>Hi,</b> how are you doing?</p>',
-            body:'Hi, how are you doing?'
-        },
-        // callback function
-        function(error, success){
-            console.log('Message ' + success ? 'sent' : 'failed');
-        }
-    );
+The same transport object can and should be reused several times.
 
-The callback function gets two parameters - *error* and *success*. If there's an 
-error, then sending failed and you should check where's the problem. If there's 
-no error value but *success* is not *true* then the server wasn't able to process 
-the message correctly. Probably there was timeout while processing the message 
-etc - in this case you should re-schedule sending this e-mail. If *success* 
-is *true* then the message was sent successfully.
+When the transport method is defined, it should be attached to the message
+object as `transport`
 
-See [examples/example_smtp.js](https://github.com/andris9/Nodemailer/blob/master/examples/example_smtp.js) for a complete example.
+    var transport = new nodemailer.Transport("SMTP", {smtp_options});
 
-Transfer method setup
-----------
+    var mailOptions = {
+        transport: transport,
+        from: "[e-mail]",
+        to: "[e-mail]"
+        ...
+    };
 
-Before sending any e-mails you need to set up a transfer method for delivering the messages.
+### Possible transport methods
 
-To do this you need to define a properties object for a specific transfer method. Setup only one of these methods since only the first one defined will be used.
+Required `type` parameter can be one of the following:
 
-### SMTP
+  * **SMTP** for using SMTP
+  * **SES** for using Amazon SES
+  * **Sendmail** for utilizing systems *sendmail* command
 
-Use SMTP as the transfer method with the following setup
+### Setting up SMTP
 
-    nodemailer.SMTP = {
-        host: 'smtp.example.com', // required
-        port: 25, // optional, defaults to 25 or 465
-        use_authentication: false, // optional, false by default
-        user: '', // used only when use_authentication is true 
-        pass: ''  // used only when use_authentication is true
-    }
+SMTP is different from the other transport mechanisms, as in its case a connection
+pool is created. All the connections try to stay alive as long as possible and 
+are reusable to minimize the protocol overhead delay - for example setting up
+TLS for authenticating is relatively lengthy process (in CPU terms, not by human
+terms), you do not want to do it several times.
 
-### Amazon SES
+Possible SMTP options are the following:
 
-Use Amazon SES as the transfer method with the following setup
+ * **service** - an optional well known service identifier ("Gmail", "Hotmail" etc., see **Well known Services** for a list of supported services) to auto-configure host, port and secure connection settings
+ * **host** - hostname of the SMTP server (defaults to "localhost", not needed with `service`)
+ * **port** - port of the SMTP server (defaults to 25, not needed with `service`)
+ * **secureConnection** - use SSL (default is `false`, not needed with `service`)
+ * **name** - the name of the client server (defaults to machine name)
+ * **auth** - authentication object as `{user:"...", pass:"..."}`
+ * **ignoreTLS** - ignore server support for STARTTLS (defaults to `false`)
+ * **debug** - output client and server messages to console
+ * **maxConnections** - how many connections to keep in the pool (defaults to 5)
 
-    nodemailer.SES = {
-        AWSAccessKeyID: 'ACCESSKEY', // required
-        AWSSecretKey: 'SECRETKEY', // required
-        ServiceUrl: 'https://email.us-east-1.amazonaws.com', // optional
-    }
+Example:
 
-### sendmail
+    var transport = new nodemailer.Transport("SMTP", {
+        service: "Gmail",
+        auth: {
+            user: "[e-mail]",
+            pass: "userpass"
+        }
+    });
 
-Use `sendmail` as the transfer method with the following setup
+**NB!** if you want to close the pool (cancel all open connections) you can use
+`transport.close()`
 
-    nodemailer.sendmail = true;
+    var transport = new nodemailer.Transport("SMTP",{});
+    ...
+    transport.close(); // close the pool 
 
-or
+### Setting up SES
 
-    nodemailer.sendmail = '/path/to/sendmail';
+SES is actually a HTTP based protocol, the compiled e-mail and related info 
+(signatures and such) are sent as a HTTP request to SES servers.
 
-Aditional setup
-----------------
+Possible SES options are the following:
 
-### SSL Support with SMTP (port 465)
+ * **AWSAccessKeyID** - AWS access key (required)
+ * **AWSSecretKey** - AWS secret (required)
+ * **ServiceUrl** - optional API end point URL (defaults to *"https://email.us-east-1.amazonaws.com"*)
 
-If you want to use SSL (not TLS/STARTTLS, just SSL), you need to set the *ssl* parameter to true.
+Example:
 
-	nodemailer.SMTP = {
-	    host: 'smtp.gmail.com',
-	    port: 465,
-	    ssl: true,
-	    use_authentication: true,
-	    user: '[e-mail]',
-	    pass: 'my.password'
-	}
+    var transport = new nodemailer.Transport("SES", {
+        AWSAccessKeyID: "AWSACCESSKEY",
+        AWSSecretKey: "AWS/Secret/key"
+    });
 
-### TLS Support with SMTP (port 587)
+### Setting up Sendmail
 
-If you want to use TLS/STARTTLS (port 587), leave *ssl* to false or do not set it, encryption will be started automatically when needed.
+Sendmail transport method streams the compiled message to the *stdin* of *sendmail*
+command.
 
-    nodemailer.SMTP = {
-        host: 'smtp.gmail.com',
-        port: 587,
-        ssl: false,
-        use_authentication: true,
-        user: '[e-mail]',
-        pass: 'my.password'
-    }
+Configuration is really easy, the options parameter is optional but you can
+use it to define the path to the *sendmail* command
 
-E-mail Message Fields
---------------------
+    var transport = new nodemailer.Transport("Sendmail", "/usr/bin/sendmail");
 
+### Well known services for SMTP
+
+If you want to use a well known service as the SMTP host, you do not need
+to enter the hostname or port number, just use the `service` parameter.
+
+Currently cupported services are: 
+
+  * **"Gmail"** for Google Mail
+  * **"hot.ee"** for www.hot.ee
+  * **"Hotmail"** for Microsoft Live Hotmail
+  * **"iCloud"** for Apple iCloud
+  * **"mail.ee"** for www.mail.ee
+  * **"Postmark"** for Postmark App
+  * **"SendGrid"** for SendGrid
+  * **"SES"** for Amazon SES
+  * **"Yahoo"** for Yahoo Mail
+  * **"Zoho"** for Zoho Mail
+
+Predefined service data covers `host`, `port` and secure connection settings, 
+any other parameters (ie. `auth`) need to be set separately.
+
+## E-mail message fields
+
 The following are the possible fields of an e-mail message:
 
-  - **sender** - The e-mail address of the sender. All e-mail addresses can be plain `[e-mail]` or formatted `Sender Name <[e-mail]>`
+  - **from** - The e-mail address of the sender. All e-mail addresses can be plain `[e-mail]` or formatted `Sender Name <[e-mail]>`
   - **to** - Comma separated list of recipients e-mail addresses that will appear on the `To:` field
   - **cc** - Comma separated list of recipients e-mail addresses that will appear on the `Cc:` field
   - **bcc** - Comma separated list of recipients e-mail addresses that will appear on the `Bcc:` field
-  - **reply_to** - An e-mail address that will appear on the `Reply-To:` field
+  - **replyTo** - An e-mail address that will appear on the `Reply-To:` field
   - **subject** - The subject of the e-mail
-  - **body** - The plaintext version of the message
+  - **text** - The plaintext version of the message
   - **html** - The HTML version of the message
-  - **attachments** - An array of attachment objects. Attachment object consists of two properties - `filename` and `contents`. Property `contents` can either be a String or a Buffer (for binary data). `filename` is the name of the attachment.
+  - **headers** - An object of additional header fields `{"X-Key-Name": "key value"}` (NB! values as passed as is, you should do your own encoding to 7bit if needed)
+  - **attachments** - An array of attachment objects.
 
-There's an optional extra field **headers** which holds custom header values in the form of `{key: value}`. These values will not overwrite any existing header but will be appended to the list.
+All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding.
+Attachments are streamed as binary.
 
-    mail_data = {
-        sender:'[e-mail]',
-        to:'[e-mail]',
-        ....
-        headers: {
-            'X-My-Custom-Header-Value': 'Visit www.example.com for more info!'
-        }
-    }
+Example:
 
-For debugging set **debug** to true - then all the data passed between the client and the server will be output to console.
+    var transport = new nodemailer.Transport("Sendmail");
 
-Address Formatting
-------------------
+    var mailOptions = {
+        transport: transport,
+        from: "[e-mail]",
+        to: "[e-mail]",
+        subject: "Hello world!",
+        text: "Plaintext body"
+    }
+    
+    nodemailer.sendMail(mailOptions, function(){});
 
-All the e-mail addresses can be plain e-mail address
+### Attachment fields
 
-    [e-mail]
+Attahcment object consists of the following properties:
 
-or with formatted name (includes unicode support)
+  * **fileName** - filename to be reported as the name of the attached file, use of unicode is allowed (except when using Amazon SES which doesn't like it)
+  * **cid** - optional content id for using inline images in HTML message source
+  * **contents** - String or a Buffer contents for the attachment
+  * **filePath** - path to a file if you want to stream the file instead of including it (better for larger attachments)
+  * **contentType** - optional content type for the attachment, if not set will be derived from the `fileName` property 
 
-    'Ноде Майлер' <[e-mail]>
+One of `contents` or `filePath` must be specified, if both are missing, the attachment
+will be discarded. Other fields are optional.
 
-To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.
+Attachments can be added as many as you want.
 
-    [e-mail], 'Ноде Майлер' <[e-mail]>, "Name, User" <[e-mail]>
+### Address Formatting
 
-Creating HTML messages
-----------------------
+All the e-mail addresses can be plain e-mail address
 
-Message body in HTML format can be set with the message field `html`. If property `html` has contents but plain text alternative `body` has not (is left to empty), then existing text from the html version is also used in the plaintext version (without the html formatting).
+    [e-mail]
 
-The charset for `html` is UTF-8.
+or with formatted name (includes unicode support)
 
-    nodemailer.send_mail({
-        ...
-        html: '<p>hello world!<br/>хелло ворлд!</p>'
-    });
+    "Ноде Майлер" <[e-mail]>
 
-Using Attachments
------------------
+To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.
 
-An e-mail message can include one or several attachments. Attachments can be set with the message field `attachments` which accepts a list of attachment objects.
+    [e-mail], "Ноде Майлер" <[e-mail]>, "Name, User" <[e-mail]>
 
-An attachment object primarly consists of two properties - `filename` which is the name of the file (not a filepath to an actual file on disk etc.) that will be reported to the receiver as the attachments name; and `contents` to hold the data in a String or Buffer format.
-There's an additional property `cid`  which can be used for embedding images in a HTML message.
+You can even use unicode domain and user names, these are automatically converted
+to the required form
 
-Property `filename` is unicode safe.
+    "Uncode Domain" <info@müriaad-polüteism.info>
 
-    var attachment_list = [
-        {
-            'filename': 'attachment1.txt',
-            'contents': 'contents for attachment1.txt'
-        },
-        {
-            'filename': 'аттачмент2.bin',
-            'contents': new Buffer('binary contents', 'binary');
-        }
-    ];
+### Using Embedded Images
 
-    nodemailer.send_mail({
-        ...
-        attachments: attachment_list
-    });
+Attachments can be used as embedded images in the HTML body. To use this
+feature, you need to set additional property of the attachment - `cid` (unique
+identifier of the file) which is a reference to the attachment file. The same
+`cid` value must be used as the image URL in HTML (using `cid:` as the URL
+protocol, see example below).
 
-Using Embedded Images
----------------------
-
-Attachments can be used as embedded images in the HTML body. To use this feature, you need to set additional property
-of the attachment - `cid` (unique identifier of the file) which is a reference to the attachment file.
-The same `cid` value must be used as the image URL in HTML (using `cid:` as the URL protocol, see example below).
-
 **NB!** the cid value should be as unique as possible!
 
-    var cid_value = Date.now() + '.image.jpg';
-    var html = 'Embedded image: <img src="cid:' + cid_value + '" />';
+    var html = "Embedded image: <img src='cid:[e-mail]' />";
     var attachments = [{
-        filename: 'image.png',
-        contents: IMAGE_CONTENTS,
-        cid: cid_value
+        filename: "image.png",
+        filePath: "/path/to/file",
+        cid: "[e-mail]"
     }];
 
-Issues
-------
+## Return callback
 
-Use [Nodemailer Issue tracker](https://github.com/andris9/Nodemailer/issues) to report additional shortcomings, bugs, feature requests etc.
+Return callback gets two parameters
 
-### Charsets
+  * **error** - an error object if the message failed
+  * **responseStatus** - an object with some information about the status on success
 
-Currently the only allowed charset is UTF-8. This is probably not going to change.
+## Tests
 
-### Slow
+Run the tests with npm in Nodemailer's directory
 
-SMTP connections are not shared - if you want to send several e-mails to the same domain in a row, then for every mail a new connection is created and closed afterwards. Together with TLS negotiation this can turn out to be pretty slow. Nodemailer is not the best choice for spamming!
+    npm test
 
-### Attachments
+There aren't currently many tests for Nodemailer but there are a lot of tests
+in the modules that are used to generate the raw e-mail body and to use the 
+SMTP client connection.
 
-Do not use large attachments as the attachment contents are read into memory and the final message body is combined into one large string before sending.
+## Tweaking 
 
-Contributors
-------------
+Nodemailer in itself is actually more like a wrapper for my other modules
+[mailcomposer](https://github.com/andris9/mailcomposer) for composing the raw message stream
+and [simplesmtp](https://github.com/andris9/simplesmtp) for delivering it, by providing an 
+unified API. If there's some problems with particular parts of the 
+message composing/sending process you should look at the  appropriate module.
 
-See [Nodemailer/contributors](https://github.com/andris9/Nodemailer/contributors) for a live list
+## License
 
-License
--------
-
-**Nodemailer** is licensed under [MIT license](https://github.com/andris9/Nodemailer/blob/master/LICENSE). Basically you can do whatever you want to with it.
+**Nodemailer** is licensed under [MIT license](https://github.com/andris9/Nodemailer/blob/master/LICENSE). Basically you can do whatever you want to with it.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Wildcard dependency

Quality

Package has a dependency with a floating version range. This can cause issues if the dependency publishes a new major version.

Found 2 instances 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

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Wildcard dependency

Quality

Package has a dependency with a floating version range. This can cause issues if the dependency publishes a new major version.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 2 instances in 1 package

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

No website

Quality

Package does not have a website.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

432469

increased by536.18%

Number of package files

44

increased by300%

Lines of code

1723

increased by9.75%

Number of low quality alerts

1

decreased by-50%

Number of lines in readme file

332

increased by24.34%

Number of low supply chain risk alerts

0

decreased by-100%

Number of medium supply chain risk alerts

4

decreased by-33.33%

Worsened metrics

Dependency count

2

increased by100%

Dev dependency count

1

increased byInfinity%

Number of medium quality alerts

2

increased by100%

Dependency changes

• + Addedmailcomposer@*

• + Addedsimplesmtp@*

• + Addedaddressparser@1.0.1(transitive)

• + Addedbuildmail@4.0.1(transitive)

• + Addediconv-lite@0.4.15(transitive)

• + Addedlibbase64@0.1.0(transitive)

• + Addedlibmime@3.0.0(transitive)

• + Addedlibqp@1.1.0(transitive)

• + Addedmailcomposer@4.0.2(transitive)

• + Addednodemailer-fetch@1.6.0(transitive)

• + Addednodemailer-shared@1.1.0(transitive)

• + Addedpunycode@1.4.1(transitive)

• + Addedrai@0.1.12(transitive)

• + Addedsimplesmtp@0.3.35(transitive)

• + Addedxoauth2@0.1.8(transitive)

• - Removedmimelib-noiconv@*

• - Removedmimelib-noiconv@0.1.9(transitive)