Skip to content
This repository
Newer
Older
100644 366 lines (263 sloc) 12.947 kb
ca1f7d82 »
2011-01-20 v0.1
1 Nodemailer
2 ==========
3
3c3cca5b »
2012-02-10 updated readme
4 **Nodemailer** is an easy to use module to send e-mails with Node.JS (using
d3c4871b »
2012-02-10 Updated readme
5 SMTP or sendmail) and is unicode friendly - You can use any characters you like ✔
3c3cca5b »
2012-02-10 updated readme
6
efc9c376 »
2012-02-10 updated readme
7 This version of Nodemailer is built from scratch and might break some existing scripts, so beware while upgrading.
93f2d1f9 »
2012-02-10 Updated docs etc
8
92101e77 »
2012-02-10 updated structure, added stub test
9 [Autogenerated docs](http://www.node.ee/maildoc/)
10
3c3cca5b »
2012-02-10 updated readme
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
efc9c376 »
2012-02-10 updated readme
22 * **SSL/STARTTLS** for secure e-mail delivery
3c3cca5b »
2012-02-10 updated readme
23 * Different transport methods - **SMTP**, **sendmail** and **Amazon SES**
efc9c376 »
2012-02-10 updated readme
24 * SMTP **Connection pool** and connection reuse for rapid delivery
25 * **Preconfigured** services for using SMTP with Gmail, Hotmail etc.
3c3cca5b »
2012-02-10 updated readme
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
7b87567a »
2012-02-10 Updated readme
38 ## Example
39
7782176d »
2012-02-10 Updated readme
40 This is a complete example to send an e-mail with plaintext and HTML body
7b87567a »
2012-02-10 Updated readme
41
42 var nodemailer = require("nodemailer");
43
d7688134 »
2012-02-10 Changed new Transport to createTransport
44 var transport = nodemailer.createTransport("SMTP",{
7b87567a »
2012-02-10 Updated readme
45 service: "Gmail",
46 auth: {
47 user: "gmail.user@gmail.com",
48 pass: "userpass"
49 }
50 });
51
52 var mailOptions = {
53 transport: transport, // transport method to use
54 from: "Sender Name <sender@example.com>", // sender address
55 to: "receiver1@example.com, receiver2@example.com", // list of receivers
56 subject: "Hello!", // Subject line
57 text: "Hello world!", // plaintext body
58 html: "<b>Hello world!</b>" // html body
59 }
60
61 nodemailer.sendMail(mailOptions, function(error){
62 if(error){
63 console.log(error);
64 }else{
65 console.log("Message sent!");
66 }
4a35e99c »
2012-02-10 Readme update
67 transport.close(); // lets shut down the connection pool
7b87567a »
2012-02-10 Updated readme
68 });
69
4a35e99c »
2012-02-10 Readme update
70 See also the [examples folder](https://github.com/andris9/Nodemailer/tree/master/examples)
c4cc33b2 »
2012-02-10 Readme update
71 for full featured examples
4a35e99c »
2012-02-10 Readme update
72
3c3cca5b »
2012-02-10 updated readme
73 ## Installation
74
75 Install through NPM
76
77 npm install nodemailer
78
79 ## Usage
80
81 Include the module
82
83 var nodemailer = require("nodemailer");
84
85 An e-mail can be sent with `sendMail(mailOptions, callback)` command
86
538e3d9f »
2012-02-10 updated readme
87 nodemailer.sendMail(mailOptions, callback);
3c3cca5b »
2012-02-10 updated readme
88
89 Where
90
efc9c376 »
2012-02-10 updated readme
91 * **mailOptions** defines the e-mail (set its subject, body text, receivers etc.), see **E-mail Message Fields** for details
92 * **callback** is the callback function that will be run after the e-mail is sent or the sending failed (see **Return callback** for details)
3c3cca5b »
2012-02-10 updated readme
93
94 ## Setting up a transport method
95
d3c4871b »
2012-02-10 Updated readme
96 Before you can send any e-mails you need to set up a transport method. This can
d7688134 »
2012-02-10 Changed new Transport to createTransport
97 be done with `nodemailer.createTransport(type, options)` where `type` indicates
e328b6d1 »
2012-02-10 updated readme
98 the transport protocol and `options` defines how it is used.
3c3cca5b »
2012-02-10 updated readme
99
d7688134 »
2012-02-10 Changed new Transport to createTransport
100 var transport = nodemailer.createTransport("SMTP", {smtp_options});
3c3cca5b »
2012-02-10 updated readme
101
102 The same transport object can and should be reused several times.
103
104 When the transport method is defined, it should be attached to the message
105 object as `transport`
106
d7688134 »
2012-02-10 Changed new Transport to createTransport
107 var transport = nodemailer.createTransport("SMTP", {smtp_options});
3c3cca5b »
2012-02-10 updated readme
108
109 var mailOptions = {
40b7b486 »
2012-02-10 Updated readme
110 transport: transport,
3c3cca5b »
2012-02-10 updated readme
111 from: "sender@tr.ee",
40b7b486 »
2012-02-10 Updated readme
112 to: "receiver@tr.ee"
113 ...
3c3cca5b »
2012-02-10 updated readme
114 };
115
116 ### Possible transport methods
117
40b7b486 »
2012-02-10 Updated readme
118 Required `type` parameter can be one of the following:
3c3cca5b »
2012-02-10 updated readme
119
120 * **SMTP** for using SMTP
121 * **SES** for using Amazon SES
122 * **Sendmail** for utilizing systems *sendmail* command
123
124 ### Setting up SMTP
125
126 SMTP is different from the other transport mechanisms, as in its case a connection
127 pool is created. All the connections try to stay alive as long as possible and
40b7b486 »
2012-02-10 Updated readme
128 are reusable to minimize the protocol overhead delay - for example setting up
3c3cca5b »
2012-02-10 updated readme
129 TLS for authenticating is relatively lengthy process (in CPU terms, not by human
130 terms), you do not want to do it several times.
131
132 Possible SMTP options are the following:
133
65cfdab6 »
2012-02-10 Updated readme
134 * **service** - an optional well known service identifier ("Gmail", "Hotmail" etc., see **Well known Services** for a list of supported services) to auto-configure host, port and secure connection settings
3c3cca5b »
2012-02-10 updated readme
135 * **host** - hostname of the SMTP server (defaults to "localhost", not needed with `service`)
136 * **port** - port of the SMTP server (defaults to 25, not needed with `service`)
137 * **secureConnection** - use SSL (default is `false`, not needed with `service`)
138 * **name** - the name of the client server (defaults to machine name)
139 * **auth** - authentication object as `{user:"...", pass:"..."}`
140 * **ignoreTLS** - ignore server support for STARTTLS (defaults to `false`)
141 * **debug** - output client and server messages to console
142 * **maxConnections** - how many connections to keep in the pool (defaults to 5)
143
144 Example:
145
d7688134 »
2012-02-10 Changed new Transport to createTransport
146 var transport = nodemailer.createTransport("SMTP", {
3c3cca5b »
2012-02-10 updated readme
147 service: "Gmail",
148 auth: {
149 user: "gmail.user@gmail.com",
150 pass: "userpass"
151 }
152 });
153
4a35e99c »
2012-02-10 Readme update
154 or the same without `service` parameter
155
d7688134 »
2012-02-10 Changed new Transport to createTransport
156 var transport = nodemailer.createTransport("SMTP", {
4a35e99c »
2012-02-10 Readme update
157 host: "smtp.gmail.com", // hostname
158 secureConnection: true, // use SSL
159 port: 465, // port for secure SMTP
160 auth: {
161 user: "gmail.user@gmail.com",
162 pass: "userpass"
163 }
164 });
165
3c3cca5b »
2012-02-10 updated readme
166 **NB!** if you want to close the pool (cancel all open connections) you can use
167 `transport.close()`
168
d7688134 »
2012-02-10 Changed new Transport to createTransport
169 var transport = nodemailer.createTransport("SMTP",{});
3c3cca5b »
2012-02-10 updated readme
170 ...
171 transport.close(); // close the pool
172
173 ### Setting up SES
174
175 SES is actually a HTTP based protocol, the compiled e-mail and related info
176 (signatures and such) are sent as a HTTP request to SES servers.
177
178 Possible SES options are the following:
179
180 * **AWSAccessKeyID** - AWS access key (required)
181 * **AWSSecretKey** - AWS secret (required)
26858651 »
2012-02-10 Updated readme
182 * **ServiceUrl** - optional API end point URL (defaults to *"https://email.us-east-1.amazonaws.com"*)
3c3cca5b »
2012-02-10 updated readme
183
184 Example:
185
d7688134 »
2012-02-10 Changed new Transport to createTransport
186 var transport = nodemailer.createTransport("SES", {
3c3cca5b »
2012-02-10 updated readme
187 AWSAccessKeyID: "AWSACCESSKEY",
188 AWSSecretKey: "AWS/Secret/key"
189 });
190
191 ### Setting up Sendmail
192
26858651 »
2012-02-10 Updated readme
193 Sendmail transport method streams the compiled message to the *stdin* of *sendmail*
3c3cca5b »
2012-02-10 updated readme
194 command.
195
196 Configuration is really easy, the options parameter is optional but you can
197 use it to define the path to the *sendmail* command
198
d7688134 »
2012-02-10 Changed new Transport to createTransport
199 var transport = nodemailer.createTransport("Sendmail", "/usr/bin/sendmail");
3c3cca5b »
2012-02-10 updated readme
200
201 ### Well known services for SMTP
93f2d1f9 »
2012-02-10 Updated docs etc
202
203 If you want to use a well known service as the SMTP host, you do not need
3c3cca5b »
2012-02-10 updated readme
204 to enter the hostname or port number, just use the `service` parameter.
93f2d1f9 »
2012-02-10 Updated docs etc
205
206 Currently cupported services are:
207
208 * **"Gmail"** for Google Mail
209 * **"hot.ee"** for www.hot.ee
210 * **"Hotmail"** for Microsoft Live Hotmail
211 * **"iCloud"** for Apple iCloud
212 * **"mail.ee"** for www.mail.ee
213 * **"Postmark"** for Postmark App
214 * **"SendGrid"** for SendGrid
215 * **"SES"** for Amazon SES
216 * **"Yahoo"** for Yahoo Mail
217 * **"Zoho"** for Zoho Mail
218
3c3cca5b »
2012-02-10 updated readme
219 Predefined service data covers `host`, `port` and secure connection settings,
220 any other parameters (ie. `auth`) need to be set separately.
93f2d1f9 »
2012-02-10 Updated docs etc
221
3c3cca5b »
2012-02-10 updated readme
222 ## E-mail message fields
93f2d1f9 »
2012-02-10 Updated docs etc
223
3c3cca5b »
2012-02-10 updated readme
224 The following are the possible fields of an e-mail message:
225
226 - **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>`
227 - **to** - Comma separated list of recipients e-mail addresses that will appear on the `To:` field
228 - **cc** - Comma separated list of recipients e-mail addresses that will appear on the `Cc:` field
229 - **bcc** - Comma separated list of recipients e-mail addresses that will appear on the `Bcc:` field
230 - **replyTo** - An e-mail address that will appear on the `Reply-To:` field
231 - **subject** - The subject of the e-mail
232 - **text** - The plaintext version of the message
233 - **html** - The HTML version of the message
234 - **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)
235 - **attachments** - An array of attachment objects.
236
237 All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding.
238 Attachments are streamed as binary.
239
240 Example:
241
d7688134 »
2012-02-10 Changed new Transport to createTransport
242 var transport = nodemailer.createTransport("Sendmail");
3c3cca5b »
2012-02-10 updated readme
243
244 var mailOptions = {
26858651 »
2012-02-10 Updated readme
245 transport: transport,
3c3cca5b »
2012-02-10 updated readme
246 from: "me@tr.ee",
247 to: "me@tr.ee",
248 subject: "Hello world!",
26858651 »
2012-02-10 Updated readme
249 text: "Plaintext body"
3c3cca5b »
2012-02-10 updated readme
250 }
251
252 nodemailer.sendMail(mailOptions, function(){});
253
254 ### Attachment fields
255
26858651 »
2012-02-10 Updated readme
256 Attahcment object consists of the following properties:
3c3cca5b »
2012-02-10 updated readme
257
258 * **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)
259 * **cid** - optional content id for using inline images in HTML message source
260 * **contents** - String or a Buffer contents for the attachment
261 * **filePath** - path to a file if you want to stream the file instead of including it (better for larger attachments)
262 * **contentType** - optional content type for the attachment, if not set will be derived from the `fileName` property
263
264 One of `contents` or `filePath` must be specified, if both are missing, the attachment
265 will be discarded. Other fields are optional.
266
267 Attachments can be added as many as you want.
268
4a35e99c »
2012-02-10 Readme update
269 var mailOptions = {
270 ...
271 attachments: [
272 {
273 fileName: "text1.txt",
274 contents: "hello world!
275 },
276 {
277 fileName: "text2.txt",
278 contents: new Buffer("hello world!,"utf-8")
279 },
280 {
281 fileName: "text3.txt",
282 filePath: "/path/to/file.txt" // stream this file
283 },
284 {
285 fileName: "text",
286 contents: "hello world!,
287 contentType: "text/plain"
288 }
289 ]
290 }
291
3c3cca5b »
2012-02-10 updated readme
292 ### Address Formatting
293
294 All the e-mail addresses can be plain e-mail address
295
296 username@example.com
297
298 or with formatted name (includes unicode support)
299
300 "Ноде Майлер" <username@example.com>
301
302 To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.
303
304 username@example.com, "Ноде Майлер" <username@example.com>, "Name, User" <username@example.com>
305
306 You can even use unicode domain and user names, these are automatically converted
4a35e99c »
2012-02-10 Readme update
307 to the supported form
3c3cca5b »
2012-02-10 updated readme
308
309 "Uncode Domain" <info@müriaad-polüteism.info>
310
311 ### Using Embedded Images
312
313 Attachments can be used as embedded images in the HTML body. To use this
314 feature, you need to set additional property of the attachment - `cid` (unique
315 identifier of the file) which is a reference to the attachment file. The same
316 `cid` value must be used as the image URL in HTML (using `cid:` as the URL
317 protocol, see example below).
318
319 **NB!** the cid value should be as unique as possible!
320
4a35e99c »
2012-02-10 Readme update
321 var mailOptions = {
322 ...
323 html: "Embedded image: <img src='cid:unique@node.ee' />",
324 attachments: [{
325 filename: "image.png",
326 filePath: "/path/to/file",
327 cid: "unique@node.ee" //same cid value as in the html img src
328 }]
329 }
3c3cca5b »
2012-02-10 updated readme
330
331 ## Return callback
332
333 Return callback gets two parameters
334
335 * **error** - an error object if the message failed
336 * **responseStatus** - an object with some information about the status on success
337
c4cc33b2 »
2012-02-10 Readme update
338 Example:
339
4a35e99c »
2012-02-10 Readme update
340 nodemailer.sendMail(mailOptions, function(error, responseStatus){
341 if(!error){
342 console.log(responseStatus.message); // response from the server
343 }
344 });
345
3c3cca5b »
2012-02-10 updated readme
346 ## Tests
347
348 Run the tests with npm in Nodemailer's directory
349
350 npm test
351
352 There aren't currently many tests for Nodemailer but there are a lot of tests
353 in the modules that are used to generate the raw e-mail body and to use the
354 SMTP client connection.
355
356 ## Tweaking
357
358 Nodemailer in itself is actually more like a wrapper for my other modules
359 [mailcomposer](https://github.com/andris9/mailcomposer) for composing the raw message stream
360 and [simplesmtp](https://github.com/andris9/simplesmtp) for delivering it, by providing an
361 unified API. If there's some problems with particular parts of the
362 message composing/sending process you should look at the appropriate module.
363
364 ## License
365
366 **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.