README.md

Mailbox

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

Requirements

• Node.js

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|false,
    "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.

Sponsors