Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 299 lines (203 sloc) 10.975 kb
ca1f7d8 v0.1
andris9 authored
1 Nodemailer
2 ==========
3
3c3cca5 updated readme
Andris Reinman authored
4 **Nodemailer** is an easy to use module to send e-mails with Node.JS (using
d3c4871 Updated readme
Andris Reinman authored
5 SMTP or sendmail) and is unicode friendly - You can use any characters you like ✔
3c3cca5 updated readme
Andris Reinman authored
6
efc9c37 updated readme
Andris Reinman authored
7 This version of Nodemailer is built from scratch and might break some existing scripts, so beware while upgrading.
93f2d1f Updated docs etc
Andris Reinman authored
8
92101e7 updated structure, added stub test
Andris Reinman authored
9 [Autogenerated docs](http://www.node.ee/maildoc/)
10
3c3cca5 updated readme
Andris Reinman authored
11 Use [DocumentUp](http://documentup.com/andris9/nodemailer/) to read this README
12 in a more structured way (with TOC).
13
14 [![Build Status](https://secure.travis-ci.org/andris9/Nodemailer.png)](http://travis-ci.org/andris9/Nodemailer)
15
16 ## Nodemailer supports
17
18 * **Unicode** to use any characters
19 * **HTML content** as well as **plain text** alternative
20 * **Attachments** (including attachment **streaming** for sending larger files)
21 * **Embedded images** in HTML
efc9c37 updated readme
Andris Reinman authored
22 * **SSL/STARTTLS** for secure e-mail delivery
3c3cca5 updated readme
Andris Reinman authored
23 * Different transport methods - **SMTP**, **sendmail** and **Amazon SES**
efc9c37 updated readme
Andris Reinman authored
24 * SMTP **Connection pool** and connection reuse for rapid delivery
25 * **Preconfigured** services for using SMTP with Gmail, Hotmail etc.
3c3cca5 updated readme
Andris Reinman authored
26
27 ## Check out my other mail related modules
28
29 If you want to parse generated or received e-mail instead of sending it, check
30 out [MailParser](https://github.com/andris9/mailparser).
31
32 If you only want to generate the raw e-mail stream, check out
33 [MailComposer](https://github.com/andris9/mailcomposer).
34
35 If you only want to communicate with the SMTP (both as client and the server),
36 check out [simplesmtp](https://github.com/andris9/simplesmtp).
37
38 ## Installation
39
40 Install through NPM
41
42 npm install nodemailer
43
3c54215 Updated readme
Andris Reinman authored
44 Currently v0.3 is not published on NPM so you should install it manually
45
46 Use the easy way
47
48 npm install https://github.com/andris9/Nodemailer/tarball/v0.3
49
50 Or the more complicated way
51
52 cd ~/node_modules
53 git clone git@github.com:andris9/Nodemailer.git nodemailer
54 cd nodemailer
55 git fetch origin v0.3:v0.3
56 git checkout v0.3
57 npm install
58
3c3cca5 updated readme
Andris Reinman authored
59 ## Usage
60
61 Include the module
62
63 var nodemailer = require("nodemailer");
64
65 An e-mail can be sent with `sendMail(mailOptions, callback)` command
66
67 nodemailer.send_mail(mailOptions, callback);
68
69 Where
70
efc9c37 updated readme
Andris Reinman authored
71 * **mailOptions** defines the e-mail (set its subject, body text, receivers etc.), see **E-mail Message Fields** for details
72 * **callback** is the callback function that will be run after the e-mail is sent or the sending failed (see **Return callback** for details)
3c3cca5 updated readme
Andris Reinman authored
73
74 ## Setting up a transport method
75
d3c4871 Updated readme
Andris Reinman authored
76 Before you can send any e-mails you need to set up a transport method. This can
3c3cca5 updated readme
Andris Reinman authored
77 be done with `new nodemailer.Transport(type, options)` where `type` indicates
78 the transport protocol and `options` defines how it used.
79
80 var transport = new nodemailer.Transport("SMTP", {smtp_options});
81
82 The same transport object can and should be reused several times.
83
84 When the transport method is defined, it should be attached to the message
85 object as `transport`
86
87 var transport = new nodemailer.Transport("SMTP", {smtp_options});
88
89 var mailOptions = {
90 from: "sender@tr.ee",
91 to: "receiver@tr.ee",
92 transport: transport
93 };
94
95 ### Possible transport methods
96
d3c4871 Updated readme
Andris Reinman authored
97 Needed `type` parameter can be one of the following:
3c3cca5 updated readme
Andris Reinman authored
98
99 * **SMTP** for using SMTP
100 * **SES** for using Amazon SES
101 * **Sendmail** for utilizing systems *sendmail* command
102
103 ### Setting up SMTP
104
105 SMTP is different from the other transport mechanisms, as in its case a connection
106 pool is created. All the connections try to stay alive as long as possible and
107 are reusable to minimize the protocol overhead delay (for example setting up
108 TLS for authenticating is relatively lengthy process (in CPU terms, not by human
109 terms), you do not want to do it several times.
110
111 Possible SMTP options are the following:
112
efc9c37 updated readme
Andris Reinman authored
113 * **service** - a well known service identifier ("Gmail", "Hotmail" etc., see **Well known Services** for alist of supported services) for auto-completing host, port and secure connection settings
3c3cca5 updated readme
Andris Reinman authored
114 * **host** - hostname of the SMTP server (defaults to "localhost", not needed with `service`)
115 * **port** - port of the SMTP server (defaults to 25, not needed with `service`)
116 * **secureConnection** - use SSL (default is `false`, not needed with `service`)
117 * **name** - the name of the client server (defaults to machine name)
118 * **auth** - authentication object as `{user:"...", pass:"..."}`
119 * **ignoreTLS** - ignore server support for STARTTLS (defaults to `false`)
120 * **debug** - output client and server messages to console
121 * **maxConnections** - how many connections to keep in the pool (defaults to 5)
122
123 Example:
124
125 var transport = new nodemailer.Transport("SMTP", {
126 service: "Gmail",
127 auth: {
128 user: "gmail.user@gmail.com",
129 pass: "userpass"
130 }
131 });
132
133 **NB!** if you want to close the pool (cancel all open connections) you can use
134 `transport.close()`
135
136 var transport = new nodemailer.Transport("SMTP",{});
137 ...
138 transport.close(); // close the pool
139
140 ### Setting up SES
141
142 SES is actually a HTTP based protocol, the compiled e-mail and related info
143 (signatures and such) are sent as a HTTP request to SES servers.
144
145 Possible SES options are the following:
146
147 * **AWSAccessKeyID** - AWS access key (required)
148 * **AWSSecretKey** - AWS secret (required)
149 * **ServiceUrl** - optional API endpoint URL (defaults to *"https://email.us-east-1.amazonaws.com"*)
150
151 Example:
152
153 var transport = new nodemailer.Transport("SES", {
154 AWSAccessKeyID: "AWSACCESSKEY",
155 AWSSecretKey: "AWS/Secret/key"
156 });
157
158 ### Setting up Sendmail
159
160 Sendmail transport method streams the compiled message to the stdin of *sendmail*
161 command.
162
163 Configuration is really easy, the options parameter is optional but you can
164 use it to define the path to the *sendmail* command
165
166 var transport = new nodemailer.Transport("Sendmail", "/usr/bin/sendmail");
167
168 ### Well known services for SMTP
93f2d1f Updated docs etc
Andris Reinman authored
169
170 If you want to use a well known service as the SMTP host, you do not need
3c3cca5 updated readme
Andris Reinman authored
171 to enter the hostname or port number, just use the `service` parameter.
93f2d1f Updated docs etc
Andris Reinman authored
172
173 Currently cupported services are:
174
175 * **"Gmail"** for Google Mail
176 * **"hot.ee"** for www.hot.ee
177 * **"Hotmail"** for Microsoft Live Hotmail
178 * **"iCloud"** for Apple iCloud
179 * **"mail.ee"** for www.mail.ee
180 * **"Postmark"** for Postmark App
181 * **"SendGrid"** for SendGrid
182 * **"SES"** for Amazon SES
183 * **"Yahoo"** for Yahoo Mail
184 * **"Zoho"** for Zoho Mail
185
3c3cca5 updated readme
Andris Reinman authored
186 Predefined service data covers `host`, `port` and secure connection settings,
187 any other parameters (ie. `auth`) need to be set separately.
93f2d1f Updated docs etc
Andris Reinman authored
188
3c3cca5 updated readme
Andris Reinman authored
189 ## E-mail message fields
93f2d1f Updated docs etc
Andris Reinman authored
190
3c3cca5 updated readme
Andris Reinman authored
191 The following are the possible fields of an e-mail message:
192
193 - **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>`
194 - **to** - Comma separated list of recipients e-mail addresses that will appear on the `To:` field
195 - **cc** - Comma separated list of recipients e-mail addresses that will appear on the `Cc:` field
196 - **bcc** - Comma separated list of recipients e-mail addresses that will appear on the `Bcc:` field
197 - **replyTo** - An e-mail address that will appear on the `Reply-To:` field
198 - **subject** - The subject of the e-mail
199 - **text** - The plaintext version of the message
200 - **html** - The HTML version of the message
201 - **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)
202 - **attachments** - An array of attachment objects.
203
204 All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding.
205 Attachments are streamed as binary.
206
207 Example:
208
209 var transport = new nodemailer.Transport("Sendmail");
210
211 var mailOptions = {
212 from: "me@tr.ee",
213 to: "me@tr.ee",
214 subject: "Hello world!",
215 text: "Plaintext body",
216 transport: transport
217 }
218
219 nodemailer.sendMail(mailOptions, function(){});
220
221 ### Attachment fields
222
223 Attahcment object cosists of the following properties:
224
225 * **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)
226 * **cid** - optional content id for using inline images in HTML message source
227 * **contents** - String or a Buffer contents for the attachment
228 * **filePath** - path to a file if you want to stream the file instead of including it (better for larger attachments)
229 * **contentType** - optional content type for the attachment, if not set will be derived from the `fileName` property
230
231 One of `contents` or `filePath` must be specified, if both are missing, the attachment
232 will be discarded. Other fields are optional.
233
234 Attachments can be added as many as you want.
235
236 ### Address Formatting
237
238 All the e-mail addresses can be plain e-mail address
239
240 username@example.com
241
242 or with formatted name (includes unicode support)
243
244 "Ноде Майлер" <username@example.com>
245
246 To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.
247
248 username@example.com, "Ноде Майлер" <username@example.com>, "Name, User" <username@example.com>
249
250 You can even use unicode domain and user names, these are automatically converted
251 to the required form
252
253 "Uncode Domain" <info@müriaad-polüteism.info>
254
255 ### Using Embedded Images
256
257 Attachments can be used as embedded images in the HTML body. To use this
258 feature, you need to set additional property of the attachment - `cid` (unique
259 identifier of the file) which is a reference to the attachment file. The same
260 `cid` value must be used as the image URL in HTML (using `cid:` as the URL
261 protocol, see example below).
262
263 **NB!** the cid value should be as unique as possible!
264
265 var html = "Embedded image: <img src='cid:unique@node.ee' />";
266 var attachments = [{
267 filename: "image.png",
268 filePath: "/path/to/file",
269 cid: "unique@node.ee"
270 }];
271
272 ## Return callback
273
274 Return callback gets two parameters
275
276 * **error** - an error object if the message failed
277 * **responseStatus** - an object with some information about the status on success
278
279 ## Tests
280
281 Run the tests with npm in Nodemailer's directory
282
283 npm test
284
285 There aren't currently many tests for Nodemailer but there are a lot of tests
286 in the modules that are used to generate the raw e-mail body and to use the
287 SMTP client connection.
288
289 ## Tweaking
290
291 Nodemailer in itself is actually more like a wrapper for my other modules
292 [mailcomposer](https://github.com/andris9/mailcomposer) for composing the raw message stream
293 and [simplesmtp](https://github.com/andris9/simplesmtp) for delivering it, by providing an
294 unified API. If there's some problems with particular parts of the
295 message composing/sending process you should look at the appropriate module.
296
297 ## License
298
299 **Nodemailer** is licensed under [MIT license](https://github.com/andris9/Nodemailer/blob/master/LICENSE). Basically you can do whatever you want to with it.
Something went wrong with that request. Please try again.