loopback-component-mailer

1.3.0 • Public • Published

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

  1. Install in you loopback project:

npm install --save loopback-component-mailer

  1. Create a component-config.json file in your server folder (if you don't already have one)

  2. Configure options inside component-config.json. (see configuration section)

{
  "loopback-component-mailer": {
    "{option}": "{value}"
  }
}
  1. 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

Package Sidebar

Install

npm i loopback-component-mailer

Weekly Downloads

76

Version

1.3.0

License

MIT

Unpacked Size

38.4 kB

Total Files

9

Last publish

Collaborators

  • jonathanprince
  • mediasuite
  • nucleoid