Loopback-component-mailer NPM

loopback-component-mailer

This component adds a mailer to loopback. Templating is done with handlebars. The queue is handled by kue/redis. The sole transport is currently sendgrid, but the module is built to be easily extendable.

Requirements

Redis >= 2.6.12

Usage

Installation

Install in you loopback project:
npm install --save loopback-component-mailer
Create a component-config.json file in your server folder (if you don't already have one)
Configure options inside component-config.json. (see configuration section)
```
{
  "loopback-component-mailer": {
    "{option}": "{value}"
  }
}
```
Create a folder for storing templates.
The default location is /server/mailer/templates. This can be set in component-config.json (see below)

Configuration

Options:

templatePath
String : The location of of the email templates relative to the project root. (default: '/server/mailer/templates/')
namespace
String : The name used for attaching to the loopback app object. (default: 'mailer')
redis
Object : Config for connection to redis server. (default: { host: 127.0.0.1, port: 6379 })
email
Object : Config email transport, currently only sendgrid and mailhog are supported. (default: { apiKey: '', transport: 'sendgrid', from: '', subject: '' })
The apiKey is required for sendgrid only.
You can use Mailhog to capture and display emails in local development. The simplest way is to spin up Mailhog in a docker container:
docker run -p 8025:8025 -p 1025:1025 mailhog/mailhog
You can then browse to localhost:8025 to see the emails that have been sent. If you run mailhog on non-default host or port (localhost:1025) then add the host and port into the configuration in your component-config.json:
```
{
  "loopback-component-mailer": {
    "email": {
      "host": "not-localhost",
      "port": 1212,
      "transport": "mailhog"
      }
   }
}
```

Templates

Mail templates are in handlebars format. The subject line for the email should be the first line in the template file and is identified using the following format:

SUBJECT::Your Email Subject

You can also use handlebars in the subject line, for example:

SUBJECT::Your Email regarding {{topic}}

Template files should have the extension .hbs

HTML Header/Footer

A static HTML header and/or footer can be added to HTML emails. Specify the path to the header/footer file(s) in the component config.

Example:

{
  "loopback-component-mailer": {
    "email": {
      "apiKey": "<yourApiKey>",
      "header": "/server/mailer/templates/header.html",
      "footer": "/server/mailer/templates/footer.html"
    }
  }
}

Sending mail from Loopback

When using the default namespace mailer, you can add to the mail queue with the following:

  app.mailer.send(templateName, emailData, callback)

Arguments

templateName:string the name of your email template file
emailData: object example:

  {
    to: <recipient@domain.com>, // can be an array of recipients
    from: <sender@domain.com>, // only required if different from the default set in component-config.json
    bcc: <bcc@domain.com>, // not required, can be an array of recipients
    cc: <cc@domain.com>, // not required, can be an array of recipients
    replyto: <replyto@domain.com>, // not required
    msgVariables: {
      subjectVariable: 'New Subject',
      to: 'Myself',
      text: 'Integration Test'
    }
  }

to: the email address of the recipient
from: the email address of the sender (if different from the default set in component-config.json)
bcc: the email address(es) of the blind carbon copy recipient(s)
cc: the email address(es) of the carbon copy recipient(s)
replyto: the email address to set for reply-to
msgVariables: variables for use in the template file
callback: function this function will be called when the mail has been added to the queue