{
  "name": "mailcomposer",
  "description": "Compose E-Mail messages",
  "version": "0.2.7",
  "author": {
    "name": "Andris Reinman"
  },
  "maintainers": [
    {
      "name": "andris",
      "email": "andris@node.ee"
    }
  ],
  "repository": {
    "type": "git",
    "url": "http://github.com/andris9/mailcomposer.git"
  },
  "scripts": {
    "test": "nodeunit test/"
  },
  "main": "./lib/mailcomposer",
  "licenses": [
    {
      "type": "MIT",
      "url": "http://github.com/andris9/mailcomposer/blob/master/LICENSE"
    }
  ],
  "dependencies": {
    "mimelib": "~0.2.14",
    "mime": "1.2.9",
    "he": "~0.3.6",
    "punycode": "~1.2.3",
    "follow-redirects": "0.0.3",
    "dkim-signer": "~0.1.0"
  },
  "devDependencies": {
    "nodeunit": "*",
    "mailparser": "~0.4.0"
  },
  "engine": {
    "node": ">=0.4"
  },
  "keywords": [
    "e-mail",
    "mime",
    "parser"
  ],
  "readme": "# mailcomposer\n\n**mailcomposer** is a Node.JS module for generating e-mail messages that can be\nstreamed to SMTP or file.\n\nThis is a standalone module that only generates raw e-mail source, you need to\nwrite your own or use an existing transport mechanism (SMTP client, Amazon SES,\nSendGrid etc). **mailcomposer** frees you from the tedious task of generating\n[rfc2822](http://tools.ietf.org/html/rfc2822) compatible messages.\n\n[![Build Status](https://secure.travis-ci.org/andris9/mailcomposer.png)](http://travis-ci.org/andris9/mailcomposer)\n\n**mailcomposer** supports:\n\n  * **Unicode** to use any characters ✔\n  * **HTML** content as well as **plain text** alternative\n  * **Attachments** and streaming for larger files (use strings, buffers, files or binary streams as attachments)\n  * **Embedded images** in HTML\n  * **DKIM** signing\n  * usage of **your own** transport mechanism\n\n## Support mailcomposer development\n\n[![Donate to author](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=DB26KWR2BQX5W)\n\n## Installation\n\nInstall through NPM\n\n    npm install mailcomposer\n\n## Usage\n\n### Include mailcomposer module\n\n```javascript\nvar MailComposer = require(\"mailcomposer\").MailComposer;\n```\n\n### Create a new `MailComposer` instance\n\n```javascript\nvar mailcomposer = new MailComposer([options]);\n```\n\nWhere `options` is an optional options object with the following possible properties:\n\n  * **escapeSMTP** - if set replaces dots in the beginning of a line with double dots\n  * **encoding** - sets transfer encoding for the textual parts (defaults to `\"quoted-printable\"`)\n  * **charset** - sets output character set for strings (defaults to `\"utf-8\"`)\n  * **keepBcc** - if set to true, includes `Bcc:` field in the message headers. Useful for *sendmail* command.\n  * **forceEmbeddedImages** - convert image urls and absolute paths in HTML to embedded attachments.\n\n### Simple example\n\nThe following example generates a simple e-mail message with plaintext and html\nbody.\n\n```javascript\nvar MailComposer = require(\"mailcomposer\").MailComposer;\n    mailcomposer = new MailComposer(),\n    fs = require(\"fs\");\n\n// add additional header field\nmailcomposer.addHeader(\"x-mailer\", \"Nodemailer 1.0\");\n\n// setup message data\nmailcomposer.setMessageOption({\n    from: \"andris@tr.ee\",\n    to: \"andris@node.ee\",\n    body: \"Hello world!\",\n    html: \"<b>Hello world!</b>\"\n});\n\nmailcomposer.streamMessage();\n\n// pipe the output to a file\nmailcomposer.pipe(fs.createWriteStream(\"test.eml\"));\n```\n\nThe output for such a script (the contents for \"test.eml\") would look like:\n\n    MIME-Version: 1.0\n    X-Mailer: Nodemailer 1.0\n    From: andris@tr.ee\n    To: andris@node.ee\n    Content-Type: multipart/alternative;\n            boundary=\"----mailcomposer-?=_1-1328088797399\"\n\n    ------mailcomposer-?=_1-1328088797399\n    Content-Type: text/plain; charset=utf-8\n    Content-Transfer-Encoding: quoted-printable\n\n    Hello world!\n    ------mailcomposer-?=_1-1328088797399\n    Content-Type: text/html; charset=utf-8\n    Content-Transfer-Encoding: quoted-printable\n\n    <b>Hello world!</b>\n    ------mailcomposer-?=_1-1328088797399--\n\n## API\n\n### Add custom headers\n\nHeaders can be added with `mailcomposer.addHeader(key, value[, formatted])` where `formatted` indicates if the value should be kept as is. If the value is missing or falsy, header value is sanitized and folded. If true, the value is passed to output as is.\n\n```javascript\nvar mailcomposer = new MailComposer();\nmailcomposer.addHeader(\"x-mailer\", \"Nodemailer 1.0\");\n```\n\nIf you add an header value with the same key several times, all of the values will be used\nin the generated header. For example:\n\n```javascript\nmailcomposer.addHeader(\"x-mailer\", \"Nodemailer 1.0\");\nmailcomposer.addHeader(\"x-mailer\", \"Nodemailer 2.0\");\n```\n\nWill be generated into\n\n    ...\n    X-Mailer: Nodemailer 1.0\n    X-Mailer: Nodemailer 2.0\n    ...\n\nThe contents of the field value is not edited in any way (except for the folding),\nso if you want to use unicode symbols you need to escape these to mime words\nby yourself. Exception being object values - in this case the object\nis automatically JSONized and mime encoded.\n\n```javascript\n// using objects as header values is allowed (will be converted to JSON)\nvar apiOptions = {};\napiOptions.category = \"newuser\";\napiOptions.tags = [\"user\", \"web\"];\nmailcomposer.addHeader(\"X-SMTPAPI\", apiOptions)\n```\n\n### Add message parts\n\nYou can set message sender, receiver, subject line, message body etc. with\n`mailcomposer.setMessageOption(options)` where options is an object with the\ndata to be set. This function overwrites any previously set values with the\nsame key\n\nThe following example creates a simple e-mail with sender being `andris@tr.ee`,\nreceiver `andris@node.ee` and plaintext part of the message as `Hello world!`:\n\n```javascript\nmailcomposer.setMessageOption({\n    from: \"andris@tr.ee\",\n    to: \"andris@node.ee\",\n    body: \"Hello world!\"\n});\n```\n\nPossible options that can be used are (all fields accept unicode):\n\n  * **from** (alias `sender`) - the sender of the message. If several addresses are given, only the first one will be used\n  * **to** - receivers for the `To:` field\n  * **cc** - receivers for the `Cc:` field\n  * **bcc** - receivers for the `Bcc:` field\n  * **replyTo** (alias `reply_to`) - e-mail address for the `Reply-To:` field\n  * **inReplyTo** - The message-id this message is replying\n  * **references** - Message-id list\n  * **subject** - the subject line of the message\n  * **body** (alias `text`) - the plaintext part of the message\n  * **html** - the HTML part of the message\n  * **envelope** - optional SMTP envelope, if auto generated envelope is not suitable\n\nThis method can be called several times\n\n```javascript\nmailcomposer.setMessageOption({from: \"andris@tr.ee\"});\nmailcomposer.setMessageOption({to: \"andris@node.ee\"});\nmailcomposer.setMessageOption({body: \"Hello world!\"});\n```\n\nTrying to set the same key several times will yield in overwrite\n\n```javascript\nmailcomposer.setMessageOption({body: \"Hello world!\"});\nmailcomposer.setMessageOption({body: \"Hello world?\"});\n// body contents will be \"Hello world?\"\n```\n\n### Address format\n\nAll e-mail address fields take structured e-mail lists (comma separated)\nas the input. Unicode is allowed for all the parts (receiver name, e-mail username\nand domain) of the address. If the domain part contains unicode symbols, it is\nautomatically converted into punycode, user part will be converted into UTF-8\nmime word.\n\nE-mail addresses can be a plain e-mail addresses\n\n    username@example.com\n\nor with a formatted name\n\n    'Ноде Майлер' <username@example.com>\n\nOr in case of comma separated lists, the formatting can be mixed\n\n    username@example.com, 'Ноде Майлер' <username@example.com>, \"Name, User\" <username@example.com>\n\n### SMTP envelope\n\nSMTP envelope is usually auto generated from `from`, `to`, `cc` and `bcc` fields but\nif for some reason you want to specify it yourself, you can do it with `envelope` property.\n\n`envelope` is an object with the following params: `from`, `to`, `cc` and `bcc` just like\nwith regular mail options. You can also use the regular address format.\n\n```javascript\nmailOptions = {\n    ...,\n    from: \"mailer@node.ee\",\n    to: \"daemon@node.ee\",\n    envelope: {\n        from: \"Daemon <deamon@node.ee>\",\n        to: \"mailer@node.ee, Mailer <mailer2@node.ee>\"\n    }\n}\n```\n\n### Add attachments\n\nAttachments can be added with `mailcomposer.addAttachment(attachment)` where\n`attachment` is an object with attachment (meta)data with the following possible\nproperties:\n\n  * **fileName** (alias `filename`) - filename to be reported as the name of the attached file, use of unicode is allowed\n  * **cid** - content id for using inline images in HTML message source\n  * **contents** - String or a Buffer contents for the attachment\n  * **filePath** - path to a file or an URL if you want to stream the file instead of including it (better for larger attachments)\n  * **streamSource** - Stream object for arbitrary binary streams if you want to stream the contents (needs to support *pause*/*resume*)\n  * **contentType** - content type for the attachment, if not set will be derived from the `fileName` property\n  * **contentDisposition** - content disposition type for the attachment, defaults to \"attachment\"\n  * **userAgent** - User-Agent string to be used if the fileName points to an URL\n\nOne of `contents`, `filePath` or `streamSource` must be specified, if none is\npresent, the attachment will be discarded. Other fields are optional.\n\nAttachments can be added as many as you want.\n\n**Using embedded images in HTML**\n\nAttachments can be used as embedded images in the HTML body. To use this\nfeature, you need to set additional property of the attachment - `cid`\n(unique identifier of the file) which is a reference to the attachment file.\nThe same `cid` value must be used as the image URL in HTML (using `cid:` as\nthe URL protocol, see example below).\n\nNB! the cid value should be as unique as possible!\n\n```javascript\nvar cid_value = Date.now() + '.image.jpg';\n\nvar html = 'Embedded image: <img src=\"cid:' + cid_value + '\" />';\n\nvar attachment = {\n    fileName: \"image.png\",\n    filePath: \"/static/images/image.png\",\n    cid: cid_value\n};\n```\n\n**Automatic embedding images**\n\nIf you want to convert images in the HTML to embedded images automatically, you can\nset mailcomposer option `forceEmbeddedImages` to true. In this case all images in\nthe HTML that are either using an absolute URL (http://...) or absolute file path\n(/path/to/file) are replaced with embedded attachments.\n\nFor example when using this code\n\n```javascript\nvar mailcomposer = new MailComposer({forceEmbeddedImages: true});\nmailcomposer.setMessageOption({\n    html: 'Embedded image: <img src=\"http://example.com/image.png\">'\n});\n```\n\nThe image linked is fetched and added automatically as an attachment and the url\nin the HTML is replaced automatically with a proper `cid:` string.\n\n### Add alternatives to HTML and text\n\nIn 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.\n\nAlternatives to text and HTML can be added with `mailcomposer.addAlternative(alternative)` where\n`alternative` is an object with alternative (meta)data with the following possible\nproperties:\n\n  * **contents** - String or a Buffer contents for the attachment\n  * **contentType** - optional content type for the attachment, if not set will be set to \"application/octet-stream\"\n  * **contentEncoding** - optional value of how the data is encoded, defaults to \"base64\"\n\nIf `contents` is empty, the alternative will be discarded. Other fields are optional.\n\n**Usage example:**\n\n```javascript\n// add HTML \"alternative\"\nmailcomposer.setMessageOption({\n    html: \"<b>Hello world!</b>\"\n});\n\n// add Markdown alternative\nmailcomposer.addAlternative({\n    contentType: \"text/x-web-markdown\",\n    contents: \"**Hello world!**\"\n});\n```\n\nIf the receiving e-mail client can render messages in Markdown syntax as well, it could prefer\nto display this alternative as the main content of the message.\n\nAlternatives can be added as many as you want.\n\n### DKIM Signing\n\n**mailcomposer** supports DKIM signing with very simple setup. Use this with caution\nthough since the generated message needs to be buffered entirely before it can be\nsigned - in this case the streaming capability offered by mailcomposer is illusionary,\nthere will only be one `'data'` event with the entire message. Not a big deal with\nsmall messages but might consume a lot of RAM when using larger attachments.\n\nSet up the DKIM signing with `useDKIM` method:\n\n```javascript\nmailcomposer.useDKIM(dkimOptions)\n```\n\nWhere `dkimOptions` includes necessary options for signing\n\n  * **domainName** - the domainname that is being used for signing\n  * **keySelector** - key selector. If you have set up a TXT record with DKIM public key at *zzz._domainkey.example.com* then `zzz` is the selector\n  * **privateKey** - DKIM private key that is used for signing as a string\n  * **headerFieldNames** - optional colon separated list of header fields to sign, by default all fields suggested by RFC4871 #5.5 are used\n\n**NB!** Currently if several header fields with the same name exists, only the last one (the one in the bottom) is signed.\n\nExample:\n\n```javascript\nmailcomposer.setMessageOption({from: \"andris@tr.ee\"});\nmailcomposer.setMessageOption({to: \"andris@node.ee\"});\nmailcomposer.setMessageOption({body: \"Hello world!\"});\nmailcomposer.useDKIM({\n    domainName: \"node.ee\",\n    keySelector: \"dkim\",\n    privateKey: fs.readFileSync(\"private_key.pem\")\n});\n```\n\n### Start streaming\n\nWhen the message data is setup, streaming can be started. After this it is not\npossible to add headers, attachments or change body contents.\n\n```javascript\nmailcomposer.streamMessage();\n```\n\nThis generates `'data'` events for the message headers and body and final `'end'` event.\nAs `MailComposer` objects are Stream instances, these can be piped\n\n```javascript\n// save the output to a file\nmailcomposer.streamMessage();\nmailcomposer.pipe(fs.createWriteStream(\"out.txt\"));\n```\n\n### Compile the message in one go\n\nIf you do not want to use the streaming possibilities, you can compile the entire\nmessage into a string in one go with `buildMessage`.\n\n```javascript\nmailcomposer.buildMessage(function(err, messageSource){\n    console.log(err || messageSource);\n});\n```\n\nThe function is actually just a wrapper around `streamMessage` and emitted events.\n\n## Envelope\n\nEnvelope can be generated with an `getEnvelope()` which returns an object\nthat includes a `from` address (string) and a list of `to` addresses (array of\nstrings) suitable for forwarding to a SMTP server as `MAIL FROM:` and `RCPT TO:`.\n\n```javascript\nconsole.log(mailcomposer.getEnvelope());\n// {from:\"sender@example.com\", to:[\"receiver@example.com\"]}\n```\n\n**NB!** both `from` and `to` properties might be missing from the envelope object\nif corresponding addresses were not detected from the e-mail.\n\n## Running tests\n\nTests are run with [nodeunit](https://github.com/caolan/nodeunit)\n\nRun\n\n    npm test\n\n## License\n\n**MIT**\n",
  "readmeFilename": "README.md",
  "bugs": {
    "url": "https://github.com/andris9/mailcomposer/issues"
  },
  "_id": "mailcomposer@0.2.7",
  "dist": {
    "shasum": "da896c28ceacb2c97cb5fc9b18d55a23b749c54c"
  },
  "_from": "mailcomposer@~0.2.7",
  "_resolved": "https://registry.npmjs.org/mailcomposer/-/mailcomposer-0.2.7.tgz"
}
