jdrouet/catapulte repository overview

⁠Catapulte

⁠What is catapulte?

Catapulte is an open source mailer you can host yourself.

You can use it to quickly catapult your transactionnal emails to destination.

⁠Why did we build catapulte?

Catapulte comes from the frustration of using several email providers. We used to work with products like sendgrid⁠, mailgun⁠, mailchimp⁠, sendinblue⁠, etc.

But they have many disadvantages :

• Most of them are not really transactionnal oriented, and users complain that their login emails take a long time to arrive.
• You cannot host it nor use it on premise
• It's American, with the patriot act, they are able to access your users data.
• They usually don't have templating tools for our non tech coworkers that ask us to change a wording every 2 days. And when they do, the editors are like html online editors, so it ends up being our job to make the template anyway.

⁠How to use it?

Catapulte is a simple service that renders your mjml template, interpolates the data and then sends it to a SMTP server. If you want to see how to create your own template, take a look at the /template folder in this repository.

You then have several options for starting catapulte. We recommend using Docker if you are on a amd64, i386 or arm64v8 architecture. By doing the following, you'll be able to have a running server that will render and send your email.

docker run -d \
  --name catapulte \
  -e SMTP_HOSTNAME=localhost \
  -e SMTP_PORT=25 \
  -e SMTP_USERNAME=optional \
  -e SMTP_PASSWORD=optional \
  -e SMTP_TLS_ENABLED=true \
  -e SWAGGER_ENABLED=true \
  -e TEMPLATE_PROVIDER=local \
  -e TEMPLATE_ROOT=/templates \
  -p 3000:3000 \
  -v /path/to/your/templates:/templates:ro \
  jdrouet/catapulte:master

Once your server started, you can simply send an email using an HTTP request.

curl -X POST -v \
  -H "Content-Type: application/json" \
  --data '{"from":"[email protected]","to":"[email protected]","params":{"some":"data"}}' \
  http://localhost:3000/templates/the-name-of-your-template

You can also send attachments using a multipart request.

curl -X POST -v \
  -F attachments=@asset/cat.jpg \
  -F [email protected] \
  -F [email protected] \
  -F params='{"some":"data"}' \
  http://localhost:3000/templates/user-login

You can configure it with some environment variable⁠ and can find more information in this wiki⁠.

If you some API specification, the Open API specification⁠ is also available.

To use it in production, we prepared a documentation on how to use Catapulte with Amazon Simple Email Service⁠.

⁠Sending to multiple recipients

You can send the same email to multiple recipients just by using an array in the to field, like this:

curl -X POST -v \
  -H "Content-Type: application/json" \
  --data '{"from":"[email protected]","to":["[email protected]","[email protected]"],"params":{"some":"data"}}' \
  http://localhost:3000/templates/the-name-of-your-template

⁠Should you use it?

If, like us, you didn't find any good way of doing transactionnal emails, then YES!

⁠Why you should use it :

• You work in a startup

  • You don't have shit loads of money to spend on the mailing tools, so use something opensource, send your emails from your own SMTP (or from Amazon SES, it's cheap)
  • You don't have time to change the email template everyday, so let your Product Owner do it
  • You wanna be able to add this little feature, just do a pull request...

• You work in a big company

  • You cannot use those external services because you're not allowed to put your user's data on an external service.
  • You cannot access external services because it's blocked by the proxy
  • You want to customise the way you authenticate to your SMTP
  • You want something user friendly enough that your manager can write the emails

⁠Thank you!