Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gibbon-lab/gibbon-mail
Send mails with mjml Template and JSON Schema
https://github.com/gibbon-lab/gibbon-mail
api emails form json-schema templates
Last synced: 26 days ago
JSON representation
Send mails with mjml Template and JSON Schema
- Host: GitHub
- URL: https://github.com/gibbon-lab/gibbon-mail
- Owner: gibbon-lab
- Created: 2023-04-11T10:53:05.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-07-06T05:07:18.000Z (4 months ago)
- Last Synced: 2024-09-28T17:04:42.150Z (about 1 month ago)
- Topics: api, emails, form, json-schema, templates
- Language: JavaScript
- Homepage:
- Size: 1.32 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://github.com/gibbon-lab/gibbon-mail/actions/workflows/main.yml)
# Gibbon-mail
Docker image: https://hub.docker.com/r/gibbonlab/gibbon-mail
Send mails with mjml Template and JSON Schema.
- Project status: [POC](https://en.wikipedia.org/wiki/Proof_of_concept)
- Screencast: https://youtu.be/9oih7cZTjk4
- Docker Image: https://hub.docker.com/r/gibbonlab/gibbon-mail (Automated Builds configured on `master` branch)
To generate PDF instead send mails, see this project: [gibbon-pdf](https://github.com/stephane-klein/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](https://github.com/jdrouet/catapulte) (Rust implementation of catapulte email sender).
## Features
- Send email from:
- Json field values (validated by [JSON Schema](https://json-schema.org/))
- [MJML](https://github.com/mjmlio/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](https://json-schema.org/)
- User can preview the email or send email
- Optionnaly record all email sent
- [cid](https://nodemailer.com/message/embedded-images/) image attachment support
## Requirements
- [direnv](https://direnv.net/)
- [docker](https://www.docker.com/)
- [nodejs](https://nodejs.org/en/)
- [pnpm](https://pnpm.io/)
All versions are specified in [.tool-versions](.tool-versions).
### Installation
You can use [`asdf`](https://github.com/asdf-vm/asdf) to install dependencies:
```sh
$ asdf plugin-add direnv
$ asdf plugin add nodejs
$ asdf plugin add pnpm
$ asdf install
$ direnv allow
```
## Roadmaps
- [x] Integrate [`mozilla-services/react-jsonschema-form`](https://github.com/mozilla-services/react-jsonschema-form)
- [x] Integrate [`mjmlio/mjml`](https://github.com/mjmlio/mjml)
- [x] Send mails with [nodemailer](https://nodemailer.com)
- [x] Add [mailhog](https://github.com/mailhog/MailHog) to test
- [x] Docker Image (`gibbonlab/gibbon-mail:latest`)
- [x] curl example
- [x] Screencast
- [x] Swagger
- [x] Multi language mail template support #8
- [x] Add [UISchema](https://react-jsonschema-form.readthedocs.io/en/latest/) support
- [x] Check json input with JSON Schema
- [ ] Test frontend
- [X] Configure CI
- [X] Add [Sentry](https://sentry.io/)
- [ ] Add option to save mail sent (in PostgreSQL)
[See other issues...](https://github.com/stephane-klein/gibbon-mail/issues)
## This project is based on this stack
- [Backend](backend/):
- [NodeJS](https://nodejs.org/en/) with [Koa](https://koajs.com/)
- [`mjmlio/mjml`](https://github.com/mjmlio/mjml) to generate Html email
- [Nunjucks](https://mozilla.github.io/nunjucks/) to fill Email templates
- [nodemailer](https://nodemailer.com) to send email
- [Swagger](https://swagger.io/tools/swagger-ui/) (see [swagger.yaml](backend/src/swagger.yaml) file)
- [Frontend](frontend/)
- [ReactJS](https://en.reactjs.org/), [Axios](https://github.com/axios/axios), [React-router](https://github.com/ReactTraining/react-router)
- [react-jsonschema-form](https://github.com/mozilla-services/react-jsonschema-form) to generate Form from JSON Schema (need Bootstrap version `v3.3.6`)
- [Bootstrap](https://getbootstrap.com/)
- Tooling
- [Jest](https://jestjs.io/) and [supertest](https://github.com/visionmedia/supertest) for backend tests
- [ESLint](https://eslint.org/)
## Quick start
You can use gibbon-mail as a standalone app:
```sh
$ npm install -g @gibbon-lab/gibbon-mail
$ gibbon-mail
```
or as library:
```js
const { createApp } = require('@gibbon-lab/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/).
## Docker Image
[`gibbonlab/gibbon-mail`](https://hub.docker.com/r/gibbon-lab/gibbon-mail) Docker
Image is automatically builded with with our CI. We currently maintain several versions
as we use [`semver`](https://semver.org/) 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"](/README.md#how-to-publish-a-new-version)
## Contribution
If you want to contribute see those READMEs:
- [`backend/`](backend/)
- [`frontend/`](frontend/)
## How to publish a new github version
- Every commit on `master` is release on `latest`.
- Every [`tag`](https://github.com/gibbon-lab/gibbon-mail/tags) 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.
2. Create a PR to release with the bumped version
3. 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](https://en.wikipedia.org/wiki/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:
```sh
$ 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": "[email protected]",
"to": "[email protected]",
"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](https://en.wikipedia.org/wiki/Gibbon) as an allusion to [Mandrill App](https://mandrill.com/).
### 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`](https://mozilla.github.io/nunjucks/fr/api.html#environment):
```js
const { nunjucksEnv } = require('@gibbon-lab/gibbon-mail')
```
You can create a custom filter and add it to gibbon-mail:
```js
const { createApp, nunjucksEnv } = require('@gibbon-lab/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 `[email protected]` email account.
```
# docker-compose.yml
version: "3.7"
services:
gibbon-mail:
image: gibbonlab/gibbon-mail:latest
ports:
- 5000:5000
volumes:
- ../mail-templates/:/templates/
environment:
SMTP_USERNAME: user
SMTP_PASSWORD: password
SMTP_HOST: mailcatcher
SMTP_PORT: 1025
BCC: [email protected],[email protected]
```
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: gibbonlab/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: [email protected]
```
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](https://github.com/getsentry/sentry/tree/master/src/sentry/templates/sentry/emails)
- [GitLab](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/views/notify)