Skip to content

Commit

Permalink
Merge pull request #27 from krunkosaurus/master
Browse files Browse the repository at this point in the history 
Readme and example.js optimizations
  • Loading branch information
@andris9
andris9 committed Jul 21, 2011
2 parents 71ac3d4 + 953c37f commit b280006
Show file tree
Hide file tree
Showing 2 changed files with 85 additions and 82 deletions.
118 changes: 60 additions & 58 deletions README.md
View file
@@ -1,10 +1,10 @@
Nodemailer
==========

**Nodemailer** is an easy to use module to send e-mails with Node.JS (using SMTP or sendmail).
**Nodemailer** is an easy to use module to send e-mails with Node.JS (using SMTP or sendmail).

You can use two ways to send an e-mail message: the *EmailMessage* constructor or the shortcut function *send_mail()*.
The *send_mail()* function takes all the fields of the e-mail message as a function parameter and sends the e-mail immediately.
You can use two ways to send an e-mail message: the *EmailMessage* constructor or the shortcut function *send_mail()*.
The *send_mail()* function takes all the fields of the e-mail message as a function parameter and sends the e-mail immediately.
*EmailMessage* allows to compose the message object first and send it later with its method *send()*. Nodemailers API is designed after Google App Engines [Mail Python API](http://code.google.com/intl/et-EE/appengine/docs/python/mail/).

**Nodemailer is Unicode friendly ✔**. You can use any characters you like.
Expand All @@ -24,7 +24,7 @@ Installation
Install through *NPM*

npm install nodemailer

or download [ZIP archive](https://github.com/andris9/Nodemailer/zipball/master).

The source for Nodemailer is available at [GitHub](https://github.com/andris9/Nodemailer).
Expand All @@ -34,11 +34,11 @@ The source for Nodemailer is available at [GitHub](https://github.com/andris9/No
* [mimelib](https://github.com/andris9/mimelib)
* [node-iconv](https://github.com/bnoordhuis/node-iconv)

If you use *NPM* then the module is available as
If you use *NPM* then the module is available as

var nodemailer = require('nodemailer');

but if you're using the source then
but if you're using the source then

var nodemailer = require('./path_to_nodemailer/lib/mail');

Expand All @@ -47,53 +47,55 @@ Usage

Using *send_mail()*

var nodemailer = require("nodemailer");
var nodemailer = require('nodemailer');

nodemailer.SMTP = {
host: "smtp.example.com"
host: 'smtp.example.com'
}

nodemailer.send_mail({sender: "me@example.com",
to:"you@example.com",
subject:"Hello!",
body:"Hi, how are you doing?"},
function(error, success){
console.log("Message "+(success?"sent":"failed"));
});
nodemailer.send_mail({
sender: 'me@example.com',
to:'you@example.com',
subject:'Hello!',
body:'Hi, how are you doing?'
},
function(error, success){
console.log('Message ' + success ? 'sent' : 'failed');
});

Using *EmailMessage*

var nodemailer = require("nodemailer");
var nodemailer = require('nodemailer');

nodemailer.SMTP = {
host: "smtp.example.com"
host: 'smtp.example.com'
}

var mail = nodemailer.EmailMessage({
sender: "me@example.com",
to:"you@example.com"
});
mail.subject = "Hello!";
mail.body = "Hi, how are you doing?";
sender: 'me@example.com',
to:'you@example.com'
});
mail.subject = 'Hello!';
mail.body = 'Hi, how are you doing?';

mail.send(function(error, success){
console.log("Message "+(success?"sent":"failed"));
});
console.log('Message ' + success ? 'sent' : 'failed');
});

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.
the message etc - in this case you should re-schedule sending this e-mail. If *success* is *true* then the message was sent successfully.

### NB!

Before sending e-mails you need to set up SMTP server parameters.

nodemailer.SMTP = {
host: "smtp.example.com", // required
host: 'smtp.example.com', // required
port: 25, // optional, defaults to 25 or 465
use_authentication: false,
user: "",
pass: ""
user: '',
pass: ''
}

Or alternatively if you don't want to use SMTP but the `sendmail` command then you could
Expand All @@ -103,9 +105,9 @@ set property *sendmail* to true or as the path to *sendmail*.

or

nodemailer.sendmail = "/path/to/sendmail";
If *sendmail* is set, then SMTP options are disregarded.
nodemailer.sendmail = '/path/to/sendmail';

If *sendmail* is set, then SMTP options are disregarded.

See [examples/example.js](https://github.com/andris9/Nodemailer/blob/master/examples/example.js) for a complete example.

Expand All @@ -114,25 +116,25 @@ See [examples/example.js](https://github.com/andris9/Nodemailer/blob/master/exam
If you want to use SSL (not TLS/STARTTLS, just SSL), you need to set the *ssl* parameter to true.

nodemailer.SMTP = {
host: "smtp.gmail.com",
host: 'smtp.gmail.com',
port: 465,
ssl: true,
use_authentication: true,
user: "my.username@gmail.com",
pass: "my.password"
user: 'my.username@gmail.com',
pass: 'my.password'
}

### TLS Support (port 587)

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.

nodemailer.SMTP = {
host: "smtp.gmail.com",
host: 'smtp.gmail.com',
port: 587,
ssl: false,
use_authentication: true,
user: "my.username@gmail.com",
pass: "my.password"
user: 'my.username@gmail.com',
pass: 'my.password'
}

E-mail Message Fields
Expand All @@ -150,11 +152,11 @@ The following are the possible fields of an e-mail 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.

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.
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.

mail_data = {
sender:"me@example.com",
to:"you@example.com",
sender:'me@example.com',
to:'you@example.com',
....
headers: {
'X-My-Custom-Header-Value': 'Visit www.example.com for more info!'
Expand All @@ -169,28 +171,28 @@ Address Formatting
All the e-mail addresses can be plain e-mail address

username@example.com

or with formatted name (includes unicode support)

"Ноде Майлер" <username@example.com>
'Ноде Майлер' <username@example.com>

To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.

username@example.com, "Ноде Майлер" <username@example.com>, User Name <username@example.com>
username@example.com, 'Ноде Майлер' <username@example.com>, User Name <username@example.com>

Currently you can't use comma in a formatted name, even if the name is in quotes.


Creating HTML messages
----------------------

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).
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).

The charset for `html` is UTF-8.

nodemailer.send_mail({
...
html: "<p>hello world!<br/>хелло ворлд!</p>"
html: '<p>hello world!<br/>хелло ворлд!</p>'
});

Using Attachments
Expand All @@ -205,15 +207,15 @@ Property `filename` is unicode safe.

var attachment_list = [
{
"filename": "attachment1.txt",
"contents": "contents for attachment1.txt"
'filename': 'attachment1.txt',
'contents': 'contents for attachment1.txt'
},
{
"filename": "аттачмент2.bin",
"contents": new Buffer("binary contents", "binary");
'filename': 'аттачмент2.bin',
'contents': new Buffer('binary contents', 'binary');
}
];

nodemailer.send_mail({
...
attachments: attachment_list
Expand All @@ -228,10 +230,10 @@ The same `cid` value must be used as the image URL in HTML (using `cid:` as the

**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 cid_value = Date.now() + '.image.jpg';
var html = 'Embedded image: <img src="cid:' + cid_value + '" />';
var attachments = [{
filename: "image.png",
filename: 'image.png',
contents: IMAGE_CONTENTS,
cid: cid_value
}];
Expand All @@ -257,4 +259,4 @@ See [Nodemailer/contributors](https://github.com/andris9/Nodemailer/contributors
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.
49 changes: 25 additions & 24 deletions examples/example.js
View file
@@ -1,38 +1,39 @@
var nodemailer = require("../lib/mail");
var nodemailer = require('../lib/mail');

// Set up SMTP server settings
nodemailer.SMTP = {
host: "smtp.gmail.com",
host: 'smtp.gmail.com',
port: 465,
use_authentication: true,
ssl: true,
user: undefined,
pass: undefined,
debug: true
}
console.log("SMTP Configured")
console.log('SMTP Configured')
// unique cid value for the embedded image
var cid = Date.now()+".image.png";
var cid = Date.now() + '.image.png';

// Message object
var message = {
sender: 'Example Test <bradley.meck@gmail.com>',
to: '"My Name" <bradley.meck@gmail.com>',
subject: "Nodemailer is unicode friendly ✔",

body: "Hello to myself!",
html:"<p><b>Hello</b> to myself <img src=\"cid:"+cid+"\"/></p>",
//to: '"My Name" <bradley.meck@gmail.com>',
to: '"Mauvis" <switchstatement@gmail.com>',
subject: 'Nodemailer is unicode friendly ✔',

body: 'Hello to myself!',
html:'<p><b>Hello</b> to myself <img src="cid:"' + cid + '"/></p>',
debug: true,
attachments:[
{
filename: "notes.txt",
contents: "Some notes about this e-mail"
filename: 'notes.txt',
contents: 'Some notes about this e-mail'
},
{
filename: "image.png",
contents: new Buffer("iVBORw0KGgoAAAANSUhEUgAAABAAAAAQAQMAAAAlPW0iAAAABlBMVEUAAAD/"+
"//+l2Z/dAAAAM0lEQVR4nGP4/5/h/1+G/58ZDrAz3D/McH8yw83NDDeNGe4U"+
"g9C9zwz3gVLMDA/A6P9/AFGGFyjOXZtQAAAAAElFTkSuQmCC", "base64"),
filename: 'image.png',
contents: new Buffer('iVBORw0KGgoAAAANSUhEUgAAABAAAAAQAQMAAAAlPW0iAAAABlBMVEUAAAD/' +
'//+l2Z/dAAAAM0lEQVR4nGP4/5/h/1+G/58ZDrAz3D/McH8yw83NDDeNGe4U' +
'g9C9zwz3gVLMDA/A6P9/AFGGFyjOXZtQAAAAAElFTkSuQmCC', 'base64'),
cid: cid
}
]
Expand All @@ -41,34 +42,34 @@ var message = {
// Callback to be run after the sending is completed
var callback = function(error, success){
if(error){
console.log("Error occured");
console.log('Error occured');
console.log(error.message);
return;
}
if(success){
console.log("Message sent successfully!");
console.log('Message sent successfully!');
}else{
console.log("Message failed, reschedule!");
console.log('Message failed, reschedule!');
}
}

console.log("Sending Mail")
console.log('Sending Mail')

// Catch uncaught errors
process.on("uncaughtException",function(e){
console.log("Uncaught Exception",e.stack);
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);
console.log('Caught Exception',e);
}

var oldemit = mail.emit;
mail.emit = function(){
console.log("Mail.emit",arguments);
oldemit.apply(mail,arguments);
console.log('Mail.emit', arguments);
oldemit.apply(mail, arguments);
}

0 comments on commit b280006

Please sign in to comment.