Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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