Miss any of our Open RFC calls?Watch the recordings here! »

@mvsde/mailbox

0.8.2 • Public • Published

Mailbox

Small wrapper around MJML and Nodemailer for (awesome) HTML emails.

Table of contents

  1. Requirements
  2. Start a new project
  3. Configuration
  4. Project setup
    1. Layouts
    2. Includes
    3. Attachments
    4. Data
  5. Development server
  6. Send test email
    1. SMTP
  7. Build for production

Requirements

Start a new project

# In current folder 
npx @mvsde/mailbox create
 
# In a sub-folder 
npx @mvsde/mailbox create [folder]
cd folder
 
# With a different name 
npx @mvsde/mailbox create --name <project-name>

The folder defaults to the current directory (.) and the name to mailbox-project.

If you created your project with the optional folder argument, don't forget to change to the new folder with cd name-of-your-folder before you continue.

Configuration

Edit the optional .mjmlconfig in the project root to customize MJML settings:

{
  "options": {
    "fonts": {
      "Font Name": "https://example.com/path/to/font/stylesheet.css"
    },
    "keepComments": true,
    "beautify": false,
    "minify": false,
    "minifyOptions": {
      "collapseWhitespace": true,
      "minifyCSS": false,
      "removeEmptyAttributes": true
    },
    "validationLevel": "strict"|"soft"|"skip"
  },
  "packages": []
}

The MJML documentation provides a short description for the available options.

Project setup

Layouts

The file src/layouts/default.mjml serves as a base layout for an HTML email. It uses MJML (Mailjet Markup Language) for simpler email markup.

Includes

The src/includes-folder is optional, it can be renamed or removed altogether. The idea behind this folder is to have one location for reusable chunks of markup. With <mj-include> MJML files can be included in layouts or other includes.

Attachments

Files in the folder src/attachments can be referenced in a data specification. Nodemailer attaches these to the mail and provides a cid so images can be loaded from the attachments. The contents of the attachment folder will be copied as-is to the output during build time.

Data

The data folder has to contain at least a default.json file which serves as the base data specification. You can create more JSON data files, but they always need a default.json to extend.

The data file content is passed to Nunjucks as a context. This allows the use of Nunjucks templating features to enhance the development and testing phase.

The attachments-key in a data file will be transformed to allow static file linking during development and cid-attachment linking in test emails.

{
  "attachments": {
    "name": "filename.ext"
  }
}

The attachment is available as {{ attachments.name }} within the email template. The value is the filename of the attachment relative to the src/attachments directory.

Development server

You can start a development server with auto-reload using the following command:

npm run dev
 
# Optional alternative layout 
npm run dev -- [layout]
 
# Optional email data 
npm run dev -- --data <data-spec,...>

The layout defaults to default (the src/layouts/default.mjml file). The Nunjucks context isn't populated with data by default.

You can specifiy one or more data files with --data file1,file2,.... The list will always be prepended with the default data file. The files will be merged from right into left.

NOTE: You don't need to specify the full path for data files. The file name without extension is sufficient.

Send test email

To send a test email use the following command:

npm run test -- --to <email-address>
 
# Optional alternative layout 
npm run test -- [layout] --to <email-address>
 
# Optional sender address 
npm run test -- --to <email-address> --from <email-address>
 
# Optional alternative email data 
npm run test -- --to <email-address> --data <data-spec,...>

This uses the sendmail command of the operating system. See SMTP on how to use a mail server.

Both layout and data default to default (the src/layouts/default.mjml and data/default.json files). A recipient email address has to be specified with --to info@example.com, the sender email is optional and defaults to test@example.com.

Email data other than default can be specified with --data file1,file2,.... The list will always be prepended with the default data file. The files will be merged from right into left.

NOTE: You don't need to specify the full path for data files. The file name without extension is sufficient.

SMTP

Sending via SMTP is optional and can be enabled with:

npm run test -- --to <email-address> --smtp.host <smtp-host> --smtp.port <smtp-port>

The username and password prompt may be skipped if the mail server allows seding without credentials.

Build for production

To generate production-ready HTML files use this command:

npm run build
 
# Optional alternative layout 
npm run build -- [layout]
 
# Optional alternative output location 
npm run build -- --output <path>
 
# Optional email data 
npm run build -- --data <data-spec,...>

The layout defaults to default (the src/layouts/default.mjml file). The output path can be changed with --output path/to/output.html. The full filepath has to be specified.

You can specifiy one or more data files with --data file1,file2,.... The list will always be prepended with the default data file. The files will be merged from right into left.

NOTE: You don't need to specify the full path for data files. The file name without extension is sufficient.

Install

npm i @mvsde/mailbox

DownloadsWeekly Downloads

83

Version

0.8.2

License

Hippocratic-2.1

Unpacked Size

50.8 kB

Total Files

55

Last publish

Collaborators

  • avatar