Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 332 lines (230 sloc) 11.953 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
7b87567 Updated readme
Andris Reinman authored
38 ## Example
39
7782176 Updated readme
Andris Reinman authored
40 This is a complete example to send an e-mail with plaintext and HTML body
7b87567 Updated readme
Andris Reinman authored
41
42 var nodemailer = require("nodemailer");
43
44 var transport = new nodemailer.Transport("SMTP",{
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 }
67 transport.close(); // let's shut down the connection pool
68 });
69
3c3cca5 updated readme
Andris Reinman authored
70 ## Installation
71
72 Install through NPM
73
74 npm install nodemailer
75
3c54215 Updated readme
Andris Reinman authored
76 Currently v0.3 is not published on NPM so you should install it manually
77
78 Use the easy way
79
80 npm install https://github.com/andris9/Nodemailer/tarball/v0.3
81
82 Or the more complicated way
83
84 cd ~/node_modules
85 git clone git@github.com:andris9/Nodemailer.git nodemailer
86 cd nodemailer
87 git fetch origin v0.3:v0.3
88 git checkout v0.3
89 npm install
90
3c3cca5 updated readme
Andris Reinman authored
91 ## Usage
92
93 Include the module
94
95 var nodemailer = require("nodemailer");
96
97 An e-mail can be sent with `sendMail(mailOptions, callback)` command
98
99 nodemailer.send_mail(mailOptions, callback);
100
101 Where
102
efc9c37 updated readme
Andris Reinman authored
103 * **mailOptions** defines the e-mail (set its subject, body text, receivers etc.), see **E-mail Message Fields** for details
104 * **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
105
106 ## Setting up a transport method
107
d3c4871 Updated readme
Andris Reinman authored
108 Before you can send any e-mails you need to set up a transport method. This can
3c3cca5 updated readme
Andris Reinman authored
109 be done with `new nodemailer.Transport(type, options)` where `type` indicates
110 the transport protocol and `options` defines how it used.
111
112 var transport = new nodemailer.Transport("SMTP", {smtp_options});
113
114 The same transport object can and should be reused several times.
115
116 When the transport method is defined, it should be attached to the message
117 object as `transport`
118
119 var transport = new nodemailer.Transport("SMTP", {smtp_options});
120
121 var mailOptions = {
40b7b48 Updated readme
Andris Reinman authored
122 transport: transport,
3c3cca5 updated readme
Andris Reinman authored
123 from: "sender@tr.ee",
40b7b48 Updated readme
Andris Reinman authored
124 to: "receiver@tr.ee"
125 ...
3c3cca5 updated readme
Andris Reinman authored
126 };
127
128 ### Possible transport methods
129
40b7b48 Updated readme
Andris Reinman authored
130 Required `type` parameter can be one of the following:
3c3cca5 updated readme
Andris Reinman authored
131
132 * **SMTP** for using SMTP
133 * **SES** for using Amazon SES
134 * **Sendmail** for utilizing systems *sendmail* command
135
136 ### Setting up SMTP
137
138 SMTP is different from the other transport mechanisms, as in its case a connection
139 pool is created. All the connections try to stay alive as long as possible and
40b7b48 Updated readme
Andris Reinman authored
140 are reusable to minimize the protocol overhead delay - for example setting up
3c3cca5 updated readme
Andris Reinman authored
141 TLS for authenticating is relatively lengthy process (in CPU terms, not by human
142 terms), you do not want to do it several times.
143
144 Possible SMTP options are the following:
145
65cfdab Updated readme
Andris Reinman authored
146 * **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
3c3cca5 updated readme
Andris Reinman authored
147 * **host** - hostname of the SMTP server (defaults to "localhost", not needed with `service`)
148 * **port** - port of the SMTP server (defaults to 25, not needed with `service`)
149 * **secureConnection** - use SSL (default is `false`, not needed with `service`)
150 * **name** - the name of the client server (defaults to machine name)
151 * **auth** - authentication object as `{user:"...", pass:"..."}`
152 * **ignoreTLS** - ignore server support for STARTTLS (defaults to `false`)
153 * **debug** - output client and server messages to console
154 * **maxConnections** - how many connections to keep in the pool (defaults to 5)
155
156 Example:
157
158 var transport = new nodemailer.Transport("SMTP", {
159 service: "Gmail",
160 auth: {
161 user: "gmail.user@gmail.com",
162 pass: "userpass"
163 }
164 });
165
166 **NB!** if you want to close the pool (cancel all open connections) you can use
167 `transport.close()`
168
169 var transport = new nodemailer.Transport("SMTP",{});
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)
2685865 Updated readme
Andris Reinman authored
182 * **ServiceUrl** - optional API end point URL (defaults to *"https://email.us-east-1.amazonaws.com"*)
3c3cca5 updated readme
Andris Reinman authored
183
184 Example:
185
186 var transport = new nodemailer.Transport("SES", {
187 AWSAccessKeyID: "AWSACCESSKEY",
188 AWSSecretKey: "AWS/Secret/key"
189 });
190
191 ### Setting up Sendmail
192
2685865 Updated readme
Andris Reinman authored
193 Sendmail transport method streams the compiled message to the *stdin* of *sendmail*
3c3cca5 updated readme
Andris Reinman authored
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
199 var transport = new nodemailer.Transport("Sendmail", "/usr/bin/sendmail");
200
201 ### Well known services for SMTP
93f2d1f Updated docs etc
Andris Reinman authored
202
203 If you want to use a well known service as the SMTP host, you do not need
3c3cca5 updated readme
Andris Reinman authored
204 to enter the hostname or port number, just use the `service` parameter.
93f2d1f Updated docs etc
Andris Reinman authored
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
3c3cca5 updated readme
Andris Reinman authored
219 Predefined service data covers `host`, `port` and secure connection settings,
220 any other parameters (ie. `auth`) need to be set separately.
93f2d1f Updated docs etc
Andris Reinman authored
221
3c3cca5 updated readme
Andris Reinman authored
222 ## E-mail message fields
93f2d1f Updated docs etc
Andris Reinman authored
223
3c3cca5 updated readme
Andris Reinman authored
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
242 var transport = new nodemailer.Transport("Sendmail");
243
244 var mailOptions = {
2685865 Updated readme
Andris Reinman authored
245 transport: transport,
3c3cca5 updated readme
Andris Reinman authored
246 from: "me@tr.ee",
247 to: "me@tr.ee",
248 subject: "Hello world!",
2685865 Updated readme
Andris Reinman authored
249 text: "Plaintext body"
3c3cca5 updated readme
Andris Reinman authored
250 }
251
252 nodemailer.sendMail(mailOptions, function(){});
253
254 ### Attachment fields
255
2685865 Updated readme
Andris Reinman authored
256 Attahcment object consists of the following properties:
3c3cca5 updated readme
Andris Reinman authored
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
269 ### Address Formatting
270
271 All the e-mail addresses can be plain e-mail address
272
273 username@example.com
274
275 or with formatted name (includes unicode support)
276
277 "Ноде Майлер" <username@example.com>
278
279 To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.
280
281 username@example.com, "Ноде Майлер" <username@example.com>, "Name, User" <username@example.com>
282
283 You can even use unicode domain and user names, these are automatically converted
284 to the required form
285
286 "Uncode Domain" <info@müriaad-polüteism.info>
287
288 ### Using Embedded Images
289
290 Attachments can be used as embedded images in the HTML body. To use this
291 feature, you need to set additional property of the attachment - `cid` (unique
292 identifier of the file) which is a reference to the attachment file. The same
293 `cid` value must be used as the image URL in HTML (using `cid:` as the URL
294 protocol, see example below).
295
296 **NB!** the cid value should be as unique as possible!
297
298 var html = "Embedded image: <img src='cid:unique@node.ee' />";
299 var attachments = [{
300 filename: "image.png",
301 filePath: "/path/to/file",
302 cid: "unique@node.ee"
303 }];
304
305 ## Return callback
306
307 Return callback gets two parameters
308
309 * **error** - an error object if the message failed
310 * **responseStatus** - an object with some information about the status on success
311
312 ## Tests
313
314 Run the tests with npm in Nodemailer's directory
315
316 npm test
317
318 There aren't currently many tests for Nodemailer but there are a lot of tests
319 in the modules that are used to generate the raw e-mail body and to use the
320 SMTP client connection.
321
322 ## Tweaking
323
324 Nodemailer in itself is actually more like a wrapper for my other modules
325 [mailcomposer](https://github.com/andris9/mailcomposer) for composing the raw message stream
326 and [simplesmtp](https://github.com/andris9/simplesmtp) for delivering it, by providing an
327 unified API. If there's some problems with particular parts of the
328 message composing/sending process you should look at the appropriate module.
329
330 ## License
331
332 **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.