MailHero is a project that helps you bootstrap your emailing services using modern technologies.
To run this project, you need the following tools installed:
To run the development environment, run the following command:
bun run dev
To test emails being sent, open this following url in your browser:
You should see an email being sent to test@example.com
from noreply@mailhero.com
in the Mailhog mailcatcher at the following address:
This project is based on the following stack:
The main directories are the following:
src/mail
: contains all the React Email templatessrc/routes
: contains all the HTTP routes, mainly the mail ones under mail.routes.tsxsrc/conf
: contains environnement schema validation with zod and transporter config from Nodemailerdocker
: containers Dockerfiles for building debian distroless and bun slim image.env
: contains dev and production environments
To run the dev environment, you simply need to run the following command:
bun run dev
This command does the following:
- Run an instance of a docker service of Mailhog to catch emails locally for testing purposes.
- Run the dev environment for the Bun.serve HHTP-server.
You can go to the following link to check the sent emails:
You can test that the mails are sent properly by sending a POST request with the following body to http://localhost:3000/mail/welcome
:
{
"to": "angelo@mailhero.com"
}
Or by running the following curl command:
curl -X POST http://localhost:3000/mail/welcome -H "Content-Type: application/json" -d '{"to": "angelo@mailhero.com"}'
You should see an email being sent to angelo@mailhero.com
from noreply@mailhero.com
in the Mailhog mailcatcher at the following address:
If you ran the command above, to stop the running container for mailoh, run the following command:
bun run stop
To check how your emails look and test them out with React Email, use the following command:
bun run email
Once docker installed, you need to pull the SlimtoolKit image. This image is used to reduce the final image size. Run the following image to pull dslim/slim:
docker pull dslim/slim
To build the bun:slim and slimmed images, run the following command in bash or powershell:
docker run -it --rm -v "${pwd}:/app" -v /var/run/docker.sock:/var/run/docker.sock dslim/slim --archive-state off --crt-api-version=1.25 build --dockerfile /docker/bun.Dockerfile --tag-fat mailhero:bun-slim --tag mailhero:bun-slimmed --include-path /bin --http-probe-off --continue-after=1 /app
On Nushell, run the following command:
docker run -it --rm -v $"(pwd):/app" -v /var/run/docker.sock:/var/run/docker.sock dslim/slim --archive-state off --crt-api-version=1.25 build --dockerfile /docker/bun.Dockerfile --tag-fat mailhero:bun-slim --tag mailhero:bun-slimmed --include-path /bin --http-probe-off --continue-after=1 /app
To build the distroless and slimmed distroless images with a compiled executable on debian, run the following command in bash or powershell:
docker run -it --rm -v "${pwd}:/app" -v /var/run/docker.sock:/var/run/docker.sock dslim/slim --archive-state off --crt-api-version=1.25 build --dockerfile /docker/debian.Dockerfile --tag-fat mailhero:debian-slim --tag mailhero:debian-slimmed --include-path /bin --http-probe-off --continue-after=1 /app
On Nushell, run the following command:
docker run -it --rm -v $"(pwd):/app" -v /var/run/docker.sock:/var/run/docker.sock dslim/slim --archive-state off --crt-api-version=1.25 build --dockerfile /docker/debian.Dockerfile --tag-fat mailhero:debian-slim --tag mailhero:debian-slimmed --include-path /bin --http-probe-off --continue-after=1 /app
To run the production environment, first create a prod.env
file in the env
folder.
Then run the following command:
docker compose up -d
By default, this compose file uses the debian-slimmed build of the image we created with the commands listed above.
You can change it to use the slim version of bun instead like so:
services:
mailhero:
image: mailhero:bun-slimmed
container_name: 'mailhero'
env_file: ./env/prod.env
ports:
- "3000:3000"