Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 155 lines (116 sloc) 5.237 kB
9305cea updating new attach code, support binary/base64 streams (fixes #18), …
eleith authored
1 #v0.2.0
fcfba12 first stab
eleith authored
2
3679d2b support starttls, update docs
eleith authored
3 ### emailjs
4
5 send emails, html and attachments from node.js to any smtp server
fcfba12 first stab
eleith authored
6
7 ### Installing
8
3679d2b support starttls, update docs
eleith authored
9 npm install emailjs
fcfba12 first stab
eleith authored
10
11 # FEATURES
3679d2b support starttls, update docs
eleith authored
12 - works with SSL and TLS smtp servers (ex: gmail)
13 - supports smtp authentication (PLAIN, LOGIN, CRAMMD5)
fcfba12 first stab
eleith authored
14 - emails are queued and the queue is sent asynchronously
3679d2b support starttls, update docs
eleith authored
15 - supports sending html emails and emails with multiple attachments (MIME)
9305cea updating new attach code, support binary/base64 streams (fixes #18), …
eleith authored
16 - attachments can added as strings, streams or file paths
a235151 support pair._ssl and pair.ssl
eleith authored
17 - works with nodejs 3.8 and above
fcfba12 first stab
eleith authored
18
19 # REQUIRES
20 - access to an SMTP Server (ex: gmail)
21
5dc8ab6 organizing readme sections
eleith authored
22 # EXAMPLE USAGE - text only emails
23
24 var email = require("./path/to/emailjs/email");
25 var server = email.server.connect({
26 user: "username",
27 password:"password",
28 host: "smtp.gmail.com",
29 ssl: true
30 });
31
32 // send the message and get a callback with an error or details of the message that was sent
33 server.send({
34 text: "i hope this works",
35 from: "you <username@gmail.com>",
36 to: "someone <someone@gmail.com>, another <another@gmail.com>",
37 cc: "else <else@gmail.com>",
38 subject: "testing emailjs"
39 }, function(err, message) { console.log(err || message); });
40
41 # EXAMPLE USAGE - html emails and attachments
42
43 var email = require("./path/to/emailjs/email");
44 var server = email.server.connect({
45 user: "username",
46 password:"password",
47 host: "smtp.gmail.com",
48 ssl: true
49 });
50
51 var headers = {
52 text: "i hope this works",
53 from: "you <username@gmail.com>",
54 to: "someone <someone@gmail.com>, another <another@gmail.com>",
55 cc: "else <else@gmail.com>",
56 subject: "testing emailjs"
57 };
58
59 // create the message
60 var message = email.message.create(headers);
61
62 // attach an alternative html email for those with advanced email clients
9305cea updating new attach code, support binary/base64 streams (fixes #18), …
eleith authored
63 message.attach({data:"<html>i <i>hope</i> this works!</html>", alternative:true});
5dc8ab6 organizing readme sections
eleith authored
64
65 // attach attachments because you can!
9305cea updating new attach code, support binary/base64 streams (fixes #18), …
eleith authored
66 message.attach({path:"path/to/file.zip", type:"application/zip", name:"renamed.zip"});
5dc8ab6 organizing readme sections
eleith authored
67
68 // send the message and get a callback with an error or details of the message that was sent
69 server.send(message, function(err, message) { console.log(err || message); });
70
71 // you can continue to send more messages with successive calls to 'server.send',
72 // they will be queued on the same smtp connection
73
74 // or you can create a new server connection with 'email.server.connect'
75 // to asynchronously send individual emails instead of a queue
76
3679d2b support starttls, update docs
eleith authored
77 # API
78
79 ## email.server.connect(options)
80
81 // options is an object with the following keys
82 options =
83 {
ad53613 fix support for non authenticated smtp use, update documentation
eleith authored
84 user // username for logging into smtp
3679d2b support starttls, update docs
eleith authored
85 password // password for logging into smtp
86 host // smtp host
87 port // smtp port (if null a standard port number will be used)
88 ssl // boolean or object {key, ca, cert} (if exists, ssl connection will be made)
89 tls // boolean (if true, starttls will be initiated)
90 timeout // max number of milliseconds to wait for smtp responses (defaults to 5000)
91 domain // domain to greet smtp with (defaults to os.hostname)
92 }
93
94 ## email.server.send(message, callback)
95
96 // message can be a smtp.Message (as returned by email.message.create)
97 // or an object identical to the first argument accepted by email.message.create
98
99 // callback will be executed with (err, message)
100 // either when message is sent or an error has occurred
101
102 ## email.message.create(headers)
103
b427058 Update Readme.md
eleith authored
104 // headers is an object ('from' and 'to' are required)
105 // returns a Message object
106
107 // you can actually pass more message headers than listed, the below are just the
108 // most common ones you would want to use
109
110 headers =
111 {
112 text // text of the email
113 from // sender of the format (address or name <address> or "name" <address>)
114 to // recipients (same format as above), multiple recipients are separated by a comma
115 cc // carbon copied recipients (same format as above)
116 bcc // blind carbon copied recipients (same format as above)
117 subject // string subject of the email
118 }
3679d2b support starttls, update docs
eleith authored
119
c3d27a1 @mscdex Update documentation
mscdex authored
120 ## Message.attach(options)
3679d2b support starttls, update docs
eleith authored
121
b427058 Update Readme.md
eleith authored
122 // can be called multiple times, each adding a new attachment
123 // options is an object with the following possible keys:
f4cdeb8 formatting readme
eleith authored
124
b427058 Update Readme.md
eleith authored
125 options =
126 {
127 // one of these fields is required
128 path // string to where the file is located
129 data // string of the data you want to attach
130 stream // binary stream that will provide attachment data (make sure it is in the paused state)
131 // better performance for binary streams is achieved if buffer.length % (76*6) == 0
132 // current max size of buffer must be no larger than Message.BUFFERSIZE
f4cdeb8 formatting readme
eleith authored
133
b427058 Update Readme.md
eleith authored
134 // optionally these fields are also accepted
135 type // string of the file mime type
136 name // name to give the file as perceived by the recipient
137 alternative // if true, will be attached inline as an alternative (also defaults type='text/html')
138 inline // if true, will be attached inline
139 encoded // set this to true if the data is already base64 encoded, (avoid this if possible)
140 headers // object containing header=>value pairs for inclusion in this attachment's header
141 }
3679d2b support starttls, update docs
eleith authored
142
fcfba12 first stab
eleith authored
143 ## Authors
144
145 eleith
9305cea updating new attach code, support binary/base64 streams (fixes #18), …
eleith authored
146
147 ## Testing
148
149 npm install -d
150 npm test
151
152 ## Contributions
153
154 issues and pull requests are welcome
Something went wrong with that request. Please try again.