Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

updated readme

  • Loading branch information...
commit 3c3cca5bd7448ff709a30b694dc154da8e2d1fda 1 parent 92101e7
Andris Reinman authored
Showing with 259 additions and 13 deletions.
  1. +258 −12 README.md
  2. +1 −1  lib/engines/sendmail.js
View
270 README.md
@@ -1,14 +1,158 @@
Nodemailer
==========
+**Nodemailer** is an easy to use module to send e-mails with Node.JS (using
+SMTP or sendmail) and it's Unicode friendly - You can use any characters you like ✔
+
This is a project for a new version of Nodemailer, built from scratch.
[Autogenerated docs](http://www.node.ee/maildoc/)
-## Well known services for SMTP
+Use [DocumentUp](http://documentup.com/andris9/nodemailer/) to read this README
+in a more structured way (with TOC).
+
+[![Build Status](https://secure.travis-ci.org/andris9/Nodemailer.png)](http://travis-ci.org/andris9/Nodemailer)
+
+## Nodemailer supports
+
+ * **Unicode** to use any characters
+ * **HTML content** as well as **plain text** alternative
+ * **Attachments** (including attachment **streaming** for sending larger files)
+ * **Embedded images** in HTML
+ * **SSL/TLS** for secure e-mail delivery
+ * Different transport methods - **SMTP**, **sendmail** and **Amazon SES**
+ * **Connection pool** for SMTP for rapid delivery
+
+## Check out my other mail related modules
+
+If you want to parse generated or received e-mail instead of sending it, check
+out [MailParser](https://github.com/andris9/mailparser).
+
+If you only want to generate the raw e-mail stream, check out
+[MailComposer](https://github.com/andris9/mailcomposer).
+
+If you only want to communicate with the SMTP (both as client and the server),
+check out [simplesmtp](https://github.com/andris9/simplesmtp).
+
+## Installation
+
+Install through NPM
+
+ npm install nodemailer
+
+## Usage
+
+Include the module
+
+ var nodemailer = require("nodemailer");
+
+An e-mail can be sent with `sendMail(mailOptions, callback)` command
+
+ nodemailer.send_mail(mailOptions, callback);
+
+Where
+
+ `mailOptions` defines the e-mail (set its subject, body text, receivers etc.), see **E-mail Message Fields** for details
+ `callback` is the callback function that will be run after the e-mail is sent or the sending failed
+
+## Setting up a transport method
+
+Before you can send any e-mail you need to set up a transport method. This can
+be done with `new nodemailer.Transport(type, options)` where `type` indicates
+the transport protocol and `options` defines how it used.
+
+ var transport = new nodemailer.Transport("SMTP", {smtp_options});
+
+The same transport object can and should be reused several times.
+
+When the transport method is defined, it should be attached to the message
+object as `transport`
+
+ var transport = new nodemailer.Transport("SMTP", {smtp_options});
+
+ var mailOptions = {
+ from: "sender@tr.ee",
+ to: "receiver@tr.ee",
+ transport: transport
+ };
+
+### Possible transport methods
+
+`type` parameter can be one of the following:
+
+ * **SMTP** for using SMTP
+ * **SES** for using Amazon SES
+ * **Sendmail** for utilizing systems *sendmail* command
+
+### Setting up SMTP
+
+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** - a well known service identifier ("Gmail", "Hotmail" etc., see **Well known Services** below) for auto-completing host, port and secure connection settings
+ * **host** - hostname of the SMTP server (defaults to "localhost", not needed with `service`)
+ * **port** - port of the SMTP server (defaults to 25, not needed with `service`)
+ * **secureConnection** - use SSL (default is `false`, not needed with `service`)
+ * **name** - the name of the client server (defaults to machine name)
+ * **auth** - authentication object as `{user:"...", pass:"..."}`
+ * **ignoreTLS** - ignore server support for STARTTLS (defaults to `false`)
+ * **debug** - output client and server messages to console
+ * **maxConnections** - how many connections to keep in the pool (defaults to 5)
+
+Example:
+
+ var transport = new nodemailer.Transport("SMTP", {
+ service: "Gmail",
+ 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 = new nodemailer.Transport("SMTP",{});
+ ...
+ transport.close(); // close the pool
+
+### Setting up SES
+
+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:
+
+ * **AWSAccessKeyID** - AWS access key (required)
+ * **AWSSecretKey** - AWS secret (required)
+ * **ServiceUrl** - optional API endpoint URL (defaults to *"https://email.us-east-1.amazonaws.com"*)
+
+Example:
+
+ var transport = new nodemailer.Transport("SES", {
+ AWSAccessKeyID: "AWSACCESSKEY",
+ AWSSecretKey: "AWS/Secret/key"
+ });
+
+### Setting up Sendmail
+
+Sendmail transport method streams the compiled message to the stdin of *sendmail*
+command.
+
+Configuration is really easy, the options parameter is optional but you can
+use it to define the path to the *sendmail* command
+
+ var transport = new nodemailer.Transport("Sendmail", "/usr/bin/sendmail");
+
+### Well known services for SMTP
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.
+to enter the hostname or port number, just use the `service` parameter.
Currently cupported services are:
@@ -23,15 +167,117 @@ Currently cupported services are:
* **"Yahoo"** for Yahoo Mail
* **"Zoho"** for Zoho Mail
-Predefined service data covers 'host', 'port' and secure connection settings,
-any other parameters (ie. auth) need to be set separately.
+Predefined service data covers `host`, `port` and secure connection settings,
+any other parameters (ie. `auth`) need to be set separately.
-For example:
+## E-mail message fields
- var transport = new nodemailer.Transport("SMTP", {
- service: "Gmail",
- auth: {
- user: "gmail.user@gmail.com",
- pass: "password"
- }
- });
+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 `sender@server.com` or formatted `Sender Name <sender@server.com>`
+ - **to** - Comma separated list of recipients e-mail addresses that will appear on the `To:` field
+ - **cc** - Comma separated list of recipients e-mail addresses that will appear on the `Cc:` field
+ - **bcc** - Comma separated list 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
+ - **subject** - The subject of the e-mail
+ - **text** - The plaintext version of the message
+ - **html** - The HTML version of the message
+ - **headers** - An object of additional header fields `{"X-Key-Name": "key value"}` (NB! values as passed as is, you should do your own encoding to 7bit if needed)
+ - **attachments** - An array of attachment objects.
+
+All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding.
+Attachments are streamed as binary.
+
+Example:
+
+ var transport = new nodemailer.Transport("Sendmail");
+
+ var mailOptions = {
+ from: "me@tr.ee",
+ to: "me@tr.ee",
+ subject: "Hello world!",
+ text: "Plaintext body",
+ transport: transport
+ }
+
+ nodemailer.sendMail(mailOptions, function(){});
+
+### Attachment fields
+
+Attahcment object cosists of the following properties:
+
+ * **fileName** - filename to be reported as the name of the attached file, use of unicode is allowed (except when using Amazon SES which doesn't like it)
+ * **cid** - optional 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** - optional 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.
+
+### Address Formatting
+
+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 required form
+
+ "Uncode Domain" <info@müriaad-polüteism.info>
+
+### 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 html = "Embedded image: <img src='cid:unique@node.ee' />";
+ var attachments = [{
+ filename: "image.png",
+ filePath: "/path/to/file",
+ cid: "unique@node.ee"
+ }];
+
+## Return callback
+
+Return callback gets two parameters
+
+ * **error** - an error object if the message failed
+ * **responseStatus** - an object with some information about the status on success
+
+## Tests
+
+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.
+
+## Tweaking
+
+Nodemailer in itself is actually more like a wrapper for my other modules
+[mailcomposer](https://github.com/andris9/mailcomposer) for composing the raw message stream
+and [simplesmtp](https://github.com/andris9/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.
+
+## License
+
+**Nodemailer** is licensed under [MIT license](https://github.com/andris9/Nodemailer/blob/master/LICENSE). Basically you can do whatever you want to with it.
View
2  lib/engines/sendmail.js
@@ -29,7 +29,7 @@ SendmailTransport.prototype.sendMail = function(emailMessage, callback) {
var sendmail = spawn(this.path, ["-t"]);
sendmail.on('exit', function (code) {
- callback(code?new Error("Sendmail exited with "+code):null);
+ callback(code?new Error("Sendmail exited with "+code):null, {});
});
emailMessage.pipe(sendmail.stdin);
Please sign in to comment.
Something went wrong with that request. Please try again.