hydra-mailer v1.0.1

HYDRA Mailer

HYDRA Mailer with templated content processing powered by Pug developed by Gab AI, Inc. under the Apache 2.0 open source software license.

Overview

HYDRA Mailer is an NPM module you can add to your HYDRA server to enable your application to send and process email using the Mailgun.com API.

HYDRA Mailer was developed in support of the Gab Business Tools application, which is based on Gab's HYDRA web application framework and not currently open source.

Mailgun Requirements

Mailgun.com is an online service that sends email. HYDRA Mailer uses Mailgun as it's transport for sending email. It does not use the Mailgun SMTP interface. Instead, HYDRA Mailer uses the Mailgun API for better performance. For this reason, a Mailgun.com API key and other credentials are required.

Visit Mailgun Account Security to create and manage your Mailgun API keys. You are going to need three valid Mailgun API keys to send and fully process email with HYDRA Mailer:

• Private API key
• Public validation key
• HTTP webhook signing key

All three are provided by Mailgun.com and require an account.

Getting Started

First, add the hydra-mailer module to your project using Yarn.

yarn add hydra-mailer

Next, add hydra-mailer to any scripts that want to use it.

const HydraMailer = require('hydra-mailer');

let mailer = new HydraMailer({
  mailgunApi: {
    apiKey: 'Your Mailgun Private API key',
    publicApiKey: 'Your Mailgun Public validation key',
    webhookSigningKey: 'Your Mailgun HTTP webhook signing key',
    domain: 'Your Mailgun domain'
  },
  templateRoot: path.join(config.root, 'email'),
  from: 'Email Address <user@some-domain.com>'
});

Next, load the templates you plan to use:

mailer
.loadTemplate('welcome')
.then(( ) => {
  // do app stuff
});

This will load ${templateName}.html.pug and ${templateName}.text.pug from the config.templateRoot directory.

Sending Mail Messages

To send a single message, use the send method.

mailer.send('welcome', {
  from: 'Gab <noreply@info.gab.com>',
  to: 'user@domain.com',
  subject: 'Welcome to Gab.com!',
  attachment: new mailer.mailgun.Attachment({
    data: ...,
    filename: filename,
    contentType: contentType,
    knownLength: content.length
  }),
  templateVars: {
    welcomeOffer: {
      title: 'Exclusive offer for new users!',
      discount: '10%',
      expires: moment().add(24, 'hours').format('MMMM DD, YYYY')
    },
    member: {
      email: job.recipient.email,
      username: job.recipient.username
    },
    ...
  }
})
.then((mailgunResult) => {
  module.log.debug('message sent.', {
    result: mailgunResult
  });
})
.catch((error) => {
  module.log.error('Mailer send error', { error: error });
});

The options.templateVars object is passed directly to Pug when rendering the HTML and Text templates. It will be used as required by your templates.

Dependencies

HYDRA Mailer makes use of the following packages:

• mailgun-js
• pug

License

Copyright 2019 Gab AI, Inc.

Licensed under the Apache 2.0 license.