/gibbon-mail

Send mails with mjml Template and JSON Schema

Primary LanguageJavaScript

CI

Gibbon-mail

Docker image: https://hub.docker.com/r/spacefill/gibbon-mail

Send mails with mjml Template and JSON Schema.

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

See also Gibbon-mail alternative project: Catapulte (Rust implementation of catapulte email sender).

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

Requirements

All versions are specified in .tool-versions.

Installation

You can use asdf to install dependencies:

$ asdf plugin-add direnv
$ asdf plugin add nodejs
$ asdf plugin add yarn
$ asdf install
$ direnv allow

Roadmaps

See other issues...

This project is based on this stack

Quick start

You can use gibbon-mail as a standalone app:

$ npm install -g @spacefill/gibbon-mail
$ gibbon-mail

or as library:

const { createApp } = require('@spacefill/gibbon-mail')

const app = createApp()

const server = app.listen(
  5000,
  '0.0.0.0',
  () => {
    console.log(`Server listening on port: 5000`);
  }
);

It's also available as docker-image.

Docker Image

spacefill/gibbon-mail Docker Image is automatically builded with with our CI. We currently maintain several versions as we use semver to tag our docker images

  • latest tag is pushed with the last commit on master
  • vX.X.X tag are pushed when we push a new tag

To see how to create a new tag see "How to publish a new version"

Contribution

If you want to contribute see those READMEs:

How to publish a new github version

  • Every commit on master is release on latest.
  • Every tag is release with the according version.

How to publish a tag

  1. Bump version
$ ./scripts/bump-project-to-version.sh 1.0.0

This will automatically update version in package.json for frontend and backend.

  1. Create a PR to release with the bumped version
  2. When your PR is merged on master create and push tag
$ ./scripts/create-and-push-tag.sh

This will automatically create a new local tag and push it.

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 nunjunks

To custom nunjunks you must use gibbon-mail as javascript library. You can't do it if you're using the docker version.

You can retrieve nunjuncks environment:

const { nunjucksEnv } = require('@spacefill/gibbon-mail')

You can create a custom filter and add it to gibbon-mail:

const { createApp, nunjucksEnv } = require('@spacefill/gibbon-mail')

function trimFilter(input, length) {
    return String(input).slice(0, length);
}

nunjucksEnv.addFilter('trim', trimFilter);

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: