Fire-Mail

Fire Mail is an easy to use npm module to send e-mail notifications based on entries in firebase.

You might want this if you have a client side web app with a contact us form, but still want to serve it over Amazon S3 for example.

Notes and information

Installation

npm install fire-mail

TL;DR Usage Example

var fireMail = require("fire-mail");

Configuration

There are three ways you can load in the configuration options

config.json
options object
firebase ref

Templates

To use Nodemailer with templates, please see documentation for these projects.

swig-email-templates - swig, template inheritance, dummy context
node-email-templates - ejs

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

var nodemailer = require("nodemailer");
 
// create reusable transport method (opens pool of SMTP connections)
var smtpTransport = nodemailer.createTransport("SMTP",{
    service: "Gmail",
    auth: {
        user: "gmail.user@gmail.com",
        pass: "userpass"
    }
});
 
// setup e-mail data with unicode symbols
var mailOptions = {
    from: "Fred Foo ✔ <foo@blurdybloop.com>", // sender address
    to: "bar@blurdybloop.com, baz@blurdybloop.com", // list of receivers
    subject: "Hello ✔", // Subject line
    text: "Hello world ✔", // plaintext body
    html: "<b>Hello world ✔</b>" // html body
}
 
// send mail with defined transport object
smtpTransport.sendMail(mailOptions, function(error, response){
    if(error){
        console.log(error);
    }else{
        console.log("Message sent: " + response.message);
    }
 
    // if you don't want to use this transport object anymore, uncomment following line
    //smtpTransport.close(); // shut down the connection pool, no more messages
});

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

transport.sendMail(mailOptions, callback);

Where

transport is a transport object created from the nodemailer.createTransport method
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 is 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 can be used to send e-mail with sendMail

var transport = nodemailer.createTransport("SMTP", {smtp_options});
 
transport.sendMail({
    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). If you're using port 587 then keep secureConnection false, since the connection is started in insecure plain text mode and only later upgraded with STARTTLS
name - the name of the client server (defaults to machine name)
auth - authentication object as {user:"...", pass:"..."} or {XOAuth2: {xoauth2_options}} or {XOAuthToken: "base64data"}
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)
maxMessages - limit the count of messages to send through a single connection (no limit by default)

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

SMTP XOAUTH and token generation

XOAUTH2

nodemailer supports XOAUTH2 authentication protocol. To use this you need to obtain a Client ID and a Client Secret from Google API Console (Open "API Access" and create "Client ID for web applications") and then request a refresh token for an user. See Google OAuth 2.0 Offline Access for more information.

Once you have obtained the Client ID, Client Secret and a Refresh Token for an user, you can use these values to send mail on behalf of the user.

var transportOptions = {
    ...,
    auth: {
        XOAuth2: {
            user: "example.user@gmail.com",
            clientId: "8819981768.apps.googleusercontent.com",
            clientSecret: "{client_secret}",
            refreshToken: "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI",
            accessToken: "vF9dft4qmTc2Nvb3RlckBhdHRhdmlzdGEuY29tCg==",
            timeout: 3600
        }
    }
}

accessToken and timeout values are both optional. If XOAUTH2 login fails a new access token is generated automatically and the login is retried.

XOAUTH

Older XOAUTH is also supported by nodemailer for SMTP. XOAUTH is based on OAuth protocol 1.0 and is considered deprecated.

To use this, include XOAuthToken option in auth instead of the regular user and pass.

var transportOptions = {
    ...,
    auth: {
        XOAuthToken: "R0VUIGh0dHBzOi8vbWFpbC5nb29...."
    }
}

nodemailer includes also built in XOAUTH token generator which can be used with nodemailer.createXOAuthGenerator(). The function is preconfigured for Gmail, so in this case only mandatory options are user, token and tokenSecret.

var XOAuthTokenGenerator = nodemailer.createXOAuthGenerator({
        user: "test.nodemailer@gmail.com",
        // requestUrl: "https://oauth.access.point",
        // consumerKey: "anonymous",
        // consumerSecret: "anonymous",
        token: "1/O_HgoO4h2uOUfpus0V--7mygICXrQQ0ZajB3ZH52KqM",
        tokenSecret: "_mUBkIwNPnfQBUIWrJrpXJ0c"
    });

One of user or requestUrl is mandatory. consumerKey and consumerSecret both default to "anonymous".

var transportOptions = {
    service: "Gmail",
    auth: {
        XOAuthToken: nodemailer.createXOAuthGenerator({
            user: "test.nodemailer@gmail.com",
            token: "1/O_HgoO4h2uOUfpus0V--7mygICXrQQ0ZajB3ZH52KqM",
            tokenSecret: "_mUBkIwNPnfQBUIWrJrpXJ0c"
        })
    }
}

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:

AWSAccessKeyID - AWS access key (required)
AWSSecretKey - AWS secret (required)
ServiceUrl - optional API end point URL (defaults to "https://email.us-east-1.amazonaws.com")

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.

Options object is optional, possible sendmail options are the following:

path - path to the sendmail command (defaults to "sendmail")
args - an array of extra command line options to pass to the sendmail command (ie. ["-f", "foo@blurdybloop.com"]).
noCR - If set to true, the line ending character will be \n instead of the default \r\n ending.

Currently the command to be spawned is built up like this: the command is either using sendmail -i -f from_addr to_addr[] (by default) or sendmail -i list_of_args[] (if args property was given). -i is ensured to be present on either case.

In the default case (no args defined) From and To addresses are either taken from From,To, Cc and Bcc properties or from the envelope property if one is present.

Be wary when using the args property - no recipients are defined by default, you need to ensure these by yourself, for example by using the -t flag.

Example:

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

var transport = nodemailer.createTransport("sendmail", {
    path: "/usr/local/bin/sendmail",
    args: ["-t", "-f", "foo@blurdybloop.com"]
});

Compatibility notice

Some sendmail implementations require all line endings to be <LF>. Set noCR:true in the options argument to circument this.

DKIM Signing

Nodemailer supports DKIM signing with very simple setup. Use this with caution though since the generated message needs to be buffered entirely before it can be signed. Not a big deal with small messages but might consume a lot of RAM when using larger attachments.

Set up the DKIM signing with useDKIM method for a transport object:

transport.useDKIM(dkimOptions)

Where dkimOptions includes necessary options for signing

domainName - the domainname that is being used for signing
keySelector - key selector. If you have set up a TXT record with DKIM public key at zzz._domainkey.blurdybloop.com then zzz is the selector
privateKey - DKIM private key that is used for signing as a string
headerFieldNames - optional colon separated list of header fields to sign, by default all fields suggested by RFC4871 #5.5 are used

All messages transmitted through this transport objects are from now on DKIM signed.

Currently if several header fields with the same name exists, only the last one (the one in the bottom) is signed.

Example:

var transport = nodemailer.createTransport("Sendmail");
 
transport.useDKIM({
    domainName: "kreata.ee",
    keySelector: "dkim",
    privateKey: fs.readFileSync("private_key.pem")
});
 
transport.sendMail(mailOptions);

See examples/example_dkim.js for a complete example.

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 supported services are:

DynectEmail
Gmail
hot.ee
Hotmail
iCloud
mail.ee
Mail.Ru
Mailgun
Mailjet
Mandrill
Postmark
QQ
QQex (Tencent Business Email)
SendGrid
SES
Yahoo
yandex
Zoho

Predefined service data covers host, port and secure connection settings, any other parameters (ie. auth) need to be set separately. Service names are case insensitive, so using "gmail" instead of "Gmail" is totally fine.

Example:

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

or alternatively

var smtpTransport = nodemailer.createTransport("SMTP",{
    service: "Gmail", // sets automatically host, port and connection security settings
    auth: {
        user: "gmail.user@gmail.com",
        pass: "userpass"
    }
});

Actually, if you are authenticating with an e-mail address that has a domain name like @gmail.com or @yahoo.com etc., then you don't even need to provide the service name, it is detected automatically.

var smtpTransport = nodemailer.createTransport("SMTP",{
    auth: {
        user: "gmail.user@gmail.com", // service is detected from the username
        pass: "userpass"
    }
});

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 or an array of recipients e-mail addresses that will appear on the To: field
cc - Comma separated list or an array of recipients e-mail addresses that will appear on the Cc: field
bcc - Comma separated list or an array 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
inReplyTo - The message-id this message is replying
references - Message-id list
subject - The subject of the e-mail
text - The plaintext version of the message
html - The HTML version of the message
generateTextFromHTML - if set to true uses HTML to generate plain text body part from the HTML if the text is not defined
headers - An object of additional header fields {"X-Key-Name": "key value"} (NB! values are passed as is, you should do your own encoding to 7bit and folding if needed)
attachments - An array of attachment objects.
alternatives - An array of alternative text contents (in addition to text and html parts)
envelope - optional SMTP envelope, if auto generated envelope is not suitable
messageId - optional Message-Id value, random value will be generated if not set. Set to false to omit the Message-Id header
date - optional Date value, current UTC string will be used if not set
encoding - optional transfer encoding for the textual parts (defaults to "quoted-printable")
charset - optional output character set for the textual parts (defaults to "utf-8")
dsn - An object with methods success, failure and delay. If any of these are set to true, DSN will be used

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 = {
    from: "me@tr.ee",
    to: "me@tr.ee",
    subject: "Hello world!",
    text: "Plaintext body"
}
 
transport.sendMail(mailOptions);

SendGrid support

Nodemailer supports SendGrid SMTP API out of the box - you can use objects as header values and these are automatically JSONized (and mime encoded if needed).

var mailOptions = {
    ...,
    headers: {
        'X-SMTPAPI': {
            category : "newuser",
            sub:{
                "%name%": ["Žiguli Õllepruul"]
            }
        }
    },
    subject: "Hello, %name%"
}

This also applies to any other service that expects a JSON string as a header value for specified key.

Generate Text from HTML

If generateTextFromHTML option is set to true, then HTML contents of the mail is automatically converted to plaintext format when plaintext content is empty or missing.

For example

mailOptions = {
    ...,
    generateTextFromHTML: true,
    html: '<h1>Hello world</h1><p><b>How</b> are you?',
    // text: '' // no text part
}

is automatically converted in the backround by Nodemailer to:

mailOptions = {
    ...,
    // source html:
    html: '<h1>Hello world</h1><p><b>How</b> are you?',
    // automatically generated plaintext message:
    text: "Hello world\n"+
          "===========\n"+
          "\n"+
          "**How** are you?"
}

As you can see the output syntax for generateTextFromHTML looks similar to markdown, and that is exactly the case here - Nodemailer includes a simple HTML to markdown converter. But don't expect too much from it, it's not full featured or perfect, just some regexes here and there.

Attachment fields

Attachment 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 or an URL if you want to stream the file instead of including it (better for larger attachments)
streamSource - Stream object for arbitrary binary streams if you want to stream the contents (needs to support pause/resume)
contentType - optional content type for the attachment, if not set will be derived from the fileName property
contentDisposition - optional content disposition type for the attachment, defaults to "attachment"

One of contents, filePath or streamSource must be specified, if none is present, the attachment will be discarded. Other fields are optional.

Attachments can be added as many as you want.

var mailOptions = {
    ...
    attachments: [
        {   // utf-8 string as an attachment
            fileName: "text1.txt",
            contents: "hello world!"
        },
        {   // binary buffer as an attachment
            fileName: "text2.txt",
            contents: new Buffer("hello world!","utf-8")
        },
        {   // file on disk as an attachment
            fileName: "text3.txt",
            filePath: "/path/to/file.txt" // stream this file
        },
        {   // fileName and content type is derived from filePath
            filePath: "/path/to/file.txt"
        },
        {   // stream as an attachment
            fileName: "text4.txt",
            streamSource: fs.createReadStream("file.txt")
        },
        {   // define custom content type for the attachment
            fileName: "text.bin",
            contents: "hello world!",
            contentType: "text/plain"
        },
        {   // use URL as an attachment
            fileName: "license.txt",
            filePath: "https://raw.github.com/andris9/Nodemailer/master/LICENSE"
        }
    ]
}

Tests

Run the tests with npm in Nodemailer's directory

npm test

License

Fire-Mail is licensed under the MIT license. Basically you can do whatever you want to with it.

fire-mail

Fire-Mail

Notes and information

Installation

TL;DR Usage Example

Configuration

Templates

Installation

Usage

Setting up a transport method

Possible transport methods

Setting up SMTP

SMTP XOAUTH and token generation

XOAUTH2

XOAUTH

Setting up SES

Setting up Sendmail

DKIM Signing

Well known services for SMTP

E-mail message fields

SendGrid support

Generate Text from HTML

Attachment fields

Tests

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

Weekly Downloads

Version

License

Last publish

Collaborators

fire-mail

Fire-Mail

Notes and information

Installation

TL;DR Usage Example

Configuration

Templates

Installation

Usage

Setting up a transport method

Possible transport methods

Setting up SMTP

SMTP XOAUTH and token generation

XOAUTH2

XOAUTH

Setting up SES

Setting up Sendmail

DKIM Signing

Well known services for SMTP

E-mail message fields

SendGrid support

Generate Text from HTML

Attachment fields

Tests

License

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Last publish

Collaborators

Weekly Downloads