MailHero is a project that helps you bootstrap your emailing services using modern technologies.

To run this project, you need the following tools installed:

• Docker
• Bun

To run the development environment, run the following command:

bun run dev

To test emails being sent, open this following url in your browser:

• http://localhost:3000/mail/welcome

You should see an email being sent to test@example.com from noreply@mailhero.com in the Mailhog mailcatcher at the following address:

• http://localhost:8025

This project is based on the following stack:

• React Email
• Nodemailer
• Mailhog
• Docker
• Bun

The main directories are the following:

• src/mail: contains all the React Email templates
• src/routes: contains all the HTTP routes, mainly the mail ones under mail.routes.tsx
• src/conf: contains environnement schema validation with zod and transporter config from Nodemailer
• docker: 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:

• http://localhost:8025

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:

• http://localhost:8025

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"