Testing Emails in Laravel with MailHog on Ubuntu (Nginx Setup + Basic Auth)

Testing Emails in Laravel with MailHog on Ubuntu (Nginx Setup + Basic Auth)

~ 2 min read

devops email testing laravel mailhog nginx security system administration ubuntu

Setting up MailHog on Ubuntu

When building Laravel applications, it’s often helpful to test outgoing emails without sending real messages. MailHog is a lightweight, local SMTP server and web interface designed exactly for this purpose.

This guide shows how to install and configure MailHog on an Ubuntu server running Laravel with PHP and nginx, and how to protect its web UI with HTTP basic authentication via nginx.

1: Install MailHog

Install the MailHog binary manually:

wget https://github.com/mailhog/MailHog/releases/download/v1.0.1/MailHog_linux_amd64
chmod +x MailHog_linux_amd64
sudo mv MailHog_linux_amd64 /usr/local/bin/mailhog

2: Run MailHog as a System Service

sudo nano /etc/systemd/system/mailhog.service

Paste the following configuration:

[Unit]
Description=MailHog Service
After=network.target

[Service]
ExecStart=/usr/local/bin/mailhog -api-bind-addr=127.0.0.1:8025 -ui-bind-addr=127.0.0.1:8025 -smtp-bind-addr=127.0.0.1:1025
Restart=always
User=www-data
Group=www-data

[Install]
WantedBy=multi-user.target

Then reload systemd and start the service:

sudo systemctl daemon-reload
sudo systemctl enable mailhog
sudo systemctl start mailhog

3: Configure Laravel to Use MailHog

Update your .env file in Laravel:

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

Clear the config cache if necessary:

php artisan config:clear
php artisan config:cache

You will also have to restart and queue workers so they also pick up the configuration changes.

Now Laravel will send emails to MailHog instead of a real SMTP server.

4: Expose the MailHog UI with Nginx + Basic Auth

To access MailHog from a browser, we’ll use nginx to reverse proxy the web UI, and protect it with HTTP basic authentication.

4.1 Create Basic Auth Credentials

sudo apt install apache2-utils

Create a password file:

sudo htpasswd -c /etc/nginx/.htpasswd-mailhog yourusername

You’ll be prompted to enter a password.

Create a new nginx config:

sudo nano /etc/nginx/sites-available/mailhog.yourdomain.com

Example configuration:

server {
    listen 80;
    server_name mailhog.yourdomain.com;

    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd-mailhog;

    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';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/mailhog.yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

4.3 Add HTTPS with Let’s Encrypt

Use Certbot to add SSL:

sudo certbot --nginx -d mailhog.yourdomain.com

5: Test the Setup

Visit https://mailhog.yourdomain.com (or http:// if you did not add SSL). You’ll be prompted for the username and password you set up with htpasswd.

Send a test email from your Laravel app. The message should appear in the MailHog inbox.

Summary

MailHog is a simple and powerful tool for testing email flows in development and staging environments. By exposing it securely behind basic auth and reverse proxying with nginx, you can safely access the interface over the web while keeping it restricted from public access.

all posts →