Emails module for Mono

Installation

npm install --save mono-mail

Then, in your configuration file of your Mono application (example: conf/application.js):

module.exports = {
  mono: {
    modules: ['mono-mail']
  }
}

Configuration

mono-mail will use the mono.mail property of your configuration (example: conf/development.js):

module.exports = {
  mono: {
    mail: {
      // Optional, if not provided, only preview will be available
      provider: {
        name: 'smtp || ses',
        ... // Provider conf
      },
      // Sender email adress (required)
      from: 'mono-mail@terrajs.org',
      // Enabled by default on development
      exposeRoutes: true
    }
  }
}

Providers

Mono mail is currently supporting two providers to send your email:

• SMTP provider, using nodemailer with the nodemailer-smtp-transport transport
• SES Amazon, using nodemail with the nodemailer-ses-transport transport.

If no provider is provided the library will remove the /mails/send route and the send method.

Usage

Mono mail is a mono module that using mjml and handlebar to generate and send awesome mails.

const monoMail = require('mono-mail')

Mono mail also expose some methods as REST routes

TODO: All rest calls need a session and a role that contain manageMail action. This action is not added automatically.

Routes

The routes for preview and sending an email are only available on development environment or if the exposeRoutes is set to true in the configuration of the module.

Test preview route

Run the mono server with mono-mail:

NODE_ENV=test npx mono dev test/fixture/ok/

Once the server launched go to this url

Roadmap

• Add attachment MINE Type in HTTP POST route

Exposed routes

Method	URI	Query params	Body	Action
GET	/mails/preview	path, data, pathType		Return HTML Generated mail
POST	/mails/send	pathType	path, data, to, subject	Send email

Query params:

• pathType?: String (relative or absolute) Relative from current mono instance dirname

Post/Query params:

• path: String. Path to the mail file
• data: Object. Data object that will be compiled by handlebar

Post params:

• subject: String (compiled with handlebar). Subject of the mail
• to: String. Email adress of the sender

Methods

registerPartial

registerPartial(partialName = String, partialPathmail = String): Promise<void>

Register new partial template to be used inside mail template

Arguments:

• partialName: String. Partial name key
• partialPathmail: String. Path of the partial template

// Register new partial
const template = await monoMail.registerPartial('font-footer', join(__dirname, 'modules/mails/font-footer.html'))

generate

generate(mail = { path, data, subject }): Promise<String>

Generate HTML template from mail object.

Arguments:

• path: String. Path to the mail file
• data: Object. Data object that will be compiled by handlebar
• subject: String (compiled with handlebar). Subject of the mail

// Generate template mail in HTML
const template = await monoMail.generate({
  subject: 'Hello, {{ firstName }}',
  path: join(__dirname, 'modules/users/signup.html'),
  data: {
    title: 'Welcome to mono-mail',
    description: 'Mono module using mjml and handlebar to generate awesome template mail and send it to your customers'
  }
})

send

send(mail = { path, data, subject, bcc, to, attachments: [{ filename, path, contentType }] }): Promise<void>

Generate HTML template from mail object.

Arguments:

• bcc: String. Blind Carbon Copy email
• to: String. Recipient email address
• attachments: Array<{ filename, path, contentType }>. Attachment to the mail

// Send email to recipient@terrajs.io recipient
const template = await monoMail.generate({
  subject: 'Hello, {{ firstName }}',
  path: join(__dirname, 'modules/users/signup.html'),
  bcc: 'copy@terrajs.io',
  to: 'recipient@terrajs.io',
  data: {
    title: 'Welcome to mono-mail',
    description: 'Mono module using mjml and handlebar to generate awesome template mail and send it to your customers'
  }
})

Development / Contribution

See the contribution guidelines of this project.

License

MIT © gaetansenn