# mailcomposer

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

This is a standalone module that only generates raw e-mail source, you need to 
write your own or use an existing transport mechanism (SMTP client, Amazon SES, 
SendGrid etc). **mailcomposer** frees you from the tedious task of generating 
[rfc822](http://tools.ietf.org/html/rfc2822) compatible messages.

[![Build Status](https://secure.travis-ci.org/andris9/mailcomposer.png)](http://travis-ci.org/andris9/mailcomposer)

See autogenerated docs [here](http://www.node.ee/mcdoc/).

**mailcomposer** supports:

  * **Unicode** to use any characters ✔
  * **HTML** content as well as **plain text** alternative
  * **Attachments** and streaming for larger files
  * **Embedded images** in HTML
  * usage of **your own** transport mechanism

## Installation

Install through NPM

    npm install mailcomposer

## Usage

### Include mailcomposer module

    var MailComposer = require("mailcomposer").MailComposer;

### Create a new `MailComposer` instance

    var mailcomposer = new MailComposer([options]);

Where `options` is an optional options object with the following possible properties:

  * **escapeSMTP** - if set replaces dots in the beginning of a line with double dots
  * **encoding** - sets transfer encoding for the textual parts (defaults to `"quoted-printable"`)
  * **keepBcc** - if set to true, includes `Bcc:` field in the message headers. Useful for *sendmail* command. 

### Simple example

The following example generates a simple e-mail message with plaintext and html
body.

    var MailComposer = require("mailcomposer").MailComposer;
        mailcomposer = new MailComposer(),
        fs = require("fs");
    
    // add additional header field
    mailcomposer.addHeader("x-mailer", "Nodemailer 1.0");
    
    // setup message data
    mailcomposer.setMessageOption({
        from: "andris@tr.ee",
        to: "andris@node.ee",
        body: "Hello world!",
        html: "<b>Hello world!</b>"
    }); 
    
    mailcomposer.streamMessage();
    
    // pipe the output to a file
    mailcomposer.pipe(fs.createWriteStream("test.eml"));

The output for such a script (the contents for "test.eml") would look like:

    MIME-Version: 1.0
    X-Mailer: Nodemailer 1.0
    From: andris@tr.ee
    To: andris@node.ee
    Content-Type: multipart/alternative;
            boundary="----mailcomposer-?=_1-1328088797399"
    
    ------mailcomposer-?=_1-1328088797399
    Content-Type: text/plain; charset=utf-8
    Content-Transfer-Encoding: quoted-printable
    
    Hello world!
    ------mailcomposer-?=_1-1328088797399
    Content-Type: text/html; charset=utf-8
    Content-Transfer-Encoding: quoted-printable
    
    <b>Hello world!</b>
    ------mailcomposer-?=_1-1328088797399--

## API

### Add custom headers

Headers can be added with `mailcomposer.addHeader(key, value)`

    var mailcomposer = new MailComposer();
    mailcomposer.addHeader("x-mailer", "Nodemailer 1.0");

If you add an header value with the same key several times, all of the values will be used
in the generated header. For example:

    mailcomposer.addHeader("x-mailer", "Nodemailer 1.0");
    mailcomposer.addHeader("x-mailer", "Nodemailer 2.0");
    
Will be generated into

    ...
    X-Mailer: Nodemailer 1.0
    X-Mailer: Nodemailer 2.0
    ...

The contents of the field value is not edited any way (except for the folding),
so if you want to use unicode symbols you need to escape these to mime words
by yourself.

### Add message parts

You can set message sender, receiver, subject line, message body etc. with
`mailcomposer.setMessageOption(options)` where options is an object with the
data to be set. This function overwrites any previously set values with the
same key

The following example creates a simple e-mail with sender being `andris@tr.ee`, 
receiver `andris@node.ee` and plaintext part of the message as `Hello world!`:

    mailcomposer.setMessageOption({
        from: "andris@tr.ee",
        to: "andris@node.ee",
        body: "Hello world!"
    }); 

Possible options that can be used are (all fields accept unicode):

  * **from** (alias `sender`) - the sender of the message. If several addresses are given, only the first one will be used
  * **to** - receivers for the `To:` field
  * **cc** - receivers for the `Cc:` field
  * **bcc** - receivers for the `Bcc:` field
  * **replyTo** (alias `reply_to`) - e-mail address for the `Reply-To:` field
  * **subject** - the subject line of the message
  * **body** (alias `text`) - the plaintext part of the message
  * **html** - the HTML part of the message

This method can be called several times

    mailcomposer.setMessageOption({from: "andris@tr.ee"});
    mailcomposer.setMessageOption({to: "andris@node.ee"});
    mailcomposer.setMessageOption({body: "Hello world!"});

Trying to set the same key several times will yield in overwrite

    mailcomposer.setMessageOption({body: "Hello world!"});
    mailcomposer.setMessageOption({body: "Hello world?"});
    // body contents will be "Hello world?"

### Address format

All e-mail address fields take structured e-mail lists (comma separated)
as the input. Unicode is allowed for all the parts (receiver name, e-mail username
and domain) of the address. If the domain part contains unicode symbols, it is
automatically converted into punycode, user part will be converted into UTF-8
mime word.

E-mail addresses can be a plain e-mail addresses

    username@example.com

or with a formatted name

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

Or in case of comma separated lists, the formatting can be mixed

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

### Add attachments

Attachments can be added with `mailcomposer.addAttachment(attachment)` where
`attachment` is an object with attachment (meta)data with the following possible
properties:

  * **fileName** (alias `filename`) - filename to be reported as the name of the attached file, use of unicode is allowed
  * **cid** - 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** - 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.

**Using embedded images in HTML**

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 cid_value = Date.now() + '.image.jpg';
    
    var html = 'Embedded image: <img src="cid:' + cid_value + '" />';
    
    var attachment = {
        fileName: "image.png",
        filePath: "/static/images/image.png",
        cid: cid_value
    };

### Start streaming

When the message data is setup, streaming can be started. After this it is not
possible to add headers, attachments or change body contents.

    mailcomposer.streamMessage();

This generates `'data'` events for the message headers and body and final `'end'` event.
As `MailComposer` objects are Stream instances, these can be piped

    // save the output to a file
    mailcomposer.streamMessage();
    mailcomposer.pipe(fs.createWriteStream("out.txt"));

## Envelope

Envelope is emitted with an `'envelope'` event and it has an object as a param
that includes a `from` address (string) and a list of `to` addresses (array of
strings) suitable for forwarding to a SMTP server as `MAIL FROM:` and `RCPT TO:`.

    mailcomposer.on("envelope", function(envelope){
        console.log(envelope);
        // {from:"sender@example.com", to:["receiver@example.com"]}
    });

**NB!** both `from` and `to` properties might be missing from the envelope object
if corresponding addresses were not detected from the e-mail.

## Running tests

Tests are run with [nodeunit](https://github.com/caolan/nodeunit)

Run

    npm test

or alternatively

    node run_tests.js

## License

**MIT**