/ never-odd-or-even / back / node_modules / mailcomposer /

[ICO]NameLast modifiedSizeDescription
[PARENTDIR]Parent Directory  -  
[DIR]node_modules/2 years ago -  
[DIR]lib/2 years ago -  
[   ]package.json2 years ago1.8K 
[TXT]README.md9 years ago 11K 
[   ]LICENSE9 years ago935  
[   ]Gruntfile.js9 years ago577  
README.md

mailcomposer

mailcomposer is a Node.JS module for generating e-mail messages that can be streamed to SMTP or file.

NB! This module is not backwards compatible with versions 0.x

Build Status

Support mailcomposer development

Donate to author

Installation

Install through NPM

npm install mailcomposer

Usage

Include mailcomposer module

var mailcomposer = require("mailcomposer");

Create a new MailComposer instance

var mail = mailcomposer(mailOptions);

Where mailOptions is an object that defines the components of the message, see below

API

createReadStream

To create a stream that outputs a raw rfc822 message from the defined input, use createReadStream()

var mail = mailcomposer({from: '...', ...});
var stream = mail.createReadStream();
stream.pipe(process.stdout);

build

To generate the message and return it with a callback use build()

var mail = mailcomposer({from: '...', ...});
mail.build(function(err, message){
    process.stdout.write(message);
});

E-mail message fields

The following are the possible fields of an e-mail message:

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

Attachments

Attachment object consists of the following properties:

Attachments can be added as many as you want.

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

Alternatives

In addition to text and HTML, any kind of data can be inserted as an alternative content of the main body - for example a word processing document with the same text as in the HTML field. It is the job of the e-mail client to select and show the best fitting alternative to the reader. Usually this field is used for calendar events and such.

Alternative objects use the same options as attachment objects. The difference between an attachment and an alternative is the fact that attachments are placed into multipart/mixed or multipart/related parts of the message white alternatives are placed into multipart/alternative part.

Usage example:

var mailOptions = {
    ...
    html: '<b>Hello world!</b>',
    alternatives: [
        {
            contentType: 'text/x-web-markdown',
            content: '**Hello world!**'
        }
    ]
}

Alternatives can be added as many as you want.

Address Formatting

All the e-mail addresses can be plain e-mail addresses

foobar@blurdybloop.com

or with formatted name (includes unicode support)

"Ноде Майлер" <foobar@blurdybloop.com>

Notice that all address fields (even from) are comma separated lists, so if you want to use a comma in the name part, make sure you enclose the name in double quotes: "Майлер, Ноде" <foobar@blurdybloop.com>

or as an address object (in this case you do not need to worry about the formatting, no need to use quotes etc.)

{
    name: 'Майлер, Ноде',
    address: 'foobar@blurdybloop.com'
}

All address fields accept comma separated list of e-mails or an array of e-mails or an array of comma separated list of e-mails or address objects - use it as you like. Formatting can be mixed.

...,
to: 'foobar@blurdybloop.com, "Ноде Майлер" <bar@blurdybloop.com>, "Name, User" <baz@blurdybloop.com>',
cc: ['foobar@blurdybloop.com', '"Ноде Майлер" <bar@blurdybloop.com>, "Name, User" <baz@blurdybloop.com>'],
bcc: ['foobar@blurdybloop.com', {name: 'Майлер, Ноде', address: 'foobar@blurdybloop.com'}]
...

You can even use unicode domains, these are automatically converted to punycode

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

SMTP envelope

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, unicode domains etc.

mailOptions = {
    ...,
    from: 'mailer@kreata.ee',
    to: 'daemon@kreata.ee',
    envelope: {
        from: 'Daemon <deamon@kreata.ee>',
        to: 'mailer@kreata.ee, Mailer <mailer2@kreata.ee>'
    }
}

Not all transports can use the envelope object, for example SES ignores it and uses the data from the From:, To: etc. headers.

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

License

MIT

Apache/2.4.38 (Debian) Server at www.karls.computer Port 80