Nukem's Possible Manifestation
    Wondering what’s next for npm?Check out our public roadmap! »

    bedrock-mail

    3.0.1 • 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.

    Install

    npm i bedrock-mail

    DownloadsWeekly Downloads

    77

    Version

    3.0.1

    License

    none

    Unpacked Size

    29.5 kB

    Total Files

    19

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar
    • avatar
    • avatar
    • avatar