Skip to content

Latest commit

 

History

History
320 lines (262 loc) · 10.3 KB

README.md

File metadata and controls

320 lines (262 loc) · 10.3 KB

emailjs Test Status Lint Status

send emails, html and attachments (files, streams and strings) from node.js to any smtp server

INSTALLING

npm install emailjs

FEATURES

  • 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
  • built-in type declarations
  • automatically handles greylisting

REQUIRES

  • auth access to an SMTP Server
  • if your service (ex: gmail) uses two-step authentication, use an application specific password

EXAMPLE USAGE - text only emails

import { SMTPClient } from 'emailjs';

const client = new SMTPClient({
	user: 'user',
	password: 'password',
	host: 'smtp.your-email.com',
	ssl: true,
});

// send the message and get a callback with an error or details of the message that was sent
client.send(
	{
		text: 'i hope this works',
		from: 'you <[email protected]>',
		to: 'someone <[email protected]>, another <[email protected]>',
		cc: 'else <[email protected]>',
		subject: 'testing emailjs',
	},
	(err, message) => {
		console.log(err || message);
	}
);

EXAMPLE USAGE - using async/await

// 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 <[email protected]>',
		to: 'someone <[email protected]>, another <[email protected]>',
		cc: 'else <[email protected]>',
		subject: 'testing emailjs',
	});
	console.log(message);
} catch (err) {
	console.error(err);
}

EXAMPLE USAGE - html emails and attachments

import { SMTPClient } from 'emailjs';

const client = new SMTPClient({
	user: 'user',
	password: 'password',
	host: 'smtp.your-email.com',
	ssl: true,
});

const message = {
	text: 'i hope this works',
	from: 'you <[email protected]>',
	to: 'someone <[email protected]>, another <[email protected]>',
	cc: 'else <[email protected]>',
	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' },
	],
};

// send the message and get a callback with an error or details of the message that was sent
client.send(message, function (err, message) {
	console.log(err || message);
});

// you can continue to send more messages with successive calls to 'client.send',
// they will be queued on the same smtp connection

// or instead of using the built-in client you can create an instance of 'smtp.SMTPConnection'

EXAMPLE USAGE - sending through outlook

import { SMTPClient, Message } from 'emailjs';

const client = new SMTPClient({
	user: 'user',
	password: 'password',
	host: 'smtp-mail.outlook.com',
	tls: {
		ciphers: 'SSLv3',
	},
});

const message = new Message({
	text: 'i hope this works',
	from: 'you <[email protected]>',
	to: 'someone <[email protected]>, another <[email protected]>',
	cc: 'else <[email protected]>',
	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' },
	],
});

// send the message and get a callback with an error or details of the message that was sent
client.send(message, (err, message) => {
	console.log(err || message);
});

EXAMPLE USAGE - attaching and embedding an image

import { SMTPClient, Message } from 'emailjs';

const client = new SMTPClient({
	user: 'user',
	password: 'password',
	host: 'smtp-mail.outlook.com',
	tls: {
		ciphers: 'SSLv3',
	},
});

const message = new Message({
	text: 'i hope this works',
	from: 'you <[email protected]>',
	to: 'someone <[email protected]>, another <[email protected]>',
	cc: 'else <[email protected]>',
	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>' },
		},
	],
});

// send the message and get a callback with an error or details of the message that was sent
client.send(message, (err, message) => {
	console.log(err || message);
});

API

new SMTPClient(options)

// 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`)
	ssl, // boolean or object (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)
};
// 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`
// NOTE: `host` is trimmed before being used to establish a connection;
// however, the original untrimmed value will still be visible in configuration.

SMTPClient#send(message, callback)

// 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

new Message(headers)

// headers is an object with the following recognized schema:
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)
	text, // text of the email
	subject, // string subject of the email
	attachment, // one attachment or array of attachments
};
// the `from` field is required.
// at least one `to`, `cc`, or `bcc` header is also required.
// you can also add whatever other headers you want.

Message#attach(options)

Can be called multiple times, each adding a new attachment.

// 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
};

Message#checkValidity()

Synchronously validate that a Message is properly formed.

const message = new Message(options);
const { isValid, validationError } = message.checkValidity();
if (isValid) {
	// ...
} else {
	// first error encountered
	console.error(validationError);
}

new SMTPConnection(options={})

// 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`)
	ssl, // boolean or object (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)
};
// 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`
// NOTE: `host` is trimmed before being used to establish a connection;
// however, the original untrimmed value will still be visible in configuration.

To target a Message Transfer Agent (MTA), omit all options.

SMTPConnection#authentication

associative array of currently supported SMTP authentication mechanisms

Authors

eleith zackschuster

Testing

npm install -d
npm test

Contributions

issues and pull requests are welcome