When building Laravel applications it's helpful to have a reliable and secure way to test email functionality without sending emails to an actual inbox. Mailpit serves as a local SMTP server, making it easy to capture and view emails sent during development.

This guide will walk you through setting up Mailpit on Laravel Forge, although the steps are relevant for any Linux-based hosting environment.

Why Mailpit?

Mailpit is a simple, self-hosted email testing tool that allows developers to catch and inspect emails sent by their applications. It provides a web interface to view emails and supports authentication for added security. By using Mailpit, developers can ensure that their email functionality works as expected in a controlled environment.

Mailpit is written in Go, so it is highly performant and resource efficient. It can also be built and distributed as a binary, so it's easy to install and manage.

Step 1: Install Mailpit

The first step is to install Mailpit on your server. SSH to the machine and follow these steps to download and set it up:

1. Create a directory for the Mailpit download:

   mkdir ~/mailpit
   cd ~/mailpit
   

2. Download the latest Mailpit release:

   wget https://github.com/axllent/mailpit/releases/download/v1.20.2/mailpit-linux-amd64.tar.gz
   

3. Extract the tar file:

   tar -xvf mailpit-linux-amd64.tar.gz
   

4. Move the binary to /opt/mailpit/:

   sudo mkdir /opt/mailpit
   mv mailpit /opt/mailpit/
   

Step 2: Prepare Passwords

This step is optional but recommended. This will secure Mailpit's user interface and SMTP server, preventing unwanted access.

1. Create a directory for password storage:

   sudo mkdir -p /var/lib/mailpit
   

2. Create a password file for the web interface, replacing the placeholder below with your own (secure) password:

   sudo sh -c 'echo "mailpit:<WEB PASSWORD>" > /var/lib/mailpit/web_password'
   

3. Create a password file for the SMTP entrypoint, replacing the placeholder below with your own (secure) password:

   sudo sh -c 'echo "mailpit:<SMTP PASSWORD>" > /var/lib/mailpit/smtp_password'
   

Step 3: Setup a Webserver for the Frontend

To serve Mailpit through a web interface, you need to create a new Nginx-powered website. Assuming you're using Laravel Forge:

1. Log in to your Laravel Forge account.
2. Select the server where you want to install Mailpit.
3. Create a new site:
   • Click on "Create Site."
   • Choose "Static HTML" as the site Project Type.
   • Enter mailpit.yourdomain.com as the root domain.
   • Finish the site creation process.

This will create a placeholder site that we will configure to serve Mailpit. Don't forget to set-up HTTPS by generating a LetsEncrypt certificate under the SSL tab for the newly created site.

Step 4: Configure DNS

You now need to set up a DNS record to point mailpit.yourdomain.com to your Forge site.

1. Access your DNS provider's dashboard.
2. Create a new A record:
   • Name: mailpit
   • Type: A
   • Value: Your Forge server's IP address.

This ensures that mailpit.yourdomain.com points to the correct server.

Step 5: Update Nginx Configuration

You'll need to update the Nginx configuration to proxy requests to Mailpit.

1. Edit the Nginx config for your site:

   • Navigate to the Nginx configuration for mailpit.yourdomain.com in Laravel Forge.
   • Update the location / block as follows:

   location / {
       proxy_pass http://127.0.0.1:8025;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "Upgrade";
   }
   

2. Save and reload Nginx.

This configuration will route traffic from mailpit.yourdomain.com to the Mailpit web interface.

Step 6: Set Up Daemon

Finally, you'll need to set up Mailpit as a daemon on your server to keep it running. You can set this up using SystemD or Supervisor, or in Forge:

1. Create a new daemon in Laravel Forge:

   • Navigate to the relevant server
   • Go to the "Daemons" tab in Forge.
   • Fill the form with directory /opt/mailpit/ and command as below:

   /opt/mailpit/mailpit --database /home/forge/mailpit.db --ui-auth-file /var/lib/mailpit/web_password --smtp-auth-file /var/lib/mailpit/smtp_password --smtp-auth-allow-insecure
   

   • Press the "Create" button.

This will ensure Mailpit runs continuously in the background.

Conclusion

With these steps, you've successfully set up Mailpit on your server!

If everything is working correctly you should be able to navigate to mailpit.yourdomain.com to access the frontend. To send mail to Mailpit from your Laravel application, simple configure it to use Mailpit as a normal SMTP server (in your .env file):

MAIL_MAILER="smtp"
MAIL_HOST="127.0.0.1"
MAIL_PORT=1025
MAIL_USERNAME=mailpit
MAIL_PASSWORD="<SMTP PASSWORD>"

Note that this assumes Mailpit and the Laravel application are running on the same server. If you want to use a dedicated Mailpit server, you'll need to make sure port 1025 is unblocked in the firewall rules and update the server host in the Laravel config accordingly.

---