Facteur

Simplified open-source email delivery for developers.

NOTE: This project is still in active development and not ready for production use.

Current features

Add/remove domains
Preview required DNS records, and check if they are correctly set up
Send emails from a simple REST endpoint
Support for multiple email drivers (currently only supports SMTP with a Postfix setup)

Upcoming features

Attachments
Support for the following drivers : Kannon and AWS SES
Email editor
Receive emails, and forward them to a webhook
... and more!

Technologies

Node.js : JavaScript runtime
TypeScript : JavaScript superset
AdonisJS : Node.js framework
Docker : Containerization
PostgreSQL : Relational database
TailwindCSS : CSS framework
React : Frontend library
ShadCN UI : React components library
Inertia.js : Glue between React and AdonisJS
Postfix : SMTP server

Prerequisites for self-hosting

Debian/Ubuntu based system. Tested on some OVH VPS.
DNS records pointing to mail.yourdomain.tld (A, AAAA), in order to get an SSL certificate.
Docker

Installation

Clone the repository and install the dependencies

# Clone the repository
git clone https://github.com/valyentdev/facteur.git

# Change directory
cd facteur

# Install dependencies
npm install

Run the setup script

sudo ./scripts/setup.sh

Add the DNS records, as shown in the output of the setup script.
Give a password to the postmasteruser:

sudo passwd postmaster

This password will be used to authenticate with the SMTP server.

Configure your environment variables, by copying the .env.example file:

cp .env.example .env

And then edit the .env file with your favorite text editor.

Generate an API key:

node ace generate:key

By default, public sign-up is disabled. You can create a user by running:

node ace auth:sign_up

Add your first domain from which you want to send emails:

node ace domain:add

Configure your DNS records, by adding the generated records to your domain. And then, check if they are correctly set up:

node ace domain:check

Start the services

docker compose -f docker-compose.dev.yml up -d

Access the Facteur dashboard at http://localhost:3333, and start configuring your domains and API keys.
Send your first email, by using the /api/v1/send endpoint. For example,

curl -X POST 'http://localhost:3333/api/v1/emails' \
  -H 'Authorization: Bearer facteur_123456789' \
  -H 'Content-Type: application/json' \
  -d $'{
    "from": "marcel@proust.fr",
    "to": "you@gmail.com",
    "subject": "Hello from Marcel",
    "html": "Hello, <b>Marcel</b> here."
  }'

FAQ

Why is this project named Facteur?

Facteur is the French word for postman. This project aims to help developers deliver emails easily.

What if I want to implement my own email sending solution into Facteur?

You can do so by implementing the IDriver interface that can be found in this file: ./app/drivers/driver.ts.

Make sure to add environment variables for your driver in the .env file, and to validate them in the ./env.ts file.

If you think your implementation could be useful for others, feel free to open a pull request!

What if I miss some feature from Facteur?

Feel free to open an issue (with your feature request), or even better, open a pull request!

What is the license ?

This project is licensed under the MIT License.

Credits

emailwiz - Email server setup scripts

valyentdev / facteur