mailgen

A Node.js package that generates clean, responsive HTML e-mails for sending transactional mail.

Programmatically create beautiful e-mails using plain old JavaScript.

Demo

Usage

First, install the package using npm:

npm install mailgen --save

Then, start using the package by importing and configuring it:

var Mailgen = require('mailgen');

// Configure mailgen by setting a theme and your product info
var mailGenerator = new Mailgen({
    theme: 'default',
    product: {
        // Appears in header & footer of e-mails
        name: 'Mailgen',
        link: 'https://mailgen.js/'
        // Optional product logo
        // logo: 'https://mailgen.js/img/logo.png'
    }
});

Next, generate an e-mail using the following code:

// Prepare email contents
var email = {
    body: {
        name: 'John Appleseed',
        intro: 'Welcome to Mailgen! We’re very excited to have you on board.',
        action: {
            instructions: 'To get started with Mailgen, please click here:',
            button: {
                color: 'green',
                text: 'Confirm your account',
                link: 'https://mailgen.js/confirm?s=d9729feb74992cc3482b350163a1a010'
            }
        },
        outro: 'Need help, or have questions? Just reply to this email, we\'d love to help.'
    }
};

// Generate an HTML email using mailgen
var emailBody = mailGenerator.generate(email);

// `emailBody` now contains the HTML body.
// It's up to you to send the e-mail. 
// Check out nodemailer to accomplish this: 
// https://nodemailer.com/

This code would output the following HTML template:

More Examples

Plaintext E-mails

To generate a plaintext version of the e-mail, simply call generatePlaintext():

// Generate plaintext email using mailgen
var emailText = mailGenerator.generatePlaintext(email);

Supported Themes

The following open-source themes are bundled with this package:

default by Postmark Transactional Email Templates

neopolitan by Send With Us

salted by Jason Rodriguez

We thank the contributing authors for creating these themes.

Custom Themes

If you want to supply your own custom theme or add a new built-in theme, check out THEME.md for instructions.

RTL Support

To change the default text direction (left-to-right), simply override it as follows:

var mailGenerator = new Mailgen({
    theme: 'salted',
    // Custom text direction
    textDirection: 'rtl',
});

Language Customizations

To customize the e-mail greeting (Hi) or signature (Yours truly), supply custom strings within the e-mail body:

var email = {
    body: {
        // Custom greeting
        greeting: 'Dear',
        
        name: 'John Appleseed',
        intro: 'Welcome to Mailgen! We’re very excited to have you on board.',
        
        // Custom signature
        signature: 'Sincerely' 
    }
};

To customize the copyright, override it when initializing Mailgen within your product as follows:

// Configure mailgen 
var mailGenerator = new Mailgen({
    theme: 'salted',
    product: {
        name: 'Mailgen',
        link: 'https://mailgen.js/',
        
        // Custom copyright notice
        copyright: 'Copyright © 2016 Mailgen. All rights reserved.',
    }
});

Go-To Actions

You can make use of Gmail's Go-To Actions within your e-mails by suppling the goToAction object as follows:

var email = {
    body: {
        // Optionally configure a Go-To Action button 
        goToAction: {
            text: 'Go to Dashboard',
            link: 'https://mailgen.com/confirm?s=d9729feb74992cc3482b350163a1a010',
            description: 'Check the status of your order in your dashboard'
        }
    }
};

Note that you need to get your sender address whitelisted before your Go-To Actions will show up in Gmail.

Troubleshooting

After sending multiple e-mails to the same Gmail / Inbox address, they become grouped and truncated since they contain similar text, breaking the responsive e-mail layout.

Simply sending the X-Entity-Ref-ID header with your e-mails will prevent grouping / truncation.

Contributing

Thanks so much for wanting to help! We really appreciate it.

Have an idea for a new feature?
Want to add a new built-in theme?

Excellent! You've come to the right place.

If you find a bug or wish to suggest a new feature, please create an issue first
Make sure your code & comment conventions are in-line with the project's style
Make your commits and PRs as tiny as possible - one feature or bugfix at a time
Write detailed commit messages, in-line with the project's commit naming conventions

Check out THEME.md if you want to add a new built-in theme to Mailgen.

License

Apache 2.0

butch2k/mailgen