Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mvsde/mailbox

Small wrapper around MJML and Nodemailer for (awesome) HTML emails
https://github.com/mvsde/mailbox

email html-email javascript mjml nodejs nodemailer

Last synced: 5 days ago
JSON representation

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

Awesome Lists containing this project

README 

        
# Mailbox



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



## Requirements



- [Node.js](https://nodejs.org)



## Start a new project



```bash

# 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 

```



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:



```json

{

  "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](https://mjml.io/documentation/#inside-node-js).



## Project setup



### Layouts



The file `src/layouts/default.mjml` serves as a base layout for an HTML email. It uses [MJML (Mailjet Markup Language)](https://mjml.io/documentation/) 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 [``](https://mjml.io/documentation/#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](https://mozilla.github.io/nunjucks/templating.html) 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.



```json

{

  "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:



```bash

npm run dev



# Optional alternative layout

npm run dev -- [layout]



# Optional email data

npm run dev -- --data 

```



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:



```bash

npm run test -- --to 



# Optional alternative layout

npm run test -- [layout] --to 



# Optional sender address

npm run test -- --to  --from 



# Optional alternative email data

npm run test -- --to  --data 

```



This uses the `sendmail` command of the operating system. See [SMTP](#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 [email protected]`, the sender email is optional and defaults to `[email protected]`.



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:



```bash

npm run test -- --to  --smtp.host  --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:



```bash

npm run build



# Optional alternative layout

npm run build -- [layout]



# Optional alternative output location

npm run build -- --output 



# Optional email data

npm run build -- --data 

```



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





  Factorial GmbH