mirror of https://github.com/eleith/emailjs.git
chore: lint readme
This commit is contained in:
parent
2ce27a2b9b
commit
7344c5bd27
189
Readme.md
189
Readme.md
|
@ -4,19 +4,21 @@ send emails, html and attachments (files, streams and strings) from node.js to a
|
|||
|
||||
## INSTALLING
|
||||
|
||||
npm install emailjs
|
||||
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
|
||||
|
||||
- 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
|
||||
|
||||
## REQUIRES
|
||||
- auth access to an SMTP Server
|
||||
- if your service (ex: gmail) uses two-step authentication, use an application specific password
|
||||
|
||||
- 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
|
||||
|
||||
|
@ -27,19 +29,22 @@ const client = new c.Client({
|
|||
user: 'user',
|
||||
password: 'password',
|
||||
host: 'smtp.your-email.com',
|
||||
ssl: true
|
||||
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 <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);
|
||||
});
|
||||
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);
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
## EXAMPLE USAGE - html emails and attachments
|
||||
|
@ -47,14 +52,14 @@ client.send({
|
|||
```javascript
|
||||
import { client as c } from 'emailjs';
|
||||
|
||||
const client = new c.Client({
|
||||
const client = new c.Client({
|
||||
user: 'user',
|
||||
password: 'password',
|
||||
host: 'smtp.your-email.com',
|
||||
ssl: true
|
||||
ssl: true,
|
||||
});
|
||||
|
||||
const message = {
|
||||
const message = {
|
||||
text: 'i hope this works',
|
||||
from: 'you <username@your-email.com>',
|
||||
to: 'someone <someone@your-email.com>, another <another@your-email.com>',
|
||||
|
@ -62,12 +67,14 @@ const message = {
|
|||
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' }
|
||||
]
|
||||
{ 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); });
|
||||
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
|
||||
|
@ -80,25 +87,25 @@ client.send(message, function(err, message) { console.log(err || message); });
|
|||
```javascript
|
||||
import { client as c, message as m } from 'emailjs';
|
||||
|
||||
const client = new c.Client({
|
||||
const client = new c.Client({
|
||||
user: 'user',
|
||||
password: 'password',
|
||||
host: 'smtp-mail.outlook.com',
|
||||
tls: {
|
||||
ciphers: 'SSLv3'
|
||||
}
|
||||
ciphers: 'SSLv3',
|
||||
},
|
||||
});
|
||||
|
||||
const message = new m.Message({
|
||||
text: 'i hope this works',
|
||||
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' }
|
||||
]
|
||||
{ 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
|
||||
|
@ -112,26 +119,33 @@ client.send(message, (err, message) => {
|
|||
```javascript
|
||||
import { client as c, message as m } from 'emailjs';
|
||||
|
||||
const client = new c.Client({
|
||||
const client = new c.Client({
|
||||
user: 'user',
|
||||
password: 'password',
|
||||
host: 'smtp-mail.outlook.com',
|
||||
tls: {
|
||||
ciphers: 'SSLv3'
|
||||
}
|
||||
ciphers: 'SSLv3',
|
||||
},
|
||||
});
|
||||
|
||||
const message = new m.Message({
|
||||
text: 'i hope this works',
|
||||
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>' },
|
||||
{
|
||||
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>' } }
|
||||
]
|
||||
{
|
||||
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
|
||||
|
@ -140,57 +154,56 @@ client.send(message, (err, message) => {
|
|||
});
|
||||
```
|
||||
|
||||
|
||||
# API
|
||||
|
||||
## new client.Client(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)
|
||||
// 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)
|
||||
}
|
||||
logger // override the built-in logger (useful for e.g. Azure Function Apps, where console.log doesn't work)
|
||||
}
|
||||
|
||||
## client.Client#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
|
||||
// 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
|
||||
// callback will be executed with (err, message)
|
||||
// either when message is sent or an error has occurred
|
||||
|
||||
## new message.Message(headers)
|
||||
|
||||
// headers is an object ('from' and 'to' are required)
|
||||
// returns a Message object
|
||||
// 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
|
||||
// you can actually pass more message headers than listed, the below are just the
|
||||
// most common ones you would want to use
|
||||
|
||||
headers =
|
||||
{
|
||||
text // text of the email
|
||||
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
|
||||
headers =
|
||||
{
|
||||
text // text of the email
|
||||
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
|
||||
attachment // one attachment or array of attachments
|
||||
}
|
||||
}
|
||||
|
||||
## message.Message#attach
|
||||
|
||||
// can be called multiple times, each adding a new attachment
|
||||
// options is an object with the following possible keys:
|
||||
// can be called multiple times, each adding a new attachment
|
||||
// options is an object with the following possible keys:
|
||||
|
||||
options =
|
||||
{
|
||||
|
@ -215,20 +228,20 @@ client.send(message, (err, message) => {
|
|||
|
||||
## 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)
|
||||
// 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)
|
||||
}
|
||||
logger // override the built-in logger (useful for e.g. Azure Function Apps, where console.log doesn't work)
|
||||
}
|
||||
|
||||
## smtp.SMTPConnection#authentication
|
||||
|
||||
|
@ -241,8 +254,8 @@ zackschuster
|
|||
|
||||
## Testing
|
||||
|
||||
npm install -d
|
||||
npm test
|
||||
npm install -d
|
||||
npm test
|
||||
|
||||
## Contributions
|
||||
|
||||
|
|
Loading…
Reference in New Issue