Mail-monkey NPM

mail-monkey

Plugin to simplify the mailing process with the help of MJML and Handlebars

Installation

npm install --save mail-monkey

Usage

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:

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:

MailMonkey.config({
  /* Your config */
})

The following props are available for configuration:

provider

Sets the mail provider. At the moment only Sendgrid is implemented but you can implement custom providers with the addProvider method (see below).

It should look like this:

MailMonkey.config({
  provider: {
    name: 'Sendgrid',
    key: 'abc', //Your Sendgrid API Key
  },
})

How to add your own provider

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():

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)

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:

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

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:

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 is supported.

It should look like this:

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. :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.