Home

Awesome

preview-email

build status code style styled with prettier made with lass license

Automatically opens your browser and iOS Simulator to preview Node.js email messages sent with Nodemailer. Made for Forward Email and Lad. Cross-platform and cross-browser email testing.

Need to send emails that land in the inbox instead of spam folder? Click here to learn how to send JavaScript contact forms and more with Node.js

Table of Contents

Screenshots

iOS Simulator

<a href="https://raw.githubusercontent.com/forwardemail/test-preview-emails-cross-browsers-ios-simulator-nodejs-javascript/master/media/macos-notification.png" target="_blank"><img src="https://raw.githubusercontent.com/forwardemail/test-preview-emails-cross-browsers-ios-simulator-nodejs-javascript/master/media/macos-notification.png" width="370" height="112" alt="macOS Notification Screenshot" /></a> <br /> <a href="https://raw.githubusercontent.com/forwardemail/test-preview-emails-cross-browsers-ios-simulator-nodejs-javascript/master/media/ios-simulator.png" target="_blank"><img src="https://raw.githubusercontent.com/forwardemail/test-preview-emails-cross-browsers-ios-simulator-nodejs-javascript/master/media/ios-simulator.png" width="481" height="908" alt="iOS Simulator Screenshot" /></a>

Browser

<a href="https://raw.githubusercontent.com/forwardemail/test-preview-emails-cross-browsers-ios-simulator-nodejs-javascript/master/media/browser.png" target="_blank"><img src="https://raw.githubusercontent.com/forwardemail/test-preview-emails-cross-browsers-ios-simulator-nodejs-javascript/master/media/browser.png" width="617" height="939" alt="Browser Screenshot" /></a>

Install

npm:

npm install preview-email

Requirements

As of v3.0.6 we have built-in support for previewing emails in the iOS Simulator (in addition to rendering them in your default web browser).

This is only applicable if you are using macOS and if not running in a CI environment. If you wish to disable this default behavior, then set openSimulator to false in the options.

Otherwise you will need to install XCode from the App Store or Apple Developer Website. We have built-in friendly macOS notifications that will alert you if there are any issues while attempting to load the iOS Simulator.

After installing XCode, you will need to open it and agree to the terms and conditions. Then you will need to assign Command Line Tools.

Once the Simulator is opened – if you need to inspect the rendered email, then you can use the Web Inspector in Safari Developer Tools.

Usage

NOTE: You should probably just use email-templates directly instead of using this package.

The function previewEmail accepts two arguments message and options, and it returns a Promise which resolves with a URL (unless you specify returnHTML: true in options argument). We automatically open the browser to this URL unless you specify options.open as false (see Options for more info).

const previewEmail = require('preview-email');
const nodemailer = require('nodemailer');

const transport = nodemailer.createTransport({
  jsonTransport: true
});

// <https://nodemailer.com/message/>
const message = {
  from: 'linus+from@gmail.com',
  to: 'linus+to@gmail.com',
  subject: 'Hello world',
  html: '<p>Hello world</p>',
  text: 'Hello world',
  attachments: [{ filename: 'hello-world.txt', content: 'Hello world' }]
};

// note that `attachments` will not be parsed unless you use
// `previewEmail` with the results of `transport.sendMail`
// e.g. `previewEmail(JSON.parse(res.message));` where `res`
// is `const res = await transport.sendMail(message);`
previewEmail(message).then(console.log).catch(console.error);

transport.sendMail(message).then(console.log).catch(console.error);

Custom Preview Template and Stylesheets

Using the options.template object, you can define your own template for rendering (e.g. get inspiration from template.pug and write your own!):

const path = require('path');

// ...

previewEmail(message, {
  template: path.join(__dirname, 'my-custom-preview-template.pug')
})
  .then(console.log)
  .catch(console.error);

Debugging

You can easily debug output from preview-email:

NODE_DEBUG=preview-email node app.js

Options

License

MIT © Forward Email