-
Notifications
You must be signed in to change notification settings - Fork 109
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Showing
10 changed files
with
422 additions
and
510 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| .travis.yml | ||
| ex | ||
| test |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| The MIT License (MIT) | ||
|
|
||
| Copyright (c) 2014 -2017 Guileen | ||
| Copyright (c) 2016 -2017 Green Pioneer | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,10 +1,13 @@ | ||
| [![npm][npm-image]][npm-url] | ||
| [![downloads][downloads-image]][downloads-url] | ||
| [![npm-issues][npm-issues-image]][npm-issues-url] | ||
| [![js-standard-style][standard-image]][standard-url] | ||
|
|
||
| [standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg | ||
| [standard-url]: http://standardjs.com/ | ||
| [npm-image]: https://img.shields.io/npm/v/sendmail.svg?style=flat | ||
| [npm-url]: https://npmjs.org/package/sendmail | ||
| [downloads-image]: https://img.shields.io/npm/dm/sendmail.svg?style=flat | ||
| [downloads-image]: https://img.shields.io/npm/dt/sendmail.svg?style=flat | ||
| [downloads-url]: https://npmjs.org/package/sendmail | ||
| [npm-issues-image]: https://img.shields.io/github/issues/guileen/node-sendmail.svg | ||
| [npm-issues-url]: https://github.com/guileen/node-sendmail/issues | ||
|
|
@@ -26,7 +29,12 @@ var sendmail = require('sendmail')({ | |
| warn: console.warn, | ||
| error: console.error | ||
| }, | ||
| silent: false | ||
| silent: false, | ||
| dkim: { // Default: False | ||
| privateKey: fs.readFileSync('./dkim-private.pem', 'utf8'), | ||
| keySelector: 'mydomainkey' | ||
| }, | ||
| devPort: 1025 // Default: False | ||
| }) | ||
| ``` | ||
| * `logger` customized logger. | ||
|
|
@@ -47,209 +55,75 @@ sendmail({ | |
| console.dir(reply); | ||
| }); | ||
| ``` | ||
| ### Examples | ||
|
|
||
| Please checkout our great examples | ||
| - **[attachmentFile](https://github.com/guileen/node-sendmail/blob/master/examples/attachmentFile)** | ||
| - **[developmentMode.js](https://github.com/guileen/node-sendmail/blob/master/examples/developmentMode)** | ||
| - **[dkim.js](https://github.com/guileen/node-sendmail/blob/master/examples/dkim)** | ||
| - **[meetingRequest.js](https://github.com/guileen/node-sendmail/blob/master/examples/meetingRequest)** | ||
| - **[simple.js](https://github.com/guileen/node-sendmail/blob/master/examples/simple)** | ||
|
|
||
| ### 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 `'[email protected]'` or formatted `'Sender Name <[email protected]>'`, see [here](#address-formatting) for details | ||
| - **sender** - An e-mail address that will appear on the *Sender:* field | ||
| - **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 (an array or space separated string) | ||
| - **subject** - The subject of the e-mail | ||
| - **text** - The plaintext version of the message as an Unicode string, Buffer, Stream or an object *{path: '...'}* | ||
| - **html** - The HTML version of the message as an Unicode string, Buffer, Stream or an object *{path: '...'}* | ||
| - **watchHtml** - Apple Watch specific HTML version of the message, same usage as with `text` and `html` | ||
| - **icalEvent** - iCalendar event, same usage as with `text` and `html`. Event `method` attribute defaults to 'PUBLISH' or define it yourself: `{method: 'REQUEST', content: iCalString}`. This value is added as an additional alternative to html or text. Only utf-8 content is allowed | ||
| - **headers** - An object or array of additional header fields (e.g. *{"X-Key-Name": "key value"}* or *[{key: "X-Key-Name", value: "val1"}, {key: "X-Key-Name", value: "val2"}]*) | ||
| - **attachments** - An array of attachment objects (see [below](#attachments) for details) | ||
| - **alternatives** - An array of alternative text contents (in addition to text and html parts) (see [below](#alternatives) for details) | ||
| - **envelope** - optional SMTP envelope, if auto generated envelope is not suitable (see [below](#smtp-envelope) for details) | ||
| - **messageId** - optional Message-Id value, random value will be generated if not set | ||
| - **date** - optional Date value, current UTC string will be used if not set | ||
| - **encoding** - optional transfer encoding for the textual parts | ||
| - **raw** - if set then overwrites entire message output with this value. The value is not parsed, so you should still set address headers or the envelope value for the message to work | ||
| - **textEncoding** - set explicitly which encoding to use for text parts (*quoted-printable* or *base64*). If not set then encoding is detected from text content (mostly ascii means *quoted-printable*, otherwise *base64*) | ||
|
|
||
| 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: | ||
|
|
||
| * **filename** - filename to be reported as the name of the attached file, use of unicode is allowed. If you do not want to use a filename, set this value as `false`, otherwise a filename is generated automatically | ||
| * **cid** - optional content id for using inline images in HTML message source. Using `cid` sets the default `contentDisposition` to `'inline'` and moves the attachment into a *multipart/related* mime node, so use it only if you actually want to use this attachment as an embedded image | ||
| * **content** - String, Buffer or a Stream contents for the attachment | ||
| * **encoding** - If set and `content` is string, then encodes the content to a Buffer using the specified encoding. Example values: `base64`, `hex`, `binary` etc. Useful if you want to use binary attachments in a JSON formatted e-mail object | ||
| * **path** - path to a file or an URL (data uris are allowed as well) if you want to stream the file instead of including it (better for larger attachments) | ||
| * **contentType** - optional content type for the attachment, if not set will be derived from the `filename` property | ||
| * **contentTransferEncoding** - optional transfer encoding for the attachment, if not set it will be derived from the `contentType` property. Example values: `quoted-printable`, `base64` | ||
| * **contentDisposition** - optional content disposition type for the attachment, defaults to 'attachment' | ||
| * **headers** is an object of additional headers, similar to *message.headers* option `{'X-My-Header': 'value'}` | ||
| * **raw** is an optional value that overrides entire node content in the mime message. If used then all other options set for this node are ignored. The value is either a string, a buffer, a stream or an attachment-like object (eg. provides `path` or `content`) | ||
|
|
||
| Attachments can be added as many as you want. | ||
|
|
||
| ```javascript | ||
| 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. | ||
| ### Upgrading | ||
|
|
||
| Alternative objects use the same options as [attachment objects](#attachments). 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. | ||
| Note if you were on any previous version before `<1.0.0` You will need to start using `html` instead of `content`. Instead of creating emails ourselves anymore we have decided to use `mailcomposer` to compose our emails. Which means we can give you the same great package with the best mail composer package out there. | ||
|
|
||
| **Usage example:** | ||
| ### Mail Options | ||
| Note we use `mailcomposer` to compose our mail before we send it out so all mail options will be well documented [Here](https://github.com/nodemailer/mailcomposer). But for those who want something particular go ahead and search down below. | ||
|
|
||
| ```javascript | ||
| var mailOptions = { | ||
| ... | ||
| html: '<b>Hello world!</b>', | ||
| alternatives: [ | ||
| { | ||
| contentType: 'text/x-web-markdown', | ||
| content: '**Hello world!**' | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| ##### E-mail message fields | ||
| Below are a list of the most used options for email fields. Please read the entire list of options here [Here](https://github.com/nodemailer/mailcomposer#e-mail-message-fields): | ||
|
|
||
| Alternatives can be added as many as you want. | ||
| - **from** | ||
| - **sender** | ||
| - **to** | ||
| - **cc** | ||
| - **bcc** | ||
| - **replyTo** | ||
| - **inReplyTo** | ||
| - **subject** | ||
| - **text** | ||
| - **html** | ||
|
|
||
| ##### Attachments | ||
| You are also able to send attachents. Please review the list of properties here [Here](https://github.com/nodemailer/mailcomposer#attachments) | ||
|
|
||
| ### Address Formatting | ||
|
|
||
| All the e-mail addresses can be plain e-mail addresses | ||
|
|
||
| ``` | ||
| [email protected] | ||
| ``` | ||
|
|
||
| or with formatted name (includes unicode support) | ||
|
|
||
| ``` | ||
| "Ноде Майлер" <[email protected]> | ||
| ``` | ||
|
|
||
| > 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: `"Майлер, Ноде" <[email protected]>` | ||
|
|
||
| or as an address object (in this case you do not need to worry about the formatting, no need to use quotes etc.) | ||
| ##### Alternatives | ||
| In addition to text and HTML, any kind of data can be inserted as an alternative content of the main body. Please check that out [Here](https://github.com/nodemailer/mailcomposer#alternatives) | ||
|
|
||
| ``` | ||
| { | ||
| name: 'Майлер, Ноде', | ||
| address: '[email protected]' | ||
| } | ||
| ``` | ||
|
|
||
| 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. | ||
| ##### Address Formatting | ||
|
|
||
| ``` | ||
| ..., | ||
| to: '[email protected], "Ноде Майлер" <[email protected]>, "Name, User" <[email protected]>', | ||
| cc: ['[email protected]', '"Ноде Майлер" <[email protected]>, "Name, User" <[email protected]>'], | ||
| bcc: ['[email protected]', {name: 'Майлер, Ноде', address: '[email protected]'}] | ||
| ... | ||
| ``` | ||
| All e-mail addresses can be formatted. Please check that out [Here](https://github.com/nodemailer/mailcomposer#address-formatting) | ||
|
|
||
| You can even use unicode domains, these are automatically converted to punycode | ||
|
|
||
| ``` | ||
| '"Unicode Domain" <info@müriaad-polüteism.info>' | ||
| ``` | ||
| ##### SMTP envelope | ||
|
|
||
| ### SMTP envelope | ||
| SMTP envelope is usually auto generated from `from`, `to`, `cc` and `bcc` fields but you can change them [Here](https://github.com/nodemailer/mailcomposer#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. | ||
| ##### Using Embedded Images | ||
|
|
||
| `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. | ||
| Attachments can be used as embedded images in the HTML body. To use this feature, you need to set additional properties [Here](https://github.com/nodemailer/mailcomposer#using-embedded-images) | ||
|
|
||
| ```javascript | ||
| mailOptions = { | ||
| ..., | ||
| from: '[email protected]', | ||
| to: '[email protected]', | ||
| envelope: { | ||
| from: 'Daemon <[email protected]>', | ||
| to: '[email protected], Mailer <[email protected]>' | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| > 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 | ||
| ### Questions, Comments & Concerns | ||
|
|
||
| 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). | ||
| Please reach out to [Green Pioneer](https://github.com/greenpioneer). [Guileen](https://github.com/guileen) is the original creator. | ||
|
|
||
| **NB!** the cid value should be as unique as possible! | ||
| ### Change Log | ||
|
|
||
| ```javascript | ||
| var mailOptions = { | ||
| ... | ||
| html: 'Embedded image: <img src="cid:[email protected]"/>', | ||
| attachments: [{ | ||
| filename: 'image.png', | ||
| path: '/path/to/file', | ||
| cid: '[email protected]' //same cid value as in the html img src | ||
| }] | ||
| } | ||
| ``` | ||
| ##### 1.0.0 Mail Composer | ||
| A better way to compose the emails while still sending them out in the exact same way. | ||
|
|
||
| ##### 1.1.0 Support for development SMTP | ||
| A property describing a port for a local SMTP server (see [MailHog](https://github.com/mailhog/MailHog)) was added. If the property is omitted, sendmail behaves like it used to. This feature makes it possible to test an application offline and for multiple email addresses without needing to create hundreds of mail accounts. - Special thanks goes out to gumannp for [PR 21](https://github.com/guileen/node-sendmail/pull/21) | ||
|
|
||
| ### Questions, Comments & Concerns | ||
| ##### 1.1.0 Add DKIM signing | ||
| Added a `dkim` object to options that can have two properties: `privateKey` and `keySelector`. These options correspond to the options for [`dkim-signer`](https://github.com/andris9/dkim-signer). Added an example for these options. Special thanks goes out to download13 for [PR 23](https://github.com/guileen/node-sendmail/pull/23) | ||
|
|
||
| Please reach out to [Green Pioneer](https://github.com/greenpioneer). [Guileen](https://github.com/guileen) is the original creator. | ||
|
|
||
| ### Roadmap | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,46 +1,46 @@ | ||
| var sendmail = require('../sendmail')({silent:true}); | ||
| var sendmail = require('../sendmail')({silent: true}) | ||
| sendmail({ | ||
| from: '[email protected]', | ||
| to: '[email protected]', | ||
| replyTo: '[email protected]', | ||
| subject: 'MailComposer sendmail', | ||
| html: 'Mail of test sendmail ', | ||
| 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') | ||
| }, | ||
| from: '[email protected]', | ||
| to: '[email protected]', | ||
| replyTo: '[email protected]', | ||
| subject: 'MailComposer sendmail', | ||
| html: 'Mail of test sendmail ', | ||
| 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' | ||
| // }, | ||
| { // 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/guileen/node-sendmail/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=' | ||
| } | ||
| ] | ||
| }, function(err, reply) { | ||
| console.log(err && err.stack); | ||
| console.dir(reply); | ||
| }); | ||
| { // 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/guileen/node-sendmail/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=' | ||
| } | ||
| ] | ||
| }, function (err, reply) { | ||
| console.log(err && err.stack) | ||
| console.dir(reply) | ||
| }) | ||
|
|
Oops, something went wrong.