mail-monkey
Version:
[](https://travis-ci.org/ElderAS/mail-monkey) [](https://www.npmjs.com/package/mail-monkey
215 lines (160 loc) • 4.91 kB
Markdown
# mail-monkey
[](https://travis-ci.org/ElderAS/mail-monkey)
[](https://www.npmjs.com/package/mail-monkey)
[](https://www.npmjs.com/package/mail-monkey)
Plugin to simplify the mailing process with the help of [MJML](https://mjml.io/) and [Handlebars](https://handlebarsjs.com/)
### Installation
`npm install --save mail-monkey`
### Usage
```js
const MailMonkey = require('mail-monkey')
/* This is the most simplest configuration, check out the docs for more features */
MailMonkey.config({
templateDir: 'YOURTEMPLATEFOLDER',
provider: {
name: 'Sendgrid',
key: 'YOURAPIKEY',
},
})
```
After you've configured `MailMonkey` you are ready to send off your mails, like this:
```js
const MailMonkey = require('mail-monkey')
/* Assuming you have a template called Confirmation */
MailMonkey.Confirmation({
to: 'who@ever.org',
from: 'me@ofcourse.com',
subject: 'Check this out!',
data: {
name: 'Awesome...',
},
attachments: [
/* You get it ;) */
],
})
```
### Config
You can configurate `MailMonkey` anytime by calling:
```js
MailMonkey.config({
/* Your config */
})
```
The following props are available for configuration:
#### provider
Sets the mail provider. At the moment only [Sendgrid](https://sendgrid.com/) is implemented but you can implement custom providers with the `addProvider` method (see below).
It should look like this:
```js
MailMonkey.config({
provider: {
name: 'Sendgrid',
key: 'abc', //Your Sendgrid API Key
},
})
```
**How to add your own provider**
```js
MailMonkey.addProvider('YOUR_PROVIDER_NAME', function(options) {
//options is the object passed in with the provider property when calling .config()
return {
send(data) {
//Send email with custom setup and return Promise
},
}
})
```
And after adding your custom provider you can use it in `.config()`:
```js
MailMonkey.config({
provider: {
name: 'YOUR_PROVIDER_NAME',
//Pass in anything you need to initialize
},
})
```
#### mailSettings
Set default settings for mail delivery.
Currently only sender is implemented. (more will come, feel free to send PR)
```js
MailMonkey.config({
mailSettings: {
sender: {
email: '...', //All emails will use this address as sender, unless from is passed to mail function
},
},
})
```
#### handlebars
Sometimes you need more features like helpers or partials.
You can do this with `configure`.
It should look like this:
```js
MailMonkey.config({
handlebars: {
configure: function(hb) {
// Modify Handlebars instance (hb) here...
},
},
})
```
#### templateDir
This is the path to you template directory. `MailMonkey` will read all files ending with `.mjml` and make them available. (CamelCase)
Example:
```
templates
- Confirmation.mjml --> MailMonkey.Confirmation
- sign-up.mjml --> MailMonkey.SignUp
- recover.mjml --> MailMonkey.Recover
```
```js
MailMonkey.config({
templateDir: '/mail/templates',
})
```
#### defaultData
If you have data that should be available in all templates you can provide it via `defaultData`.
Usually stuff like logo url etc.
It should look like this:
```js
MailMonkey.config({
defaultData: {
company: {
name: 'Elder AS',
},
logo: 'path...',
},
})
```
#### server
If you would like to make your emails available at a given url you can solve it via `server`.
Currently only [Express](https://expressjs.com/) is supported.
It should look like this:
```js
MailMonkey.config({
server: {
instance: EXPRESSAPP,
endpoint: '/mail', //All emails are available at /mail/TEMPLATENAME
resolver: function(req) {
//OPTIONAL
//Write your custom data resolver here
//This function should return your template data (async as Promise or sync Object)
//DEFAULT: returns req.query
},
},
})
```
`server.endpoint` uses the same syntax as [Express](https://expressjs.com/). `:template` is reserved by `mail-monkey` and will be appended to your endpoint config if it isn't present.
**Examples (template name is "confirmation")**
```
endpoint: '/mail' -> available @ /mail/confirmation
endpoint: '/' -> available @ /confirmation
endpoint: '/mail/:template/:YOURID' -> available @ /mail/confirmation/YOURID
endpoint: '/mail/:YOURID/:template' -> available @ /mail/YOURID/confirmation
```
`server.resolver` can be used to resolve data you want to have accessible in your template. By default it returns QueryStrings via `req.query`.
#### debug
You can enable logging by setting `debug` to true
## License
[The MIT License](http://opensource.org/licenses/MIT)
Copyright (c) Carsten Jacobsen