Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 555 lines (407 sloc) 21.233 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 }
20de70a updated readme and examples
Andris Reinman authored
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
7b87567 Updated readme
Andris Reinman authored
79 });
80
4a35e99 Readme update
Andris Reinman authored
81 See also the [examples folder](https://github.com/andris9/Nodemailer/tree/master/examples)
c4cc33b Readme update
Andris Reinman authored
82 for full featured examples
4a35e99 Readme update
Andris Reinman authored
83
3c3cca5 updated readme
Andris Reinman authored
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
07db51a updated sending api, backwards compatible
Andris Reinman authored
96 An e-mail can be sent with `sendMail(mailOptions[, callback])` command
3c3cca5 updated readme
Andris Reinman authored
97
07db51a updated sending api, backwards compatible
Andris Reinman authored
98 transport.sendMail(mailOptions, callback);
3c3cca5 updated readme
Andris Reinman authored
99
100 Where
101
eb7d4fd @andris9 Update README.md
authored
102 * `transport` is a transport method defined with `nodemailer.createTransport`
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
d768813 Changed new Transport to createTransport
Andris Reinman authored
109 be done with `nodemailer.createTransport(type, options)` where `type` indicates
e328b6d updated readme
Andris Reinman authored
110 the transport protocol and `options` defines how it is used.
3c3cca5 updated readme
Andris Reinman authored
111
d768813 Changed new Transport to createTransport
Andris Reinman authored
112 var transport = nodemailer.createTransport("SMTP", {smtp_options});
3c3cca5 updated readme
Andris Reinman authored
113
114 The same transport object can and should be reused several times.
115
eb7d4fd @andris9 Update README.md
authored
116 When the transport method is defined, it can be used to send e-mail with `sendMail`
3c3cca5 updated readme
Andris Reinman authored
117
d768813 Changed new Transport to createTransport
Andris Reinman authored
118 var transport = nodemailer.createTransport("SMTP", {smtp_options});
3c3cca5 updated readme
Andris Reinman authored
119
eb7d4fd @andris9 Update README.md
authored
120 transport.sendMail({
3c3cca5 updated readme
Andris Reinman authored
121 from: "sender@tr.ee",
40b7b48 Updated readme
Andris Reinman authored
122 to: "receiver@tr.ee"
123 ...
eb7d4fd @andris9 Update README.md
authored
124 });
3c3cca5 updated readme
Andris Reinman authored
125
126 ### Possible transport methods
127
40b7b48 Updated readme
Andris Reinman authored
128 Required `type` parameter can be one of the following:
3c3cca5 updated readme
Andris Reinman authored
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
40b7b48 Updated readme
Andris Reinman authored
138 are reusable to minimize the protocol overhead delay - for example setting up
3c3cca5 updated readme
Andris Reinman authored
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
65cfdab Updated readme
Andris Reinman authored
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
3c3cca5 updated readme
Andris Reinman authored
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`)
9f30440 Updated README about secureConnection option
Andris Reinman authored
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
3c3cca5 updated readme
Andris Reinman authored
148 * **name** - the name of the client server (defaults to machine name)
c075b9b Added XOAuthToken auth option for Gmail XOAUTH support
Andris Reinman authored
149 * **auth** - authentication object as `{user:"...", pass:"..."}` or `{XOAuthToken: "base64data"}`
3c3cca5 updated readme
Andris Reinman authored
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
d768813 Changed new Transport to createTransport
Andris Reinman authored
156 var transport = nodemailer.createTransport("SMTP", {
3c3cca5 updated readme
Andris Reinman authored
157 service: "Gmail",
158 auth: {
159 user: "gmail.user@gmail.com",
160 pass: "userpass"
161 }
162 });
163
4a35e99 Readme update
Andris Reinman authored
164 or the same without `service` parameter
165
d768813 Changed new Transport to createTransport
Andris Reinman authored
166 var transport = nodemailer.createTransport("SMTP", {
4a35e99 Readme update
Andris Reinman authored
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
3c3cca5 updated readme
Andris Reinman authored
176 **NB!** if you want to close the pool (cancel all open connections) you can use
177 `transport.close()`
178
d768813 Changed new Transport to createTransport
Andris Reinman authored
179 var transport = nodemailer.createTransport("SMTP",{});
3c3cca5 updated readme
Andris Reinman authored
180 ...
181 transport.close(); // close the pool
182
26794a7 Fixed XOAUTH generator defaults bug, updated README
Andris Reinman authored
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
9fdff73 updated README
Andris Reinman authored
189 var transportOptions = {
26794a7 Fixed XOAUTH generator defaults bug, updated README
Andris Reinman authored
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
9fdff73 updated README
Andris Reinman authored
212 var transportOptions = {
213 service: "Gmail",
26794a7 Fixed XOAUTH generator defaults bug, updated README
Andris Reinman authored
214 auth: {
215 XOAuthToken: nodemailer.createXOAuthGenerator({
216 user: "test.nodemailer@gmail.com",
217 token: "1/O_HgoO4h2uOUfpus0V--7mygICXrQQ0ZajB3ZH52KqM",
218 tokenSecret: "_mUBkIwNPnfQBUIWrJrpXJ0c"
d917ad9 update
Andris Reinman authored
219 })
26794a7 Fixed XOAUTH generator defaults bug, updated README
Andris Reinman authored
220 }
221 }
222
3c3cca5 updated readme
Andris Reinman authored
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)
2685865 Updated readme
Andris Reinman authored
232 * **ServiceUrl** - optional API end point URL (defaults to *"https://email.us-east-1.amazonaws.com"*)
3c3cca5 updated readme
Andris Reinman authored
233
234 Example:
235
d768813 Changed new Transport to createTransport
Andris Reinman authored
236 var transport = nodemailer.createTransport("SES", {
3c3cca5 updated readme
Andris Reinman authored
237 AWSAccessKeyID: "AWSACCESSKEY",
238 AWSSecretKey: "AWS/Secret/key"
239 });
240
241 ### Setting up Sendmail
242
2685865 Updated readme
Andris Reinman authored
243 Sendmail transport method streams the compiled message to the *stdin* of *sendmail*
3c3cca5 updated readme
Andris Reinman authored
244 command.
245
dce4b06 updated readme
Andris Reinman authored
246 Options object is optional, possible sendmail options are the following:
3c3cca5 updated readme
Andris Reinman authored
247
ac74656 Sendmail support update
Andris Reinman authored
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"]`)
3c3cca5 updated readme
Andris Reinman authored
250
dce4b06 updated readme
Andris Reinman authored
251 Example:
252
253 var transport = nodemailer.createTransport("sendmail");
254
255 or
256
257 var transport = nodemailer.createTransport("sendmail", {
258 path: "/usr/local/bin/sendmail",
259 args: ["-f sender@example.com"]
260 });
261
52cf687 Added DKIM signing support
Andris Reinman authored
262 ### DKIM Signing
263
264 **Nodemailer** supports DKIM signing with very simple setup. Use this with caution
265 though since the generated message needs to be buffered entirely before it can be
36d191c Updated README
Andris Reinman authored
266 signed. Not a big deal with small messages but might consume a lot of RAM when
267 using larger attachments.
52cf687 Added DKIM signing support
Andris Reinman authored
268
269 Set up the DKIM signing with `useDKIM` method for a transport object:
270
271 transport.useDKIM(dkimOptions)
272
273 Where `dkimOptions` includes necessary options for signing
274
275 * **domainName** - the domainname that is being used for signing
276 * **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
277 * **privateKey** - DKIM private key that is used for signing as a string
278 * **headerFieldNames** - optional colon separated list of header fields to sign, by default all fields suggested by RFC4871 #5.5 are used
279
280 All messages transmitted through this transport objects are from now on DKIM signed.
281
1f93264 Updated README
Andris Reinman authored
282 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
283
284 Example:
285
286 var transport = nodemailer.createTransport("Sendmail");
287
288 transport.useDKIM({
289 domainName: "node.ee",
290 keySelector: "dkim",
291 privateKey: fs.readFileSync("private_key.pem")
292 });
293
294 transport.sendMail(mailOptions);
295
296 See examples/example_dkim.js for a complete example.
297
1f93264 Updated README
Andris Reinman authored
298 **NB!** Be careful when using services like Gmail, SES etc. through SMTP
299 (SES API is handled by Nodemailer automatically) - these tend to modify some
300 headers like Message-Id or Date which invalidates the signature. In this case use
301 `headerFieldNames` property to define only fields that won't be changed and leave
302 out `Date` or any other unsupported field.
303
3c3cca5 updated readme
Andris Reinman authored
304 ### Well known services for SMTP
93f2d1f Updated docs etc
Andris Reinman authored
305
306 If you want to use a well known service as the SMTP host, you do not need
5fef793 readme update
Andris Reinman authored
307 to enter the hostname or port number, just use the `service` parameter (**NB!** case sensitive).
93f2d1f Updated docs etc
Andris Reinman authored
308
309 Currently cupported services are:
310
311 * **"Gmail"** for Google Mail
312 * **"hot.ee"** for www.hot.ee
313 * **"Hotmail"** for Microsoft Live Hotmail
314 * **"iCloud"** for Apple iCloud
315 * **"mail.ee"** for www.mail.ee
316 * **"Postmark"** for Postmark App
317 * **"SendGrid"** for SendGrid
318 * **"SES"** for Amazon SES
319 * **"Yahoo"** for Yahoo Mail
320 * **"Zoho"** for Zoho Mail
321
3c3cca5 updated readme
Andris Reinman authored
322 Predefined service data covers `host`, `port` and secure connection settings,
323 any other parameters (ie. `auth`) need to be set separately.
93f2d1f Updated docs etc
Andris Reinman authored
324
3c3cca5 updated readme
Andris Reinman authored
325 ## E-mail message fields
93f2d1f Updated docs etc
Andris Reinman authored
326
3c3cca5 updated readme
Andris Reinman authored
327 The following are the possible fields of an e-mail message:
328
329 - **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>`
330 - **to** - Comma separated list of recipients e-mail addresses that will appear on the `To:` field
331 - **cc** - Comma separated list of recipients e-mail addresses that will appear on the `Cc:` field
332 - **bcc** - Comma separated list of recipients e-mail addresses that will appear on the `Bcc:` field
333 - **replyTo** - An e-mail address that will appear on the `Reply-To:` field
334 - **subject** - The subject of the e-mail
335 - **text** - The plaintext version of the message
336 - **html** - The HTML version of the message
aae3749 regenerated docs
Andris Reinman authored
337 - **generateTextFromHTML** - if set to true uses HTML to generate plain text body part from the HTML if the text is not defined
d6cc175 @andris9 Update README.md
authored
338 - **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)
3c3cca5 updated readme
Andris Reinman authored
339 - **attachments** - An array of attachment objects.
9285f5c updated mailcomposer dependency to support envelope property
Andris Reinman authored
340 - **envelope** - optional SMTP envelope, if auto generated envelope is not suitable
4ec8fbd @skabbes Updated README.md for new messageId option
skabbes authored
341 - **messageId** - optional Message-Id value, random value will be generated if not set. Set to false to omit the Message-Id header
8fb65b8 @skabbes Allow the mailcomposer encoding to be specified
skabbes authored
342 - **encoding** - optional transfer encoding for the textual parts (defaults to "quoted-printable")
3c3cca5 updated readme
Andris Reinman authored
343
344 All text fields (e-mail addresses, plaintext body, html body) use UTF-8 as the encoding.
345 Attachments are streamed as binary.
346
347 Example:
348
d768813 Changed new Transport to createTransport
Andris Reinman authored
349 var transport = nodemailer.createTransport("Sendmail");
3c3cca5 updated readme
Andris Reinman authored
350
351 var mailOptions = {
352 from: "me@tr.ee",
353 to: "me@tr.ee",
354 subject: "Hello world!",
2685865 Updated readme
Andris Reinman authored
355 text: "Plaintext body"
3c3cca5 updated readme
Andris Reinman authored
356 }
357
07db51a updated sending api, backwards compatible
Andris Reinman authored
358 transport.sendMail(mailOptions);
3c3cca5 updated readme
Andris Reinman authored
359
ecfeb0e updated README for SendGrid support
Andris Reinman authored
360 ### SendGrid support
361
362 Nodemailer supports SendGrid [SMTP API](http://docs.sendgrid.com/documentation/api/smtp-api/) out of the box - you can
363 use objects as header values and these are automatically JSONized (and mime encoded if needed).
364
365 var mailOptions = {
366 ...,
367 headers: {
368 'X-SMTPAPI': {
369 category : "newuser",
370 sub:{
371 "%name%": ["Žiguli Õllepruul"]
372 }
373 }
3c9462a updated README for SendGrid support
Andris Reinman authored
374 },
375 subject: "Hello, %name%"
ecfeb0e updated README for SendGrid support
Andris Reinman authored
376 }
377
3c9462a updated README for SendGrid support
Andris Reinman authored
378 This also applies to any other service that expects a JSON string as a header value for specified key.
379
d1f45e1 @andris9 Update README.md
authored
380 ### Generate Text from HTML
381
382 If `generateTextFromHTML` option is set to true, then HTML contents of the mail is automatically converted
383 to plaintext format when plaintext content is empty or missing.
384
385 For example
386
387 mailOptions = {
388 ...,
389 generateTextFromHTML: true,
390 html: '<h1>Hello world</h1><p><b>How</b> are you?',
391 // text: '' // no text part
392 }
393
394 is automatically converted in the backround by Nodemailer to:
395
396 mailOptions = {
397 ...,
398 // source html:
399 html: '<h1>Hello world</h1><p><b>How</b> are you?',
400 // automatically generated plaintext message:
401 text: "Hello world\n"+
402 "===========\n"+
403 "\n"+
404 "**How** are you?"
405 }
406
407 As you can see the output syntax for `generateTextFromHTML` looks similar to markdown, and that
408 is exactly the case here - Nodemailer includes a simple HTML to markdown converter. But don't
409 expect too much from it, it's not full featured or perfect, just some regexes here and there.
410
3c3cca5 updated readme
Andris Reinman authored
411 ### Attachment fields
412
2685865 Updated readme
Andris Reinman authored
413 Attahcment object consists of the following properties:
3c3cca5 updated readme
Andris Reinman authored
414
415 * **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)
416 * **cid** - optional content id for using inline images in HTML message source
417 * **contents** - String or a Buffer contents for the attachment
02c57f0 Added URL option for attachments
Andris Reinman authored
418 * **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
419 * **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
420 * **contentType** - optional content type for the attachment, if not set will be derived from the `fileName` property
421 * **contentDisposition** - optional content disposition type for the attachment, defaults to "attachment"
3c3cca5 updated readme
Andris Reinman authored
422
80bd5a3 added support for binary streams for attachments
Andris Reinman authored
423 One of `contents`, `filePath` or `streamSource` must be specified, if none is
424 present, the attachment will be discarded. Other fields are optional.
3c3cca5 updated readme
Andris Reinman authored
425
426 Attachments can be added as many as you want.
427
4a35e99 Readme update
Andris Reinman authored
428 var mailOptions = {
429 ...
430 attachments: [
02c57f0 Added URL option for attachments
Andris Reinman authored
431 { // utf-8 string as an attachment
4a35e99 Readme update
Andris Reinman authored
432 fileName: "text1.txt",
433 contents: "hello world!
434 },
02c57f0 Added URL option for attachments
Andris Reinman authored
435 { // binary buffer as an attachment
4a35e99 Readme update
Andris Reinman authored
436 fileName: "text2.txt",
437 contents: new Buffer("hello world!,"utf-8")
438 },
02c57f0 Added URL option for attachments
Andris Reinman authored
439 { // file on disk as an attachment
4a35e99 Readme update
Andris Reinman authored
440 fileName: "text3.txt",
441 filePath: "/path/to/file.txt" // stream this file
442 },
02c57f0 Added URL option for attachments
Andris Reinman authored
443 { // fileName and content type is derived from filePath
444 filePath: "/path/to/file.txt"
445 },
446 { // stream as an attachment
80bd5a3 added support for binary streams for attachments
Andris Reinman authored
447 fileName: "text4.txt",
448 streamSource: fs.createReadStream("file.txt")
449 },
02c57f0 Added URL option for attachments
Andris Reinman authored
450 { // define custom content type for the attachment
451 fileName: "text.bin",
4a35e99 Readme update
Andris Reinman authored
452 contents: "hello world!,
453 contentType: "text/plain"
02c57f0 Added URL option for attachments
Andris Reinman authored
454 },
455 { // use URL as an attachment
456 fileName: "license.txt",
e26edb2 updated README
Andris Reinman authored
457 filePath: "https://raw.github.com/andris9/Nodemailer/master/LICENSE"
4a35e99 Readme update
Andris Reinman authored
458 }
459 ]
460 }
461
3c3cca5 updated readme
Andris Reinman authored
462 ### Address Formatting
463
464 All the e-mail addresses can be plain e-mail address
465
466 username@example.com
467
468 or with formatted name (includes unicode support)
469
470 "Ноде Майлер" <username@example.com>
471
472 To, Cc and Bcc fields accept comma separated list of e-mails. Formatting can be mixed.
473
474 username@example.com, "Ноде Майлер" <username@example.com>, "Name, User" <username@example.com>
475
476 You can even use unicode domain and user names, these are automatically converted
4a35e99 Readme update
Andris Reinman authored
477 to the supported form
3c3cca5 updated readme
Andris Reinman authored
478
479 "Uncode Domain" <info@müriaad-polüteism.info>
480
9285f5c updated mailcomposer dependency to support envelope property
Andris Reinman authored
481 ### SMTP envelope
482
483 SMTP envelope is usually auto generated from `from`, `to`, `cc` and `bcc` fields but
484 if for some reason you want to specify it yourself, you can do it with `envelope` property.
485
486 `envelope` is an object with the following params: `from`, `to`, `cc` and `bcc` just like
487 with regular mail options. You can also use the regular address format.
488
489 mailOptions = {
490 ...,
491 from: "mailer@node.ee",
492 to: "daemon@node.ee",
493 envelope: {
494 from: "Daemon <deamon@node.ee>",
495 to: "mailer@node.ee, Mailer <mailer2@node.ee>"
496 }
497 }
498
3c3cca5 updated readme
Andris Reinman authored
499 ### Using Embedded Images
500
501 Attachments can be used as embedded images in the HTML body. To use this
502 feature, you need to set additional property of the attachment - `cid` (unique
503 identifier of the file) which is a reference to the attachment file. The same
504 `cid` value must be used as the image URL in HTML (using `cid:` as the URL
505 protocol, see example below).
506
507 **NB!** the cid value should be as unique as possible!
508
4a35e99 Readme update
Andris Reinman authored
509 var mailOptions = {
510 ...
511 html: "Embedded image: <img src='cid:unique@node.ee' />",
512 attachments: [{
513 filename: "image.png",
514 filePath: "/path/to/file",
515 cid: "unique@node.ee" //same cid value as in the html img src
516 }]
517 }
3c3cca5 updated readme
Andris Reinman authored
518
519 ## Return callback
520
521 Return callback gets two parameters
522
523 * **error** - an error object if the message failed
524 * **responseStatus** - an object with some information about the status on success
525
c4cc33b Readme update
Andris Reinman authored
526 Example:
527
4a35e99 Readme update
Andris Reinman authored
528 nodemailer.sendMail(mailOptions, function(error, responseStatus){
529 if(!error){
530 console.log(responseStatus.message); // response from the server
531 }
532 });
533
3c3cca5 updated readme
Andris Reinman authored
534 ## Tests
535
536 Run the tests with npm in Nodemailer's directory
537
538 npm test
539
540 There aren't currently many tests for Nodemailer but there are a lot of tests
541 in the modules that are used to generate the raw e-mail body and to use the
542 SMTP client connection.
543
544 ## Tweaking
545
546 Nodemailer in itself is actually more like a wrapper for my other modules
547 [mailcomposer](https://github.com/andris9/mailcomposer) for composing the raw message stream
548 and [simplesmtp](https://github.com/andris9/simplesmtp) for delivering it, by providing an
549 unified API. If there's some problems with particular parts of the
550 message composing/sending process you should look at the appropriate module.
551
552 ## License
553
4ec8fbd @skabbes Updated README.md for new messageId option
skabbes authored
554 **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.