2020-09-04 05:22:45 +00:00
# emailjs [](https://github.com/eleith/emailjs/actions?query=workflow%3A.github%2Fworkflows%2Ftest.yml) [](https://github.com/eleith/emailjs/actions?query=workflow%3A.github%2Fworkflows%2Flint.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
2022-05-06 20:06:53 +00:00
```console
$ npm install emailjs # or yarn, pnpm, etc.
```
2011-02-23 21:23:37 +00:00
2011-12-09 11:28:25 +00:00
## FEATURES
2020-05-26 07:03:53 +00:00
- works with SSL and TLS smtp servers
- supports smtp authentication ('PLAIN', 'LOGIN', 'CRAM-MD5', 'XOAUTH2')
- emails are queued and the queue is sent asynchronously
- supports sending html emails and emails with multiple attachments (MIME)
- attachments can be added as strings, streams or file paths
- supports utf-8 headers and body
2020-06-13 00:16:50 +00:00
- built-in type declarations
2020-07-26 01:44:33 +00:00
- automatically handles [greylisting ](http://projects.puremagic.com/greylisting/whitepaper.html )
2011-02-23 21:23:37 +00:00
2011-12-09 11:28:25 +00:00
## REQUIRES
2020-05-26 07:03:53 +00:00
- auth access to an SMTP Server
- if your service (ex: gmail) uses two-step authentication, use an application specific password
2011-02-23 21:23:37 +00:00
2022-05-06 20:06:53 +00:00
## DEVELOPMENT
issues and pull requests are welcome!
### Setup
#### node 14+
```console
$ corepack enable yarn # if necessary to install or update
$ yarn
```
#### node 12
```console
$ npm install --global yarn # if necessary to install or update; see https://classic.yarnpkg.com/en/docs/install
$ yarn
```
### Testing
```console
$ yarn test
```
2011-12-09 11:28:25 +00:00
## EXAMPLE USAGE - text only emails
2011-02-24 23:05:34 +00:00
2020-05-26 07:40:39 +00:00
```js
2020-05-27 18:15:55 +00:00
import { SMTPClient } from 'emailjs';
2020-05-01 19:47:39 +00:00
2020-05-27 18:15:55 +00:00
const client = new SMTPClient({
2020-05-01 19:47:39 +00:00
user: 'user',
password: 'password',
host: 'smtp.your-email.com',
2020-05-26 07:03:53 +00:00
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-26 07:03:53 +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
2020-12-01 23:20:43 +00:00
## EXAMPLE USAGE - using async/await
```js
// assuming top-level await for brevity
import { SMTPClient } from 'emailjs';
const client = new SMTPClient({
user: 'user',
password: 'password',
host: 'smtp.your-email.com',
ssl: true,
});
try {
const message = await client.sendAsync({
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',
});
console.log(message);
} catch (err) {
console.error(err);
}
```
2011-12-09 11:28:25 +00:00
## EXAMPLE USAGE - html emails and attachments
2011-02-24 23:05:34 +00:00
2020-05-26 07:40:39 +00:00
```js
2020-05-27 18:15:55 +00:00
import { SMTPClient } from 'emailjs';
2020-05-01 19:47:39 +00:00
2020-05-27 18:15:55 +00:00
const client = new SMTPClient({
2020-05-01 19:47:39 +00:00
user: 'user',
password: 'password',
host: 'smtp.your-email.com',
2020-05-26 07:03:53 +00:00
ssl: true,
2011-12-09 11:20:54 +00:00
});
2020-05-26 07:03:53 +00:00
const message = {
2020-05-01 19:47:39 +00:00
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 },
2020-05-26 07:03:53 +00:00
{ 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-26 07:03:53 +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 20:17:50 +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
2020-05-26 07:40:39 +00:00
```js
2020-05-27 18:15:55 +00:00
import { SMTPClient, Message } from 'emailjs';
2020-05-01 19:47:39 +00:00
2020-05-27 18:15:55 +00:00
const client = new SMTPClient({
2020-05-01 19:47:39 +00:00
user: 'user',
password: 'password',
host: 'smtp-mail.outlook.com',
tls: {
2020-05-26 07:03:53 +00:00
ciphers: 'SSLv3',
},
2014-04-07 06:22:08 +00:00
});
2020-05-27 12:40:34 +00:00
const message = new Message({
2020-05-26 07:03:53 +00:00
text: 'i hope this works',
2020-05-01 19:47:39 +00:00
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 },
2020-05-26 07:03:53 +00:00
{ path: 'path/to/file.zip', type: 'application/zip', name: 'renamed.zip' },
],
2020-05-01 19:47:39 +00:00
});
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
2020-05-26 07:40:39 +00:00
```js
2020-05-27 18:15:55 +00:00
import { SMTPClient, Message } from 'emailjs';
2020-05-01 19:47:39 +00:00
2020-05-27 18:15:55 +00:00
const client = new SMTPClient({
2020-05-01 19:47:39 +00:00
user: 'user',
password: 'password',
host: 'smtp-mail.outlook.com',
tls: {
2020-05-26 07:03:53 +00:00
ciphers: 'SSLv3',
},
2016-09-05 05:55:38 +00:00
});
2020-05-27 12:40:34 +00:00
const message = new Message({
2020-05-26 07:03:53 +00:00
text: 'i hope this works',
2020-05-01 19:47:39 +00:00
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: [
2020-05-26 07:03:53 +00:00
{
data:
'< html > i < i > hope< / i > this works! here is an image: < img src = "cid:my-image" width = "100" height = "50" > < / html > ',
},
2020-05-01 19:47:39 +00:00
{ path: 'path/to/file.zip', type: 'application/zip', name: 'renamed.zip' },
2020-05-26 07:03:53 +00:00
{
path: 'path/to/image.jpg',
type: 'image/jpg',
headers: { 'Content-ID': '< my-image > ' },
},
],
2020-05-01 19:47:39 +00:00
});
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-27 18:15:55 +00:00
## new SMTPClient(options)
2011-02-24 23:02:24 +00:00
2020-05-26 07:40:39 +00:00
```js
// options is an object with the following recognized schema:
const options = {
user, // username for logging into smtp
password, // password for logging into smtp
2020-05-26 14:29:15 +00:00
host, // smtp host (defaults to 'localhost')
port, // smtp port (defaults to 25 for unencrypted, 465 for `ssl` , and 587 for `tls` )
2020-05-30 16:58:55 +00:00
ssl, // boolean or object (if true or object, ssl connection will be made)
2020-05-26 07:40:39 +00:00
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)
};
2020-05-30 16:58:55 +00:00
// ssl/tls objects are an abbreviated form of [`tls.connect` ](https://nodejs.org/dist/latest-v14.x/docs/api/tls.html#tls_tls_connect_options_callback )'s options
// the missing items are: `port` , `host` , `path` , `socket` , `timeout` and `secureContext`
2020-05-26 15:04:55 +00:00
// NOTE: `host` is trimmed before being used to establish a connection;
2020-05-26 14:29:15 +00:00
// however, the original untrimmed value will still be visible in configuration.
2020-05-26 07:40:39 +00:00
```
2018-07-12 18:57:38 +00:00
2020-05-27 18:15:55 +00:00
## SMTPClient#send(message, callback)
2018-07-12 18:57:38 +00:00
2020-05-26 07:40:39 +00:00
```js
// 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
2011-02-24 23:02:24 +00:00
2020-05-26 07:40:39 +00:00
// callback will be executed with (err, message)
// either when message is sent or an error has occurred
```
2011-02-24 23:02:24 +00:00
2020-05-27 12:40:34 +00:00
## new Message(headers)
2011-02-24 23:02:24 +00:00
2020-05-26 07:40:39 +00:00
```js
2020-05-27 05:47:24 +00:00
// headers is an object with the following recognized schema:
2020-05-26 07:40:39 +00:00
const headers = {
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)
2020-05-27 05:47:24 +00:00
text, // text of the email
2020-05-26 07:40:39 +00:00
subject, // string subject of the email
attachment, // one attachment or array of attachments
};
2020-05-27 05:47:24 +00:00
// the `from` field is required.
// at least one `to` , `cc` , or `bcc` header is also required.
2020-05-26 07:40:39 +00:00
// you can also add whatever other headers you want.
```
2011-02-24 23:02:24 +00:00
2020-05-27 12:40:34 +00:00
## Message#attach(options)
2011-02-24 23:02:24 +00:00
2020-05-26 07:40:39 +00:00
Can be called multiple times, each adding a new attachment.
```js
// options is an object with the following recognized schema:
const 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
// optionally these fields are also accepted
type, // string of the file mime type
name, // name to give the file as perceived by the recipient
charset, // charset to encode attatchment in
method, // method to send attachment as (used by calendar invites)
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
related, // an array of attachments that you want to be related to the parent attachment
};
```
2018-07-12 18:57:38 +00:00
2021-09-03 22:22:47 +00:00
## Message#checkValidity()
Synchronously validate that a Message is properly formed.
```js
const message = new Message(options);
const { isValid, validationError } = message.checkValidity();
if (isValid) {
// ...
} else {
// first error encountered
console.error(validationError);
}
```
2020-05-27 12:40:34 +00:00
## new SMTPConnection(options={})
2020-05-01 19:47:39 +00:00
2020-05-26 07:40:39 +00:00
```js
// options is an object with the following recognized schema:
const options = {
user, // username for logging into smtp
password, // password for logging into smtp
host, // smtp host (defaults to 'localhost')
port, // smtp port (defaults to 25 for unencrypted, 465 for `ssl` , and 587 for `tls` )
2020-05-30 16:58:55 +00:00
ssl, // boolean or object (if true or object, ssl connection will be made)
2020-05-26 07:40:39 +00:00
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)
};
2020-05-30 16:58:55 +00:00
// ssl/tls objects are an abbreviated form of [`tls.connect` ](https://nodejs.org/dist/latest-v14.x/docs/api/tls.html#tls_tls_connect_options_callback )'s options
// the missing items are: `port` , `host` , `path` , `socket` , `timeout` and `secureContext`
2020-05-26 15:04:55 +00:00
// NOTE: `host` is trimmed before being used to establish a connection;
2020-05-26 14:29:15 +00:00
// however, the original untrimmed value will still be visible in configuration.
2020-05-26 07:40:39 +00:00
```
2020-05-01 19:47:39 +00:00
2020-05-26 07:12:25 +00:00
To target a Message Transfer Agent (MTA), omit all options.
2020-05-27 12:40:34 +00:00
## SMTPConnection#authentication
2020-05-01 19:47:39 +00:00
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
