bedrock-mail

3.1.0 • Public • Published

bedrock-mail

A Bedrock module that allows you to send automated, template-based emails in response to events. Data used in the templates comes from both data in the events and from "triggers" that are run to load data for the event. Templates can be written in any language supported by email-templates.

Requirements

  • An available nodemailer transport (SMTP, AWS SES, etc).

Quick Examples

npm install bedrock-mail
const bedrock = require('bedrock');
const brMail = require('bedrock-mail');
const {config} = bedrock;

// configure default mail behavior
// defaults to send if NODE_ENV is 'production'
//config.mail.send = true;
// defaults for every message
config.mail.message = {
  from: 'My Company Support <support@example.com>'
};

// setup SMTP transport
bedrock.config.mail.transport = {
  type: 'smtp',
  options: {
    host: 'mail.example.com'
  },
  verify: true
};

// setup default template locals for all mails
bedrock.config.mail.locals.service = {
  name: 'My Service',
  url: 'https://example.com/'
};

// schedule generic event
bedrock.events.emitLater({
  type: 'myModule.myEvent',
  details: {
    accountId: 1234,
    image: 'https://example.com/images/2020-01-01.png'
  }
});

// handle generic even and send email
bedrock.events.on('myModule.myEvent', async event => {
  const account = await getAccount(event.accountId);
  brMail.send({
    template: 'myModule.myEvent',
    message: {
      to: account.email
    },
    locals: {
      image: event.image
    }
  });
});

Example EJS subject template events/myModule.myEvent/subject.ejs:

Here's your daily image from <%= service.name %>!

Example EJS html template events/myModule.myEvent/html.ejs:

<html>
  <body>
    <p>Hello <%= account.name %>,</p>
    <p>Here's your daily image:</p>
    <p><img src="<%= image %>"></p>
    <hr/>
    <p><a href="<%= service.url %>"><%= service.name %></a></p>
  </body>
</html>

Example EJS text template if the auto-generated one from HTML is not sufficient events/myModule.myEvent/text.ejs:

Hello <%= account.name %>,

Here's a link to your daily image:
<%= image %>

-- 
<%= service.name %>
<%= service.url %>

This template depends on the service object and properties to be setup on a global level. See the nodemailer docs if you want to add attachments, embedded images, or use other features.

EJS includes work with file paths relative to the template. For example, the text template example that includes a text footer:

example/text.ejs:

Welcome to our service!

<%- include('../common/footer.text.ejs') %>

common/footer.text.ejs:

-- 
Example Service
https://example.com/

See the test directory for a full example.

Configuration

For documentation on configuration, see config.js, the example above, the test example, and the nodemailer and email-templates documentation.

API

async use('transport', transport)

Configure at runtime to use a specific transport configuration. Transport is the same format as bedrock.config.mail.transport.

async verify()

Call the transport verify() method, if supported. See the nodemailer documentation. Useful to check a SMTP connection works.

async send({template, message, locals})

Send mail using a specific template (name or path), message options, and local vars.

await brMail.send('my-template', {to: 'someone@example.com'}, {foo: 'bar'});

Testing

The test directory example tool can be used to test transports and templates.

CLI Overrides

This library adds global CLI options that can be useful during development to override config values. Boolean options are case-insensitve: default, false, f, 0, true, t, 1.

  • --mail-to ADDRESS: Override mail target address for all emails.
  • --mail-preview BOOLEAN: Override previewing mail mode.
  • --mail-send BOOLEAN: Override sending mail mode.
  • --mail-log BOOLEAN: Override logging mode to print headers and text body.

Readme

Keywords

Package Sidebar

Install

npm i bedrock-mail

Weekly Downloads

1

Version

3.1.0

License

none

Unpacked Size

30.1 kB

Total Files

20

Last publish

Collaborators

  • msporny
  • dlongley
  • davidlehn
  • mattcollier
  • gannan