Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 540 lines (398 sloc) 20.699 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
21c545d @andris9 Update README.md
authored
5 SMTP or sendmail or Amazon SES) and is unicode friendly - You can use any characters you like ✔
3c3cca5 updated readme
Andris Reinman authored
6
06eb6cb some minor housekeeping
Andris Reinman authored
7 Nodemailer is Windows friendly, you can install it with *npm* on Windows just like any other module, there are no compiled dependencies. Use it from Azure or from your Windows box hassle free.
8
cc5b5ae updated readme
Andris Reinman authored
9 Version v0.3 of Nodemailer is built from scratch and might break some existing scripts, so beware while upgrading. Nodemailer should be backwards compatible - if your script worked before, then it should work now, even if Nodemailer documentation differs from your code (method names, properties etc.).
93f2d1f Updated docs etc
Andris Reinman authored
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.
21c545d @andris9 Update README.md
authored
26 * Use objects as header values for **SendGrid** SMTP API
a9acb36 Updated Readme
Andris Reinman authored
27 * **XOAUTH** authentication support and token generation (3-legged OAuth) - useful with Gmail
52cf687 Added DKIM signing support
Andris Reinman authored
28 * **DKIM** signing
3c3cca5 updated readme
Andris Reinman authored
29
ed599e5 @andris9 Update README.md
authored
30 ## Support Nodemailer development
31
32 [![Donate to author](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=DB26KWR2BQX5W)
33
3c3cca5 updated readme
Andris Reinman authored
34 ## Check out my other mail related modules
35
36 If you want to parse generated or received e-mail instead of sending it, check
37 out [MailParser](https://github.com/andris9/mailparser).
38
39 If you only want to generate the raw e-mail stream, check out
40 [MailComposer](https://github.com/andris9/mailcomposer).
41
42 If you only want to communicate with the SMTP (both as client and the server),
43 check out [simplesmtp](https://github.com/andris9/simplesmtp).
44
7b87567 Updated readme
Andris Reinman authored
45 ## Example
46
7782176 Updated readme
Andris Reinman authored
47 This is a complete example to send an e-mail with plaintext and HTML body
7b87567 Updated readme
Andris Reinman authored
48
49 var nodemailer = require("nodemailer");
50
0d22389 @andris9 Update README.md
authored
51 // create reusable transport method (opens pool of SMTP connections)
07db51a updated sending api, backwards compatible
Andris Reinman authored
52 var smtpTransport = nodemailer.createTransport("SMTP",{
7b87567 Updated readme
Andris Reinman authored
53 service: "Gmail",
54 auth: {
55 user: "gmail.user@gmail.com",
56 pass: "userpass"
57 }
58 });
59
1f6a511 @andris9 Update README.md
authored
60 // setup e-mail data with unicode symbols
7b87567 Updated readme
Andris Reinman authored
61 var mailOptions = {
0d22389 @andris9 Update README.md
authored
62 from: "Sender Name ✔ <sender@example.com>", // sender address
7b87567 Updated readme
Andris Reinman authored
63 to: "receiver1@example.com, receiver2@example.com", // list of receivers
0d22389 @andris9 Update README.md
authored
64 subject: "Hello ✔", // Subject line
65 text: "Hello world ✔", // plaintext body
66 html: "<b>Hello world ✔</b>" // html body
7b87567 Updated readme
Andris Reinman authored
67 }
68
07db51a updated sending api, backwards compatible
Andris Reinman authored
69 // send mail with defined transport object
0d22389 @andris9 Update README.md
authored
70 smtpTransport.sendMail(mailOptions, function(error, response){
7b87567 Updated readme
Andris Reinman authored
71 if(error){
72 console.log(error);
73 }else{
0d22389 @andris9 Update README.md
authored
74 console.log("Message sent: " + response.message);
7b87567 Updated readme
Andris Reinman authored
75 }
a8d5f64 @andris9 Update README.md
authored
76 smtpTransport.close(); // shut down the connection pool, no more messages
7b87567 Updated readme
Andris Reinman authored
77 });
78
4a35e99 Readme update
Andris Reinman authored
79 See also the [examples folder](https://github.com/andris9/Nodemailer/tree/master/examples)
c4cc33b Readme update
Andris Reinman authored
80 for full featured examples
4a35e99 Readme update
Andris Reinman authored
81
3c3cca5 updated readme
Andris Reinman authored
82 ## Installation
83
84 Install through NPM
85
86 npm install nodemailer
87
88 ## Usage
89
90 Include the module
91
92 var nodemailer = require("nodemailer");
93
07db51a updated sending api, backwards compatible
Andris Reinman authored
94 An e-mail can be sent with `sendMail(mailOptions[, callback])` command
3c3cca5 updated readme
Andris Reinman authored
95
07db51a updated sending api, backwards compatible
Andris Reinman authored
96 transport.sendMail(mailOptions, callback);
3c3cca5 updated readme
Andris Reinman authored
97
98 Where
99
eb7d4fd @andris9 Update README.md
authored
100 * `transport` is a transport method defined with `nodemailer.createTransport`
efc9c37 updated readme
Andris Reinman authored
101 * **mailOptions** defines the e-mail (set its subject, body text, receivers etc.), see **E-mail Message Fields** for details
102 * **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
103
104 ## Setting up a transport method
105
d3c4871 Updated readme
Andris Reinman authored
106 Before you can send any e-mails you need to set up a transport method. This can
d768813 Changed new Transport to createTransport
Andris Reinman authored
107 be done with `nodemailer.createTransport(type, options)` where `type` indicates
e328b6d updated readme
Andris Reinman authored
108 the transport protocol and `options` defines how it is used.
3c3cca5 updated readme
Andris Reinman authored
109
d768813 Changed new Transport to createTransport
Andris Reinman authored
110 var transport = nodemailer.createTransport("SMTP", {smtp_options});
3c3cca5 updated readme
Andris Reinman authored
111
112 The same transport object can and should be reused several times.
113
eb7d4fd @andris9 Update README.md
authored
114 When the transport method is defined, it can be used to send e-mail with `sendMail`
3c3cca5 updated readme
Andris Reinman authored
115
d768813 Changed new Transport to createTransport
Andris Reinman authored
116 var transport = nodemailer.createTransport("SMTP", {smtp_options});
3c3cca5 updated readme
Andris Reinman authored
117
eb7d4fd @andris9 Update README.md
authored
118 transport.sendMail({
3c3cca5 updated readme
Andris Reinman authored
119 from: "sender@tr.ee",
40b7b48 Updated readme
Andris Reinman authored
120 to: "receiver@tr.ee"
121 ...
eb7d4fd @andris9 Update README.md
authored
122 });
3c3cca5 updated readme
Andris Reinman authored
123
124 ### Possible transport methods
125
40b7b48 Updated readme
Andris Reinman authored
126 Required `type` parameter can be one of the following:
3c3cca5 updated readme
Andris Reinman authored
127
128 * **SMTP** for using SMTP
129 * **SES** for using Amazon SES
130 * **Sendmail** for utilizing systems *sendmail* command
131
132 ### Setting up SMTP
133
134 SMTP is different from the other transport mechanisms, as in its case a connection
135 pool is created. All the connections try to stay alive as long as possible and
40b7b48 Updated readme
Andris Reinman authored
136 are reusable to minimize the protocol overhead delay - for example setting up
3c3cca5 updated readme
Andris Reinman authored
137 TLS for authenticating is relatively lengthy process (in CPU terms, not by human
138 terms), you do not want to do it several times.
139
140 Possible SMTP options are the following:
141
65cfdab Updated readme
Andris Reinman authored
142 * **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
143 * **host** - hostname of the SMTP server (defaults to "localhost", not needed with `service`)
144 * **port** - port of the SMTP server (defaults to 25, not needed with `service`)
9f30440 Updated README about secureConnection option
Andris Reinman authored
145 * **secureConnection** - use SSL (default is `false`, not needed with `service`). If you're using port 587 then keep `secureConnection` false, since the connection is started in insecure plain text mode and only later upgraded with STARTTLS
3c3cca5 updated readme
Andris Reinman authored
146 * **name** - the name of the client server (defaults to machine name)
c075b9b Added XOAuthToken auth option for Gmail XOAUTH support
Andris Reinman authored
147 * **auth** - authentication object as `{user:"...", pass:"..."}` or `{XOAuthToken: "base64data"}`
3c3cca5 updated readme
Andris Reinman authored
148 * **ignoreTLS** - ignore server support for STARTTLS (defaults to `false`)
149 * **debug** - output client and server messages to console
150 * **maxConnections** - how many connections to keep in the pool (defaults to 5)
151
152 Example:
153
d768813 Changed new Transport to createTransport
Andris Reinman authored
154 var transport = nodemailer.createTransport("SMTP", {
3c3cca5 updated readme
Andris Reinman authored
155 service: "Gmail",
156 auth: {
157 user: "gmail.user@gmail.com",
158 pass: "userpass"
159 }
160 });
161
4a35e99 Readme update
Andris Reinman authored
162 or the same without `service` parameter
163
d768813 Changed new Transport to createTransport
Andris Reinman authored
164 var transport = nodemailer.createTransport("SMTP", {
4a35e99 Readme update
Andris Reinman authored
165 host: "smtp.gmail.com", // hostname
166 secureConnection: true, // use SSL
167 port: 465, // port for secure SMTP
168 auth: {
169 user: "gmail.user@gmail.com",
170 pass: "userpass"
171 }
172 });
173
3c3cca5 updated readme
Andris Reinman authored
174 **NB!** if you want to close the pool (cancel all open connections) you can use
175 `transport.close()`
176
d768813 Changed new Transport to createTransport
Andris Reinman authored
177 var transport = nodemailer.createTransport("SMTP",{});
3c3cca5 updated readme
Andris Reinman authored
178 ...
179 transport.close(); // close the pool
180
26794a7 Fixed XOAUTH generator defaults bug, updated README
Andris Reinman authored
181
182 #### SMTP XOAUTH and token generation
183
184 **nodemailer** supports XOAUTH authentication for SMTP. To use this, include
185 `XOAuthToken` option in `auth` instead of the regular `user` and `pass`.
186
9fdff73 updated README
Andris Reinman authored
187 var transportOptions = {
26794a7 Fixed XOAUTH generator defaults bug, updated README
Andris Reinman authored
188 ...,
189 auth: {
190 XOAuthToken: "R0VUIGh0dHBzOi8vbWFpbC5nb29...."
191 }
192 }
193
194 **nodemailer** includes also built in XOAUTH token generator which can be used
195 with `nodemailer.createXOAuthGenerator()`. The function is preconfigured for
196 Gmail, so in this case only mandatory options are `user`, `token` and `tokenSecret`.
197
198 var XOAuthTokenGenerator = nodemailer.createXOAuthGenerator({
199 user: "test.nodemailer@gmail.com",
200 // requestUrl: "https://oauth.access.point",
201 // consumerKey: "anonymous",
202 // consumerSecret: "anonymous",
203 token: "1/O_HgoO4h2uOUfpus0V--7mygICXrQQ0ZajB3ZH52KqM",
204 tokenSecret: "_mUBkIwNPnfQBUIWrJrpXJ0c"
205 });
206
207 One of `user` or `requestUrl` is mandatory. `consumerKey` and `consumerSecret` both
208 default to `"anonymous"`.
209
9fdff73 updated README
Andris Reinman authored
210 var transportOptions = {
211 service: "Gmail",
26794a7 Fixed XOAUTH generator defaults bug, updated README
Andris Reinman authored
212 auth: {
213 XOAuthToken: nodemailer.createXOAuthGenerator({
214 user: "test.nodemailer@gmail.com",
215 token: "1/O_HgoO4h2uOUfpus0V--7mygICXrQQ0ZajB3ZH52KqM",
216 tokenSecret: "_mUBkIwNPnfQBUIWrJrpXJ0c"
217 });
218 }
219 }
220
3c3cca5 updated readme
Andris Reinman authored
221 ### Setting up SES
222
223 SES is actually a HTTP based protocol, the compiled e-mail and related info
224 (signatures and such) are sent as a HTTP request to SES servers.
225
226 Possible SES options are the following:
227
228 * **AWSAccessKeyID** - AWS access key (required)
229 * **AWSSecretKey** - AWS secret (required)
2685865 Updated readme
Andris Reinman authored
230 * **ServiceUrl** - optional API end point URL (defaults to *"https://email.us-east-1.amazonaws.com"*)
3c3cca5 updated readme
Andris Reinman authored
231
232 Example:
233
d768813 Changed new Transport to createTransport
Andris Reinman authored
234 var transport = nodemailer.createTransport("SES", {
3c3cca5 updated readme
Andris Reinman authored
235 AWSAccessKeyID: "AWSACCESSKEY",
236 AWSSecretKey: "AWS/Secret/key"
237 });
238
239 ### Setting up Sendmail
240
2685865 Updated readme
Andris Reinman authored
241 Sendmail transport method streams the compiled message to the *stdin* of *sendmail*
3c3cca5 updated readme
Andris Reinman authored
242 command.
243
244 Configuration is really easy, the options parameter is optional but you can
245 use it to define the path to the *sendmail* command
246
d768813 Changed new Transport to createTransport
Andris Reinman authored
247 var transport = nodemailer.createTransport("Sendmail", "/usr/bin/sendmail");
3c3cca5 updated readme
Andris Reinman authored
248
52cf687 Added DKIM signing support
Andris Reinman authored
249 ### DKIM Signing
250
251 **Nodemailer** supports DKIM signing with very simple setup. Use this with caution
252 though since the generated message needs to be buffered entirely before it can be
36d191c Updated README
Andris Reinman authored
253 signed. Not a big deal with small messages but might consume a lot of RAM when
254 using larger attachments.
52cf687 Added DKIM signing support
Andris Reinman authored
255
256 Set up the DKIM signing with `useDKIM` method for a transport object:
257
258 transport.useDKIM(dkimOptions)
259
260 Where `dkimOptions` includes necessary options for signing
261
262 * **domainName** - the domainname that is being used for signing
263 * **keySelector** - key selector. If you have set up a TXT record with DKIM public key at *zzz._domainkey.example.com* then `zzz` is the selector
264 * **privateKey** - DKIM private key that is used for signing as a string
265 * **headerFieldNames** - optional colon separated list of header fields to sign, by default all fields suggested by RFC4871 #5.5 are used
266
267 All messages transmitted through this transport objects are from now on DKIM signed.
268
1f93264 Updated README
Andris Reinman authored
269 Currently if several header fields with the same name exists, only the last one (the one in the bottom) is signed.
52cf687 Added DKIM signing support
Andris Reinman authored
270
271 Example:
272
273 var transport = nodemailer.createTransport("Sendmail");
274
275 transport.useDKIM({
276 domainName: "node.ee",
277 keySelector: "dkim",
278 privateKey: fs.readFileSync("private_key.pem")
279 });
280
281 transport.sendMail(mailOptions);
282
283 See examples/example_dkim.js for a complete example.
284
1f93264 Updated README
Andris Reinman authored
285 **NB!** Be careful when using services like Gmail, SES etc. through SMTP
286 (SES API is handled by Nodemailer automatically) - these tend to modify some
287 headers like Message-Id or Date which invalidates the signature. In this case use
288 `headerFieldNames` property to define only fields that won't be changed and leave
289 out `Date` or any other unsupported field.
290
3c3cca5 updated readme
Andris Reinman authored
291 ### Well known services for SMTP
93f2d1f Updated docs etc
Andris Reinman authored
292
293 If you want to use a well known service as the SMTP host, you do not need
5fef793 readme update
Andris Reinman authored
294 to enter the hostname or port number, just use the `service` parameter (**NB!** case sensitive).
93f2d1f Updated docs etc
Andris Reinman authored
295
296 Currently cupported services are:
297
298 * **"Gmail"** for Google Mail
299 * **"hot.ee"** for www.hot.ee
300 * **"Hotmail"** for Microsoft Live Hotmail
301 * **"iCloud"** for Apple iCloud
302 * **"mail.ee"** for www.mail.ee
303 * **"Postmark"** for Postmark App
304 * **"SendGrid"** for SendGrid
305 * **"SES"** for Amazon SES
306 * **"Yahoo"** for Yahoo Mail
307 * **"Zoho"** for Zoho Mail
308
3c3cca5 updated readme
Andris Reinman authored
309 Predefined service data covers `host`, `port` and secure connection settings,
310 any other parameters (ie. `auth`) need to be set separately.
93f2d1f Updated docs etc
Andris Reinman authored
311
3c3cca5 updated readme
Andris Reinman authored
312 ## E-mail message fields
93f2d1f Updated docs etc
Andris Reinman authored
313
3c3cca5 updated readme
Andris Reinman authored
314 The following are the possible fields of an e-mail message:
315
316 - **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>`
317 - **to** - Comma separated list of recipients e-mail addresses that will appear on the `To:` field
318 - **cc** - Comma separated list of recipients e-mail addresses that will appear on the `Cc:` field
319 - **bcc** - Comma separated list of recipients e-mail addresses that will appear on the `Bcc:` field
320 - **replyTo** - An e-mail address that will appear on the `Reply-To:` field
321 - **subject** - The subject of the e-mail
322 - **text** - The plaintext version of the message
323 - **html** - The HTML version of the message
aae3749 regenerated docs
Andris Reinman authored
324 - **generateTextFromHTML** - if set to true uses HTML to generate plain text body part from the HTML if the text is not defined
3c3cca5 updated readme
Andris Reinman authored
325 - **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)
326 - **attachments** - An array of attachment objects.
9285f5c updated mailcomposer dependency to support envelope property
Andris Reinman authored
327 - **envelope** - optional SMTP envelope, if auto generated envelope is not suitable
2b9a3c9 Added messageId option
Andris Reinman authored
328 - **messageId** - optional Message-Id value, random value will be generated if not set
3c3cca5 updated readme
Andris Reinman authored
329
330 All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding.
331 Attachments are streamed as binary.
332
333 Example:
334
d768813 Changed new Transport to createTransport
Andris Reinman authored
335 var transport = nodemailer.createTransport("Sendmail");
3c3cca5 updated readme
Andris Reinman authored
336
337 var mailOptions = {
338 from: "me@tr.ee",
339 to: "me@tr.ee",
340 subject: "Hello world!",
2685865 Updated readme
Andris Reinman authored
341 text: "Plaintext body"
3c3cca5 updated readme
Andris Reinman authored
342 }
343
07db51a updated sending api, backwards compatible
Andris Reinman authored
344 transport.sendMail(mailOptions);
3c3cca5 updated readme
Andris Reinman authored
345
ecfeb0e updated README for SendGrid support
Andris Reinman authored
346 ### SendGrid support
347
348 Nodemailer supports SendGrid [SMTP API](http://docs.sendgrid.com/documentation/api/smtp-api/) out of the box - you can
349 use objects as header values and these are automatically JSONized (and mime encoded if needed).
350
351 var mailOptions = {
352 ...,
353 headers: {
354 'X-SMTPAPI': {
355 category : "newuser",
356 sub:{
357 "%name%": ["Žiguli Õllepruul"]
358 }
359 }
3c9462a updated README for SendGrid support
Andris Reinman authored
360 },
361 subject: "Hello, %name%"
ecfeb0e updated README for SendGrid support
Andris Reinman authored
362 }
363
3c9462a updated README for SendGrid support
Andris Reinman authored
364 This also applies to any other service that expects a JSON string as a header value for specified key.
365
d1f45e1 @andris9 Update README.md
authored
366 ### Generate Text from HTML
367
368 If `generateTextFromHTML` option is set to true, then HTML contents of the mail is automatically converted
369 to plaintext format when plaintext content is empty or missing.
370
371 For example
372
373 mailOptions = {
374 ...,
375 generateTextFromHTML: true,
376 html: '<h1>Hello world</h1><p><b>How</b> are you?',
377 // text: '' // no text part
378 }
379
380 is automatically converted in the backround by Nodemailer to:
381
382 mailOptions = {
383 ...,
384 // source html:
385 html: '<h1>Hello world</h1><p><b>How</b> are you?',
386 // automatically generated plaintext message:
387 text: "Hello world\n"+
388 "===========\n"+
389 "\n"+
390 "**How** are you?"
391 }
392
393 As you can see the output syntax for `generateTextFromHTML` looks similar to markdown, and that
394 is exactly the case here - Nodemailer includes a simple HTML to markdown converter. But don't
395 expect too much from it, it's not full featured or perfect, just some regexes here and there.
396
3c3cca5 updated readme
Andris Reinman authored
397 ### Attachment fields
398
2685865 Updated readme
Andris Reinman authored
399 Attahcment object consists of the following properties:
3c3cca5 updated readme
Andris Reinman authored
400
401 * **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)
402 * **cid** - optional content id for using inline images in HTML message source
403 * **contents** - String or a Buffer contents for the attachment
02c57f0 Added URL option for attachments
Andris Reinman authored
404 * **filePath** - path to a file or an URL if you want to stream the file instead of including it (better for larger attachments)
80bd5a3 added support for binary streams for attachments
Andris Reinman authored
405 * **streamSource** - Stream object for arbitrary binary streams if you want to stream the contents (needs to support *pause*/*resume*)
2b9a3c9 Added messageId option
Andris Reinman authored
406 * **contentType** - optional content type for the attachment, if not set will be derived from the `fileName` property
407 * **contentDisposition** - optional content disposition type for the attachment, defaults to "attachment"
3c3cca5 updated readme
Andris Reinman authored
408
80bd5a3 added support for binary streams for attachments
Andris Reinman authored
409 One of `contents`, `filePath` or `streamSource` must be specified, if none is
410 present, the attachment will be discarded. Other fields are optional.
3c3cca5 updated readme
Andris Reinman authored
411
412 Attachments can be added as many as you want.
413
4a35e99 Readme update
Andris Reinman authored
414 var mailOptions = {
415 ...
416 attachments: [
02c57f0 Added URL option for attachments
Andris Reinman authored
417 { // utf-8 string as an attachment
4a35e99 Readme update
Andris Reinman authored
418 fileName: "text1.txt",
419 contents: "hello world!
420 },
02c57f0 Added URL option for attachments
Andris Reinman authored
421 { // binary buffer as an attachment
4a35e99 Readme update
Andris Reinman authored
422 fileName: "text2.txt",
423 contents: new Buffer("hello world!,"utf-8")
424 },
02c57f0 Added URL option for attachments
Andris Reinman authored
425 { // file on disk as an attachment
4a35e99 Readme update
Andris Reinman authored
426 fileName: "text3.txt",
427 filePath: "/path/to/file.txt" // stream this file
428 },
02c57f0 Added URL option for attachments
Andris Reinman authored
429 { // fileName and content type is derived from filePath
430 filePath: "/path/to/file.txt"
431 },
432 { // stream as an attachment
80bd5a3 added support for binary streams for attachments
Andris Reinman authored
433 fileName: "text4.txt",
434 streamSource: fs.createReadStream("file.txt")
435 },
02c57f0 Added URL option for attachments
Andris Reinman authored
436 { // define custom content type for the attachment
437 fileName: "text.bin",
4a35e99 Readme update
Andris Reinman authored
438 contents: "hello world!,
439 contentType: "text/plain"
02c57f0 Added URL option for attachments
Andris Reinman authored
440 },
441 { // use URL as an attachment
442 fileName: "license.txt",
443 contents: "https://raw.github.com/andris9/Nodemailer/master/LICENSE"
4a35e99 Readme update
Andris Reinman authored
444 }
445 ]
446 }
447
3c3cca5 updated readme
Andris Reinman authored
448 ### Address Formatting
449
450 All the e-mail addresses can be plain e-mail address
451
452 username@example.com
453
454 or with formatted name (includes unicode support)
455
456 "Ноде Майлер" <username@example.com>
457
458 To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.
459
460 username@example.com, "Ноде Майлер" <username@example.com>, "Name, User" <username@example.com>
461
462 You can even use unicode domain and user names, these are automatically converted
4a35e99 Readme update
Andris Reinman authored
463 to the supported form
3c3cca5 updated readme
Andris Reinman authored
464
465 "Uncode Domain" <info@müriaad-polüteism.info>
466
9285f5c updated mailcomposer dependency to support envelope property
Andris Reinman authored
467 ### SMTP envelope
468
469 SMTP envelope is usually auto generated from `from`, `to`, `cc` and `bcc` fields but
470 if for some reason you want to specify it yourself, you can do it with `envelope` property.
471
472 `envelope` is an object with the following params: `from`, `to`, `cc` and `bcc` just like
473 with regular mail options. You can also use the regular address format.
474
475 mailOptions = {
476 ...,
477 from: "mailer@node.ee",
478 to: "daemon@node.ee",
479 envelope: {
480 from: "Daemon <deamon@node.ee>",
481 to: "mailer@node.ee, Mailer <mailer2@node.ee>"
482 }
483 }
484
3c3cca5 updated readme
Andris Reinman authored
485 ### Using Embedded Images
486
487 Attachments can be used as embedded images in the HTML body. To use this
488 feature, you need to set additional property of the attachment - `cid` (unique
489 identifier of the file) which is a reference to the attachment file. The same
490 `cid` value must be used as the image URL in HTML (using `cid:` as the URL
491 protocol, see example below).
492
493 **NB!** the cid value should be as unique as possible!
494
4a35e99 Readme update
Andris Reinman authored
495 var mailOptions = {
496 ...
497 html: "Embedded image: <img src='cid:unique@node.ee' />",
498 attachments: [{
499 filename: "image.png",
500 filePath: "/path/to/file",
501 cid: "unique@node.ee" //same cid value as in the html img src
502 }]
503 }
3c3cca5 updated readme
Andris Reinman authored
504
505 ## Return callback
506
507 Return callback gets two parameters
508
509 * **error** - an error object if the message failed
510 * **responseStatus** - an object with some information about the status on success
511
c4cc33b Readme update
Andris Reinman authored
512 Example:
513
4a35e99 Readme update
Andris Reinman authored
514 nodemailer.sendMail(mailOptions, function(error, responseStatus){
515 if(!error){
516 console.log(responseStatus.message); // response from the server
517 }
518 });
519
3c3cca5 updated readme
Andris Reinman authored
520 ## Tests
521
522 Run the tests with npm in Nodemailer's directory
523
524 npm test
525
526 There aren't currently many tests for Nodemailer but there are a lot of tests
527 in the modules that are used to generate the raw e-mail body and to use the
528 SMTP client connection.
529
530 ## Tweaking
531
532 Nodemailer in itself is actually more like a wrapper for my other modules
533 [mailcomposer](https://github.com/andris9/mailcomposer) for composing the raw message stream
534 and [simplesmtp](https://github.com/andris9/simplesmtp) for delivering it, by providing an
535 unified API. If there's some problems with particular parts of the
536 message composing/sending process you should look at the appropriate module.
537
538 ## License
539
540 **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.