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