Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 186 lines (147 sloc) 6.461 kb
e85ebe1 update test environment
eleith authored
1 # emailjs [![Build Status](https://secure.travis-ci.org/eleith/emailjs.png)](http://travis-ci.org/eleith/emailjs)
3679d2b support starttls, update docs
eleith authored
2
6ad4112 updated readme
eleith authored
3 send emails, html and attachments (files, streams and strings) from node.js to any smtp server
fcfba12 first stab
eleith authored
4
4a63c04 Update Readme.md
eleith authored
5 ## INSTALLING
fcfba12 first stab
eleith authored
6
3679d2b support starttls, update docs
eleith authored
7 npm install emailjs
fcfba12 first stab
eleith authored
8
4a63c04 Update Readme.md
eleith authored
9 ## FEATURES
20a0e19 update readme with gmail two-step advice
eleith authored
10 - works with SSL and TLS smtp servers
3679d2b support starttls, update docs
eleith authored
11 - supports smtp authentication (PLAIN, LOGIN, CRAMMD5)
fcfba12 first stab
eleith authored
12 - emails are queued and the queue is sent asynchronously
3679d2b support starttls, update docs
eleith authored
13 - supports sending html emails and emails with multiple attachments (MIME)
6efb0ff english
eleith authored
14 - attachments can be added as strings, streams or file paths
c9b5d85 update package.json properly
eleith authored
15 - supports utf-8 headers and body
fcfba12 first stab
eleith authored
16
4a63c04 Update Readme.md
eleith authored
17 ## REQUIRES
20a0e19 update readme with gmail two-step advice
eleith authored
18 - auth access to an SMTP Server
dbf4cf5 @skalnik Fix a small typo :pencil2:
skalnik authored
19 - if your service (ex: gmail) uses two-step authentication, use an application specific password
fcfba12 first stab
eleith authored
20
4a63c04 Update Readme.md
eleith authored
21 ## EXAMPLE USAGE - text only emails
5dc8ab6 organizing readme sections
eleith authored
22
6a9cd97 Update Readme.md
eleith authored
23 ```javascript
24 var email = require("./path/to/emailjs/email");
25 var server = email.server.connect({
26 user: "username",
27 password:"password",
20a0e19 update readme with gmail two-step advice
eleith authored
28 host: "smtp.your-email.com",
6a9cd97 Update Readme.md
eleith authored
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",
20a0e19 update readme with gmail two-step advice
eleith authored
35 from: "you <username@your-email.com>",
36 to: "someone <someone@your-email.com>, another <another@your-email.com>",
37 cc: "else <else@your-email.com>",
6a9cd97 Update Readme.md
eleith authored
38 subject: "testing emailjs"
39 }, function(err, message) { console.log(err || message); });
40 ```
5dc8ab6 organizing readme sections
eleith authored
41
4a63c04 Update Readme.md
eleith authored
42 ## EXAMPLE USAGE - html emails and attachments
5dc8ab6 organizing readme sections
eleith authored
43
6a9cd97 Update Readme.md
eleith authored
44 ```javascript
45 var email = require("./path/to/emailjs/email");
46 var server = email.server.connect({
47 user: "username",
48 password:"password",
20a0e19 update readme with gmail two-step advice
eleith authored
49 host: "smtp.your-email.com",
6a9cd97 Update Readme.md
eleith authored
50 ssl: true
51 });
52
8ee6877 new test suite, remove need to explicitly call email.message.create
eleith authored
53 var message = {
6a9cd97 Update Readme.md
eleith authored
54 text: "i hope this works",
20a0e19 update readme with gmail two-step advice
eleith authored
55 from: "you <username@your-email.com>",
56 to: "someone <someone@your-email.com>, another <another@your-email.com>",
57 cc: "else <else@your-email.com>",
8ee6877 new test suite, remove need to explicitly call email.message.create
eleith authored
58 subject: "testing emailjs",
59 attachment:
60 [
61 {data:"<html>i <i>hope</i> this works!</html>", alternative:true},
62 {path:"path/to/file.zip", type:"application/zip", name:"renamed.zip"}
63 ]
6a9cd97 Update Readme.md
eleith authored
64 };
65
66 // send the message and get a callback with an error or details of the message that was sent
67 server.send(message, function(err, message) { console.log(err || message); });
68
69 // you can continue to send more messages with successive calls to 'server.send',
70 // they will be queued on the same smtp connection
71
72 // or you can create a new server connection with 'email.server.connect'
73 // to asynchronously send individual emails instead of a queue
74 ```
13785da allow tls to be an object to customize ciphers, pass through arguments i...
eleith authored
75
76 ## EXAMPLE USAGE - sending through hotmail/outlook
77
78 ```javascript
79 var email = require("./path/to/emailjs/email");
80 var server = email.server.connect({
81 user: "username",
82 password:"password",
83 host: "smtp-mail.outlook.com",
84 tls: {ciphers: "SSLv3"}
85 });
86
87 var message = {
88 text: "i hope this works",
89 from: "you <username@outlook.com>",
20a0e19 update readme with gmail two-step advice
eleith authored
90 to: "someone <someone@your-email.com>, another <another@your-email.com>",
91 cc: "else <else@your-email.com>",
13785da allow tls to be an object to customize ciphers, pass through arguments i...
eleith authored
92 subject: "testing emailjs",
93 attachment:
94 [
95 {data:"<html>i <i>hope</i> this works!</html>", alternative:true},
96 {path:"path/to/file.zip", type:"application/zip", name:"renamed.zip"}
97 ]
98 };
99
100 // send the message and get a callback with an error or details of the message that was sent
101 server.send(message, function(err, message) { console.log(err || message); });
102 ```
103
3679d2b support starttls, update docs
eleith authored
104 # API
105
106 ## email.server.connect(options)
107
108 // options is an object with the following keys
109 options =
110 {
ad53613 fix support for non authenticated smtp use, update documentation
eleith authored
111 user // username for logging into smtp
3679d2b support starttls, update docs
eleith authored
112 password // password for logging into smtp
113 host // smtp host
114 port // smtp port (if null a standard port number will be used)
13785da allow tls to be an object to customize ciphers, pass through arguments i...
eleith authored
115 ssl // boolean or object {key, ca, cert} (if true or object, ssl connection will be made)
116 tls // boolean or object (if true or object, starttls will be initiated)
3679d2b support starttls, update docs
eleith authored
117 timeout // max number of milliseconds to wait for smtp responses (defaults to 5000)
118 domain // domain to greet smtp with (defaults to os.hostname)
119 }
120
121 ## email.server.send(message, callback)
122
123 // message can be a smtp.Message (as returned by email.message.create)
124 // or an object identical to the first argument accepted by email.message.create
125
126 // callback will be executed with (err, message)
127 // either when message is sent or an error has occurred
128
8ee6877 new test suite, remove need to explicitly call email.message.create
eleith authored
129 ## message
3679d2b support starttls, update docs
eleith authored
130
b427058 Update Readme.md
eleith authored
131 // headers is an object ('from' and 'to' are required)
132 // returns a Message object
133
134 // you can actually pass more message headers than listed, the below are just the
135 // most common ones you would want to use
136
137 headers =
138 {
139 text // text of the email
140 from // sender of the format (address or name <address> or "name" <address>)
141 to // recipients (same format as above), multiple recipients are separated by a comma
142 cc // carbon copied recipients (same format as above)
143 bcc // blind carbon copied recipients (same format as above)
144 subject // string subject of the email
8ee6877 new test suite, remove need to explicitly call email.message.create
eleith authored
145 attachment // one attachment or array of attachments
b427058 Update Readme.md
eleith authored
146 }
3679d2b support starttls, update docs
eleith authored
147
8ee6877 new test suite, remove need to explicitly call email.message.create
eleith authored
148 ## attachment
3679d2b support starttls, update docs
eleith authored
149
b427058 Update Readme.md
eleith authored
150 // can be called multiple times, each adding a new attachment
151 // options is an object with the following possible keys:
f4cdeb8 formatting readme
eleith authored
152
b427058 Update Readme.md
eleith authored
153 options =
154 {
155 // one of these fields is required
156 path // string to where the file is located
157 data // string of the data you want to attach
158 stream // binary stream that will provide attachment data (make sure it is in the paused state)
159 // better performance for binary streams is achieved if buffer.length % (76*6) == 0
160 // current max size of buffer must be no larger than Message.BUFFERSIZE
f4cdeb8 formatting readme
eleith authored
161
b427058 Update Readme.md
eleith authored
162 // optionally these fields are also accepted
163 type // string of the file mime type
164 name // name to give the file as perceived by the recipient
a26c907 @eleith add method field for attachments
authored
165 charset // charset to encode attatchment in
166 method // method to send attachment as (used by calendar invites)
b427058 Update Readme.md
eleith authored
167 alternative // if true, will be attached inline as an alternative (also defaults type='text/html')
168 inline // if true, will be attached inline
169 encoded // set this to true if the data is already base64 encoded, (avoid this if possible)
170 headers // object containing header=>value pairs for inclusion in this attachment's header
aeaa753 version bump
eleith authored
171 related // an array of attachments that you want to be related to the parent attachment
b427058 Update Readme.md
eleith authored
172 }
3679d2b support starttls, update docs
eleith authored
173
fcfba12 first stab
eleith authored
174 ## Authors
175
176 eleith
9305cea updating new attach code, support binary/base64 streams (fixes #18), usi...
eleith authored
177
178 ## Testing
179
5cab165 Update Readme.md
eleith authored
180 npm install -d
181 npm test
9305cea updating new attach code, support binary/base64 streams (fixes #18), usi...
eleith authored
182
183 ## Contributions
184
185 issues and pull requests are welcome
Something went wrong with that request. Please try again.