2020-05-01 20:12:52 +00:00
|
|
|
# emailjs [](https://github.com/eleith/emailjs/actions?query=workflow%3A.github%2Fworkflows%2Ftest.yml)
|
2011-02-24 23:02:24 +00:00
|
|
|
|
2011-12-09 11:13:37 +00:00
|
|
|
send emails, html and attachments (files, streams and strings) from node.js to any smtp server
|
2011-02-23 21:23:37 +00:00
|
|
|
|
2011-12-09 11:28:25 +00:00
|
|
|
## INSTALLING
|
2011-02-23 21:23:37 +00:00
|
|
|
|
2011-02-24 23:02:24 +00:00
|
|
|
npm install emailjs
|
2011-02-23 21:23:37 +00:00
|
|
|
|
2011-12-09 11:28:25 +00:00
|
|
|
## FEATURES
|
2018-07-12 18:57:38 +00:00
|
|
|
- works with SSL and TLS smtp servers
|
2017-07-16 17:07:59 +00:00
|
|
|
- supports smtp authentication ('PLAIN', 'LOGIN', 'CRAM-MD5', 'XOAUTH2')
|
2011-02-23 21:23:37 +00:00
|
|
|
- emails are queued and the queue is sent asynchronously
|
2011-02-24 23:02:24 +00:00
|
|
|
- supports sending html emails and emails with multiple attachments (MIME)
|
2011-12-09 11:15:13 +00:00
|
|
|
- attachments can be added as strings, streams or file paths
|
2014-04-07 10:11:20 +00:00
|
|
|
- supports utf-8 headers and body
|
2011-02-23 21:23:37 +00:00
|
|
|
|
2011-12-09 11:28:25 +00:00
|
|
|
## REQUIRES
|
2014-07-05 16:35:05 +00:00
|
|
|
- auth access to an SMTP Server
|
2014-12-01 04:48:11 +00:00
|
|
|
- if your service (ex: gmail) uses two-step authentication, use an application specific password
|
2011-02-23 21:23:37 +00:00
|
|
|
|
2011-12-09 11:28:25 +00:00
|
|
|
## EXAMPLE USAGE - text only emails
|
2011-02-24 23:05:34 +00:00
|
|
|
|
2011-12-09 11:20:54 +00:00
|
|
|
```javascript
|
2020-05-01 19:47:39 +00:00
|
|
|
import { client as c } from 'emailjs';
|
|
|
|
|
|
|
|
|
|
const client = new c.Client({
|
|
|
|
|
user: 'user',
|
|
|
|
|
password: 'password',
|
|
|
|
|
host: 'smtp.your-email.com',
|
|
|
|
|
ssl: true
|
2011-12-09 11:20:54 +00:00
|
|
|
});
|
|
|
|
|
|
|
|
|
|
// send the message and get a callback with an error or details of the message that was sent
|
2020-05-01 19:47:39 +00:00
|
|
|
client.send({
|
|
|
|
|
text: 'i hope this works',
|
|
|
|
|
from: 'you <username@your-email.com>',
|
|
|
|
|
to: 'someone <someone@your-email.com>, another <another@your-email.com>',
|
|
|
|
|
cc: 'else <else@your-email.com>',
|
|
|
|
|
subject: 'testing emailjs'
|
|
|
|
|
}, (err, message) => {
|
|
|
|
|
console.log(err || message);
|
|
|
|
|
});
|
2011-12-09 11:20:54 +00:00
|
|
|
```
|
2011-02-24 23:05:34 +00:00
|
|
|
|
2011-12-09 11:28:25 +00:00
|
|
|
## EXAMPLE USAGE - html emails and attachments
|
2011-02-24 23:05:34 +00:00
|
|
|
|
2011-12-09 11:20:54 +00:00
|
|
|
```javascript
|
2020-05-01 19:47:39 +00:00
|
|
|
import { client as c } from 'emailjs';
|
|
|
|
|
|
|
|
|
|
const client = new c.Client({
|
|
|
|
|
user: 'user',
|
|
|
|
|
password: 'password',
|
|
|
|
|
host: 'smtp.your-email.com',
|
|
|
|
|
ssl: true
|
2011-12-09 11:20:54 +00:00
|
|
|
});
|
|
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
const message = {
|
|
|
|
|
text: 'i hope this works',
|
|
|
|
|
from: 'you <username@your-email.com>',
|
|
|
|
|
to: 'someone <someone@your-email.com>, another <another@your-email.com>',
|
|
|
|
|
cc: 'else <else@your-email.com>',
|
|
|
|
|
subject: 'testing emailjs',
|
|
|
|
|
attachment: [
|
|
|
|
|
{ data: '<html>i <i>hope</i> this works!</html>', alternative: true },
|
|
|
|
|
{ path: 'path/to/file.zip', type: 'application/zip', name: 'renamed.zip' }
|
|
|
|
|
]
|
2011-12-09 11:20:54 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
// send the message and get a callback with an error or details of the message that was sent
|
2020-05-01 19:47:39 +00:00
|
|
|
client.send(message, function(err, message) { console.log(err || message); });
|
2011-12-09 11:20:54 +00:00
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
// you can continue to send more messages with successive calls to 'client.send',
|
2011-12-09 11:20:54 +00:00
|
|
|
// they will be queued on the same smtp connection
|
|
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
// or instead of using the built-in client you can create an instance of 'SMTP.SMTPConnection'
|
2011-12-09 11:20:54 +00:00
|
|
|
```
|
2014-04-07 06:22:08 +00:00
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
## EXAMPLE USAGE - sending through outlook
|
2014-04-07 06:22:08 +00:00
|
|
|
|
|
|
|
|
```javascript
|
2020-05-01 19:47:39 +00:00
|
|
|
import { client as c, message as m } from 'emailjs';
|
|
|
|
|
|
|
|
|
|
const client = new c.Client({
|
|
|
|
|
user: 'user',
|
|
|
|
|
password: 'password',
|
|
|
|
|
host: 'smtp-mail.outlook.com',
|
|
|
|
|
tls: {
|
|
|
|
|
ciphers: 'SSLv3'
|
|
|
|
|
}
|
2014-04-07 06:22:08 +00:00
|
|
|
});
|
|
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
const message = new m.Message({
|
|
|
|
|
text: 'i hope this works',
|
|
|
|
|
from: 'you <username@outlook.com>',
|
|
|
|
|
to: 'someone <someone@your-email.com>, another <another@your-email.com>',
|
|
|
|
|
cc: 'else <else@your-email.com>',
|
|
|
|
|
subject: 'testing emailjs',
|
|
|
|
|
attachment: [
|
|
|
|
|
{ data: '<html>i <i>hope</i> this works!</html>', alternative: true },
|
|
|
|
|
{ path: 'path/to/file.zip', type: 'application/zip', name: 'renamed.zip' }
|
|
|
|
|
]
|
|
|
|
|
});
|
2014-04-07 06:22:08 +00:00
|
|
|
|
|
|
|
|
// send the message and get a callback with an error or details of the message that was sent
|
2020-05-01 19:47:39 +00:00
|
|
|
client.send(message, (err, message) => {
|
|
|
|
|
console.log(err || message);
|
|
|
|
|
});
|
2014-04-07 06:22:08 +00:00
|
|
|
```
|
|
|
|
|
|
2016-09-05 05:55:38 +00:00
|
|
|
## EXAMPLE USAGE - attaching and embedding an image
|
|
|
|
|
|
|
|
|
|
```javascript
|
2020-05-01 19:47:39 +00:00
|
|
|
import { client as c, message as m } from 'emailjs';
|
|
|
|
|
|
|
|
|
|
const client = new c.Client({
|
|
|
|
|
user: 'user',
|
|
|
|
|
password: 'password',
|
|
|
|
|
host: 'smtp-mail.outlook.com',
|
|
|
|
|
tls: {
|
|
|
|
|
ciphers: 'SSLv3'
|
|
|
|
|
}
|
2016-09-05 05:55:38 +00:00
|
|
|
});
|
|
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
const message = new m.Message({
|
|
|
|
|
text: 'i hope this works',
|
|
|
|
|
from: 'you <username@outlook.com>',
|
|
|
|
|
to: 'someone <someone@your-email.com>, another <another@your-email.com>',
|
|
|
|
|
cc: 'else <else@your-email.com>',
|
|
|
|
|
subject: 'testing emailjs',
|
|
|
|
|
attachment: [
|
|
|
|
|
{ data: '<html>i <i>hope</i> this works! here is an image: <img src="cid:my-image" width="100" height ="50"> </html>' },
|
|
|
|
|
{ path: 'path/to/file.zip', type: 'application/zip', name: 'renamed.zip' },
|
|
|
|
|
{ path: 'path/to/image.jpg', type: 'image/jpg', headers: { 'Content-ID': '<my-image>' } }
|
|
|
|
|
]
|
|
|
|
|
});
|
2016-09-05 05:55:38 +00:00
|
|
|
|
|
|
|
|
// send the message and get a callback with an error or details of the message that was sent
|
2020-05-01 19:47:39 +00:00
|
|
|
client.send(message, (err, message) => {
|
|
|
|
|
console.log(err || message);
|
|
|
|
|
});
|
2016-09-05 05:55:38 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
2018-07-12 18:57:38 +00:00
|
|
|
# API
|
2011-02-24 23:02:24 +00:00
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
## new client.Client(options)
|
2011-02-24 23:02:24 +00:00
|
|
|
|
|
|
|
|
// options is an object with the following keys
|
|
|
|
|
options =
|
|
|
|
|
{
|
2018-07-12 18:57:38 +00:00
|
|
|
user // username for logging into smtp
|
2011-02-24 23:02:24 +00:00
|
|
|
password // password for logging into smtp
|
|
|
|
|
host // smtp host
|
|
|
|
|
port // smtp port (if null a standard port number will be used)
|
2014-04-07 06:22:08 +00:00
|
|
|
ssl // boolean or object {key, ca, cert} (if true or object, ssl connection will be made)
|
|
|
|
|
tls // boolean or object (if true or object, starttls will be initiated)
|
2011-02-24 23:02:24 +00:00
|
|
|
timeout // max number of milliseconds to wait for smtp responses (defaults to 5000)
|
|
|
|
|
domain // domain to greet smtp with (defaults to os.hostname)
|
2017-07-16 17:07:59 +00:00
|
|
|
authentication // array of preferred authentication methods ('PLAIN', 'LOGIN', 'CRAM-MD5', 'XOAUTH2')
|
2018-07-12 18:57:38 +00:00
|
|
|
logger // override the built-in logger (useful for e.g. Azure Function Apps, where console.log doesn't work)
|
2011-02-24 23:02:24 +00:00
|
|
|
}
|
2018-07-12 18:57:38 +00:00
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
## client.Client#send(message, callback)
|
2018-07-12 18:57:38 +00:00
|
|
|
|
2011-02-24 23:02:24 +00:00
|
|
|
// message can be a smtp.Message (as returned by email.message.create)
|
|
|
|
|
// or an object identical to the first argument accepted by email.message.create
|
|
|
|
|
|
|
|
|
|
// callback will be executed with (err, message)
|
|
|
|
|
// either when message is sent or an error has occurred
|
|
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
## new message.Message(headers)
|
2011-02-24 23:02:24 +00:00
|
|
|
|
2011-12-09 10:57:52 +00:00
|
|
|
// headers is an object ('from' and 'to' are required)
|
|
|
|
|
// returns a Message object
|
|
|
|
|
|
|
|
|
|
// you can actually pass more message headers than listed, the below are just the
|
|
|
|
|
// most common ones you would want to use
|
|
|
|
|
|
|
|
|
|
headers =
|
|
|
|
|
{
|
2018-07-12 18:57:38 +00:00
|
|
|
text // text of the email
|
2011-12-09 10:57:52 +00:00
|
|
|
from // sender of the format (address or name <address> or "name" <address>)
|
|
|
|
|
to // recipients (same format as above), multiple recipients are separated by a comma
|
|
|
|
|
cc // carbon copied recipients (same format as above)
|
|
|
|
|
bcc // blind carbon copied recipients (same format as above)
|
|
|
|
|
subject // string subject of the email
|
2012-05-28 09:59:31 +00:00
|
|
|
attachment // one attachment or array of attachments
|
2011-12-09 10:57:52 +00:00
|
|
|
}
|
2011-02-24 23:02:24 +00:00
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
## message.Message#attach
|
2011-02-24 23:02:24 +00:00
|
|
|
|
2011-12-09 10:57:52 +00:00
|
|
|
// can be called multiple times, each adding a new attachment
|
|
|
|
|
// options is an object with the following possible keys:
|
2018-07-12 18:57:38 +00:00
|
|
|
|
2011-12-09 10:57:52 +00:00
|
|
|
options =
|
|
|
|
|
{
|
|
|
|
|
// one of these fields is required
|
|
|
|
|
path // string to where the file is located
|
|
|
|
|
data // string of the data you want to attach
|
|
|
|
|
stream // binary stream that will provide attachment data (make sure it is in the paused state)
|
|
|
|
|
// better performance for binary streams is achieved if buffer.length % (76*6) == 0
|
|
|
|
|
// current max size of buffer must be no larger than Message.BUFFERSIZE
|
2018-07-12 18:57:38 +00:00
|
|
|
|
2011-12-09 10:57:52 +00:00
|
|
|
// optionally these fields are also accepted
|
|
|
|
|
type // string of the file mime type
|
|
|
|
|
name // name to give the file as perceived by the recipient
|
2014-10-04 20:47:55 +00:00
|
|
|
charset // charset to encode attatchment in
|
|
|
|
|
method // method to send attachment as (used by calendar invites)
|
2011-12-09 10:57:52 +00:00
|
|
|
alternative // if true, will be attached inline as an alternative (also defaults type='text/html')
|
|
|
|
|
inline // if true, will be attached inline
|
|
|
|
|
encoded // set this to true if the data is already base64 encoded, (avoid this if possible)
|
|
|
|
|
headers // object containing header=>value pairs for inclusion in this attachment's header
|
2012-03-28 16:12:33 +00:00
|
|
|
related // an array of attachments that you want to be related to the parent attachment
|
2011-12-09 10:57:52 +00:00
|
|
|
}
|
2018-07-12 18:57:38 +00:00
|
|
|
|
2020-05-01 19:47:39 +00:00
|
|
|
## new SMTP.SMTPConnection(options)
|
|
|
|
|
|
|
|
|
|
// options is an object with the following keys
|
|
|
|
|
options =
|
|
|
|
|
{
|
|
|
|
|
user // username for logging into smtp
|
|
|
|
|
password // password for logging into smtp
|
|
|
|
|
host // smtp host
|
|
|
|
|
port // smtp port (if null a standard port number will be used)
|
|
|
|
|
ssl // boolean or object {key, ca, cert} (if true or object, ssl connection will be made)
|
|
|
|
|
tls // boolean or object (if true or object, starttls will be initiated)
|
|
|
|
|
timeout // max number of milliseconds to wait for smtp responses (defaults to 5000)
|
|
|
|
|
domain // domain to greet smtp with (defaults to os.hostname)
|
|
|
|
|
authentication // array of preferred authentication methods ('PLAIN', 'LOGIN', 'CRAM-MD5', 'XOAUTH2')
|
|
|
|
|
logger // override the built-in logger (useful for e.g. Azure Function Apps, where console.log doesn't work)
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
## SMTP.SMTPConnection#authentication
|
|
|
|
|
|
|
|
|
|
associative array of currently supported SMTP authentication mechanisms
|
|
|
|
|
|
2011-02-23 21:23:37 +00:00
|
|
|
## Authors
|
|
|
|
|
|
|
|
|
|
eleith
|
2018-08-06 18:58:41 +00:00
|
|
|
zackschuster
|
2011-12-09 10:28:38 +00:00
|
|
|
|
|
|
|
|
## Testing
|
|
|
|
|
|
2011-12-09 11:24:36 +00:00
|
|
|
npm install -d
|
|
|
|
|
npm test
|
2011-12-09 10:28:38 +00:00
|
|
|
|
|
|
|
|
## Contributions
|
|
|
|
|
|
|
|
|
|
issues and pull requests are welcome
|
