Gibbon-mail

Send mails with mjml Template and JSON Schema.

• Project status: POC
• Screencast: https://youtu.be/9oih7cZTjk4
• Docker Image: https://hub.docker.com/r/stephaneklein/gibbon-mail (Automated Builds configured on master branch)

To generate PDF instead send mails, see this project: gibbon-pdf

Why this project?

• I would like to move transactionnal mail engine from my application in a separate service
• I would like to allow humans to send email manually, via a simple application plugged to the same API.
• I would like to keep a history (optionally) of all mail sent

Quick start

Go to docker-image/ and read the README.

or if you want to contribute see this READMEs:

• backend/
• frontend/

Roadmaps

• Integrate mozilla-services/react-jsonschema-form
• Integrate mjmlio/mjml
• Send mails with nodemailer
• Add mailhog to test
• Docker Image (stephaneklein/gibbon-mail:latest)
• curl example
• Screencast
• Swagger
• Multi language mail template support #8
• Add UISchema support
• Check json input with JSON Schema
• Test frontend
• Configure CI
• Add option to save mail sent (in PostgreSQL)

See other issues...

Features

• Send email from:
  • Json field values (validated by JSON Schema)
  • MJML template file
  • TXT template file
  • Oneline Subject template file
• Rest API endpoints to generate mail preview or send email
• Web UI to generate email manually:
  • HTML form are autogenerated by JSON Schema
  • User can preview the email or send email
• Optionnaly record all email sent
• cid image attachment support

Docker Image

stephaneklein/gibbon-mail:latest Docker Image is automatically builded when master branch is updated.

This project is based on this stack

• Backend:
  • NodeJS with Koa
  • mjmlio/mjml to generate Html email
  • Nunjucks to fill Email templates
  • nodemailer to send email
  • Swagger (see swagger.yaml file)
• Frontend
  • ReactJS, Axios, React-router
  • react-jsonschema-form to generate Form from JSON Schema (need Bootstrap version v3.3.6)
  • Bootstrap
• Tooling
  • Jest and supertest for backend tests
  • ESLint

FAQ

How can I enable Authentication system?

This project hasn't build-in authentication system, it's a internal service in your stack, you must protect it by a private network or Basic access authentication system.

How does the multi-language support works?

Language files

Inside your mail templates folders, you can create multiple languages files for each email, in the following format: /mail-templates/email-folder/{lang}.(mjml|subject|txt).

For example, an email that supports French and English, and defaults to english, will have the following files in its template folder:

$ ls mail-templates/email-example
default.mjml -> en.mjml                 fr.mjml              en.mjml
default.subject -> en.subject           fr.subject           en.subject
default.txt -> en.mjml                  fr.txt               en.txt

Note: default files are actually symbolic links

Telling Gibbon which language to use

When using Gibbon to send an email, if the lang property is present in the body of the request, Gibbon will use the corresponding language files accordingly. If the language files are not found, Gibbon will use the default files

For example, the following request body will try to send a german email, or fallback to the default email if there are no german files in the template folder:

{
  "from": "no-reply@example.com",
  "to": "john.doe@example.com",
  "lang": "de"
}

Examples

• Adding a french-only email

  • create /email-folder/FR.{txt,mjml,subject} files
  • run the following command to use French as the default language: ln -s FR.subject default.subject ; ln -s FR.txt default.txt ; ln -s FR.mjml default.mjml

• Create an english version

  • create /email-folder/EN.{txt,mjml,subject} files

• Switch the default version from French to English

  • rm -f default.*
  • ln -s EN.subject default.subject ; ln -s EN.txt default.txt ; ln -s EN.mjml default.mjml

If the lang property is missing from the body of the request, Gibbon will fallback to the default version, and use the default files.

Why « Gibbon-mail » name?

Gibbon as an allusion to Mandrill App.

Custom filters

All Nunjucks features and filters are available, but often enough, you may find that not to be enough. Gibbon now supports custom filters.

To learn how to do this, refer to backend/filters/index.js.

How can I keep an archive of all mails send by Gibbon-mail?

Configure BCC variable env as below example to send all mails send by Gibbon-mail to log@example.com email account.

# docker-compose.yml
version: "3.7"
services:
  gibbon-mail:
    image: stephaneklein/gibbon-mail:latest
    ports:
     - 5000:5000
    volumes:
     - ../mail-templates/:/templates/
    environment:
      SMTP_USERNAME: user
      SMTP_PASSWORD: password
      SMTP_HOST: mailcatcher
      SMTP_PORT: 1025
      BCC: log@example.com,test1@example.com

Or you can pass it to the body of the request as bcc.

Why can I configure two smtp service?

Gibbon-mail support two smtp server configuration, for instance:

# docker-compose.yml
version: "3.7"
services:
  gibbon-mail:
    image: stephaneklein/gibbon-mail:latest
    ports:
     - 5000:5000
    volumes:
     - ../mail-templates/:/templates/
    environment:
      SMTP_USERNAME: user
      SMTP_PASSWORD: password
      SMTP_HOST: mailcatcher
      SMTP_PORT: 1025
      SMTP_LABEL: "Send mail to Mailcatcher"
      SMTP2_USERNAME: user
      SMTP2_PASSWORD: password
      SMTP2_HOST: example.com
      SMTP2_PORT: 25
      SMTP2_LABEL: "Send mail with example.com smtp server"
      BCC: log@example.com

You can use SMTP2_URL for instance on staging environment: by default, you send mail to Mailhog fake smtp server et optionnaly on real smtp server to test your mail template rendering on several email clients.

---

Emails examples:

• Sentry
• GitLab