Skip to content

Latest commit

 

History

History
366 lines (263 loc) · 12.6 KB

README.md

File metadata and controls

366 lines (263 loc) · 12.6 KB
Raw

Nodemailer

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 ✔

This version of Nodemailer is built from scratch and might break some existing scripts, so beware while upgrading.

Autogenerated docs

Use DocumentUp to read this README in a more structured way (with TOC).

Build Status

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.

If you only want to generate the raw e-mail stream, check out MailComposer.

If you only want to communicate with the SMTP (both as client and the server), check out simplesmtp.

Example

This is a complete example to send an e-mail with plaintext and HTML body

var nodemailer = require("nodemailer");

var transport = nodemailer.createTransport("SMTP",{
    service: "Gmail",
    auth: {
        user: "gmail.user@gmail.com",
        pass: "userpass"
    }
});

var mailOptions = {
    transport: transport, // transport method to use
    from: "Sender Name <sender@example.com>", // sender address
    to: "receiver1@example.com, receiver2@example.com", // 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(); // lets shut down the connection pool
});

See also the examples folder for full featured examples

Installation

Install through NPM

npm install nodemailer

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

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

Setting up a transport method

Before you can send any e-mails you need to set up a transport method. This can be done with nodemailer.createTransport(type, options) where type indicates the transport protocol and options defines how it used.

var transport = nodemailer.createTransport("SMTP", {smtp_options});

The same transport object can and should be reused several times.

When the transport method is defined, it should be attached to the message object as transport

var transport = nodemailer.createTransport("SMTP", {smtp_options});

var mailOptions = {
    transport: transport,
    from: "sender@tr.ee",
    to: "receiver@tr.ee"
    ...
};

Possible transport methods

Required type parameter can be one of the following:

  • SMTP for using SMTP
  • SES for using Amazon SES
  • Sendmail for utilizing systems sendmail command

Setting up SMTP

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.

Possible SMTP options are the following:

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

Example:

var transport = nodemailer.createTransport("SMTP", {
    service: "Gmail",
    auth: {
        user: "gmail.user@gmail.com",
        pass: "userpass"
    }
});

or the same without service parameter

var transport = nodemailer.createTransport("SMTP", {
    host: "smtp.gmail.com", // hostname
    secureConnection: true, // use SSL
    port: 465, // port for secure SMTP
    auth: {
        user: "gmail.user@gmail.com",
        pass: "userpass"
    }
});

NB! if you want to close the pool (cancel all open connections) you can use transport.close()

var transport = nodemailer.createTransport("SMTP",{});
...
transport.close(); // close the pool

Setting up SES

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.

Possible SES options are the following:

Example:

var transport = nodemailer.createTransport("SES", {
    AWSAccessKeyID: "AWSACCESSKEY",
    AWSSecretKey: "AWS/Secret/key"
});

Setting up Sendmail

Sendmail transport method streams the compiled message to the stdin of sendmail command.

Configuration is really easy, the options parameter is optional but you can use it to define the path to the sendmail command

var transport = nodemailer.createTransport("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:

  • from - The e-mail address of the sender. All e-mail addresses can be plain sender@server.com or formatted Sender Name <sender@server.com>
  • 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
  • replyTo - An e-mail address that will appear on the Reply-To: field
  • subject - The subject of the e-mail
  • text - The plaintext version of the message
  • html - The HTML version of the message
  • 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.

All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding. Attachments are streamed as binary.

Example:

var transport = nodemailer.createTransport("Sendmail");

var mailOptions = {
    transport: transport,
    from: "me@tr.ee",
    to: "me@tr.ee",
    subject: "Hello world!",
    text: "Plaintext body"
}

nodemailer.sendMail(mailOptions, function(){});

Attachment fields

Attahcment object consists of the following properties:

  • 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

One of contents or filePath must be specified, if both are missing, the attachment will be discarded. Other fields are optional.

Attachments can be added as many as you want.

var mailOptions = {
    ...
    attachments: [
        {
            fileName: "text1.txt",
            contents: "hello world!
        },
        {
            fileName: "text2.txt",
            contents: new Buffer("hello world!,"utf-8")
        },
        {
            fileName: "text3.txt",
            filePath: "/path/to/file.txt" // stream this file
        },
        {
            fileName: "text",
            contents: "hello world!,
            contentType: "text/plain"
        }
    ]
}

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>

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

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

You can even use unicode domain and user names, these are automatically converted to the supported form

"Uncode Domain" <info@müriaad-polüteism.info>

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 mailOptions = {
    ...
    html: "Embedded image: <img src='cid:unique@node.ee' />",
    attachments: [{
        filename: "image.png",
        filePath: "/path/to/file",
        cid: "unique@node.ee" //same cid value as in the html img src
    }]
}

Return callback

Return callback gets two parameters

  • error - an error object if the message failed
  • responseStatus - an object with some information about the status on success

Example:

nodemailer.sendMail(mailOptions, function(error, responseStatus){
    if(!error){
        console.log(responseStatus.message); // response from the server
    }
});

Tests

Run the tests with npm in Nodemailer's directory

npm test

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.

Tweaking

Nodemailer in itself is actually more like a wrapper for my other modules mailcomposer for composing the raw message stream and 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.

License

Nodemailer is licensed under MIT license. Basically you can do whatever you want to with it.