Security News
ESLint is Now Language-Agnostic: Linting JSON, Markdown, and Beyond
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
nodemailer
Advanced tools
Nodemailer is a module for Node.js applications to allow easy email sending. It supports various transport methods and has a simple setup process for sending emails.
Send Emails
This feature allows you to send emails using Nodemailer. The code sample shows how to set up a transporter using Gmail, define mail options, and send an email.
const nodemailer = require('nodemailer');
let transporter = nodemailer.createTransport({
service: 'gmail',
auth: {
user: 'your.email@example.com',
pass: 'yourpassword'
}
});
let mailOptions = {
from: 'your.email@example.com',
to: 'recipient@example.com',
subject: 'Test Email Subject',
text: 'Hello world?',
html: '<b>Hello world?</b>'
};
transporter.sendMail(mailOptions, function(error, info){
if (error) {
console.log(error);
} else {
console.log('Email sent: ' + info.response);
}
});
HTML Email Content
Nodemailer allows you to send HTML content in your emails. The code sample demonstrates how to send an email with HTML content.
const nodemailer = require('nodemailer');
let transporter = nodemailer.createTransport({
// transport configuration
});
let mailOptions = {
from: 'your.email@example.com',
to: 'recipient@example.com',
subject: 'HTML Email',
html: '<h1>Welcome</h1><p>That was easy!</p>'
};
transporter.sendMail(mailOptions, function(error, info){
// callback
});
Attachments
Nodemailer supports sending attachments in emails. The code sample shows how to attach a file to an email.
const nodemailer = require('nodemailer');
let transporter = nodemailer.createTransport({
// transport configuration
});
let mailOptions = {
from: 'your.email@example.com',
to: 'recipient@example.com',
subject: 'Attachment',
text: 'Please find the attachment.',
attachments: [
{
filename: 'file.txt',
path: '/path/to/file.txt'
}
]
};
transporter.sendMail(mailOptions, function(error, info){
// callback
});
Custom Transport Methods
Nodemailer allows the use of custom transport methods for sending emails. The code sample illustrates how to use a custom transport plugin.
const nodemailer = require('nodemailer');
const customTransport = require('my-custom-transport');
let transporter = nodemailer.createTransport(customTransport({
// custom transport options
}));
// send mail with defined transport object
transporter.sendMail({
// mail options
}, function(error, info){
// callback
});
A simple Node.js module for Mailgun. Mailgun-js is designed to work with the Mailgun API for sending, receiving, and tracking emails. It's similar to Nodemailer in functionality but is specifically tailored for Mailgun's service.
The official Node.js client library for interacting with the Postmark API. This package is intended for sending emails through Postmark's transactional email service. Unlike Nodemailer, which is more generic, Postmark is focused on providing a robust service for transactional emails.
Amazon Web Services SDK for JavaScript in Node.js. It includes support for SES (Simple Email Service), which can be used to send emails. While Nodemailer is a standalone package for email, aws-sdk is a comprehensive cloud services SDK that includes email sending capabilities among many other AWS services.
Nodemailer is an easy to use module to send e-mails with Node.JS (using SMTP or sendmail or Amazon SES) and is unicode friendly - You can use any characters you like ✔
Nodemailer is Windows friendly, you can install it with npm on Windows just like any other module, there are no compiled dependencies. Use it from Azure or from your Windows box hassle free.
Version v0.3 of Nodemailer is built from scratch and might break some existing scripts, so beware while upgrading. Nodemailer should be backwards compatible - if your script worked before, then it should work now, even if Nodemailer documentation differs from your code (method names, properties etc.).
Use DocumentUp to read this README in a more structured way (with TOC).
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.
To use Nodemailer with templates, please see documentation for node-email-templates.
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: "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
}
// 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
Install through NPM
npm install nodemailer
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 method defined with nodemailer.createTransport
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"
...
});
Required type
parameter can be one of the following:
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
)service
)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{user:"...", pass:"..."}
or {XOAuthToken: "base64data"}
false
)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
nodemailer supports XOAUTH authentication for SMTP. 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"
})
}
}
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"
});
Sendmail transport method streams the compiled message to the stdin of sendmail command.
Options object is optional, possible sendmail options are the following:
sendmail
command (defaults to "sendmail")sendmail
command (ie. ["-f sender@example.com"]
)Example:
var transport = nodemailer.createTransport("sendmail");
or
var transport = nodemailer.createTransport("sendmail", {
path: "/usr/local/bin/sendmail",
args: ["-f sender@example.com"]
});
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
zzz
is the selectorAll 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: "node.ee",
keySelector: "dkim",
privateKey: fs.readFileSync("private_key.pem")
});
transport.sendMail(mailOptions);
See examples/example_dkim.js for a complete example.
NB! Be careful when using services like Gmail, SES etc. through SMTP
(SES API is handled by Nodemailer automatically) - these tend to modify some
headers like Message-Id or Date which invalidates the signature. In this case use
headerFieldNames
property to define only fields that won't be changed and leave
out Date
or any other unsupported field.
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 (NB! case sensitive).
Currently cupported services are:
Predefined service data covers host
, port
and secure connection settings,
any other parameters (ie. auth
) need to be set separately.
The following are the possible fields of an e-mail message:
sender@server.com
or formatted Sender Name <sender@server.com>
To:
fieldCc:
fieldBcc:
fieldReply-To:
field{"X-Key-Name": "key value"}
(NB! values are passed as is, you should do your own encoding to 7bit if needed)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);
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.
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.
Attahcment object consists of the following properties:
fileName
propertyOne 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"
}
]
}
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>
SMTP envelope is usually auto generated from from
, to
, cc
and bcc
fields but
if for some reason you want to specify it yourself, you can do it with envelope
property.
envelope
is an object with the following params: from
, to
, cc
and bcc
just like
with regular mail options. You can also use the regular address format.
mailOptions = {
...,
from: "mailer@node.ee",
to: "daemon@node.ee",
envelope: {
from: "Daemon <deamon@node.ee>",
to: "mailer@node.ee, Mailer <mailer2@node.ee>"
}
}
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 gets two parameters
Example:
nodemailer.sendMail(mailOptions, function(error, responseStatus){
if(!error){
console.log(responseStatus.message); // response from the server
}
});
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.
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.
Nodemailer is licensed under MIT license. Basically you can do whatever you want to with it.
FAQs
Easy as cake e-mail sending from your Node.js applications
The npm package nodemailer receives a total of 3,111,647 weekly downloads. As such, nodemailer popularity was classified as popular.
We found that nodemailer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ESLint has added JSON and Markdown linting support with new officially-supported plugins, expanding its versatility beyond JavaScript.
Security News
Members Hub is conducting large-scale campaigns to artificially boost Discord server metrics, undermining community trust and platform integrity.
Security News
NIST has failed to meet its self-imposed deadline of clearing the NVD's backlog by the end of the fiscal year. Meanwhile, CVE's awaiting analysis have increased by 33% since June.