Docker image: https://hub.docker.com/r/spacefill/gibbon-mail
Send mails with mjml Template and JSON Schema.
master
branch)To generate PDF instead send mails, see this project: gibbon-pdf
See also Gibbon-mail alternative project: Catapulte (Rust implementation of catapulte email sender).
All versions are specified in .tool-versions.
You can use asdf
to install dependencies:
$ asdf plugin-add direnv
$ asdf plugin add nodejs
$ asdf plugin add yarn
$ asdf install
$ direnv allow
mozilla-services/react-jsonschema-form
mjmlio/mjml
stephaneklein/gibbon-mail:latest
)mjmlio/mjml
to generate Html emailv3.3.6
)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
.
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 tagTo see how to create a new tag see "How to publish a new version"
If you want to contribute see those READMEs:
master
is release on latest
.tag
is release with
the according version.$ ./scripts/bump-project-to-version.sh 1.0.0
This will automatically update version in package.json
for frontend and backend.
$ ./scripts/create-and-push-tag.sh
This will automatically create a new local tag and push it.
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.
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
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"
}
Adding a french-only email
/email-folder/FR.{txt,mjml,subject}
filesln -s FR.subject default.subject ; ln -s FR.txt default.txt ; ln -s FR.mjml default.mjml
Create an english version
/email-folder/EN.{txt,mjml,subject}
filesSwitch 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.
Gibbon as an allusion to Mandrill App.
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);
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
.
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: