npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@bouncingpixel/mailgun-emails

v0.3.0-beta

Published

Emailer capability using mailgun to send and DustJS for rendering

Downloads

7

Readme

mailgun-emails

A utility for sending emails using Mailgun. Emails are defined in a directory with a .dust template file and a .js settings file.

Working With the Template

Requirements

  • NodeJS 6 LTS
  • dustjs-linkedin pre-initialized
  • A Mailgun account

Configuration

This module, like many other @bouncingpixel modules, relies on nconf. The following configuration keys should be defined to use this module:

Required

  • mailgunTemplatePath The path to the directory containing the template dust and JS settings files.
  • mailgunDomain The domain used in the mailgun configuration. If left unset, sending emails will simply return without sending and without errors.
  • mailgunApiKey The API key for accessing mailgun. If left unset, sending emails will simply return without sending and without errors.

Optional

  • mailgunDefaultFrom The default address to use in the From field when an email does not have a specific one defined.
  • siterootHost The site's root host such as mydomain.com for URLs rendered by Dust. The resulting URL is defined as siterootUrl
  • requireHTTPS If siterootUrl is defined, this defines if any URLs sent to the user should be HTTP or HTTPS

Using mailgun-emails

The email folder is used to store the configuration and dust template files for each email that could be sent. An email type must contain both files: a JS file which exports an object containing the configuration for that email, and a dust file defining the template to be displayed to the end user. For mass-sent emails that need individual variables, Mailgun supports per-recipient variables. Expose the variable in the configuration using individualVars, and then use the format %recipient.VARIABLE% where VARIABLE is the name of the variable exposed. All variables shared between all recipients can skip the Mailgun template variables and use Dust directly. These variables are exposed with dustVars.

Each email can define who the from address is. This can either be a function which returns the from address or a string. Each email can define who the to addresses are. This field is an array and can either contain a string of each email or an object such as {name: "Person's name", email: "[email protected]"}. Finally, the email configuration must define a subject, which may be a function or a string.

Each of the functions defined for to, from, subject, individualVars, and dustVars take only one parameter which contains all options passed into the call to sendTemplateEmail.

Sending an email uses the function sendTemplateEmail. This function returns a promise.

// Sends an email
sendTemplateEmail(options: {
  // template, required
  // the name of the template to load. This is the filename of the .dust/.js file.
  template: string,

  // recipients, required unless template settings defines `to`
  recipients: string[] | {name: string, email: string}[],

  // any additional parameters needed for processing may be passed
}): Promise

Creating a template

A template consists of two parts: a dust template and a JS settings file. The dust file is just normal dust and any helpers that are attached to the dust JS.

The settings file is a single exported object. The settings file is as follows:

module.exports = {
  // from is optional if mailgunDefaultFrom is defined. will always use this as from if available.
  // this can optionally be a function that takes a single parameter: the options passed to sendTemplateEmail
  from: 'Our Site <[email protected]>',

  // to is optional if the recipients is defined in the sendTemplateEmail options parameter
  // this can optionally be a function that takes a single parameter: the options passed to sendTemplateEmail
  to: ['[email protected]'],

  // the subject of the email to send, this is required
  // this can optionally be a function that takes a single parameter: the options passed to sendTemplateEmail
  subject: 'My email subject',

  // dustVars is an optional function to filter or manipulate the options to generate variables exposed to dust
  // by default, all options passed to sendTemplateEmail if this is not defined
  dustVars: function(options) {
    return options;
  },

  // individualVars is an optional function to determine which values each recipient recieves
  // this uses Mailgun's templates, not the dustjs!
  individualVars: function(recipient, opts) {
    return null;
  }
};