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