Mailpit: self-hosted test SMTP server on your VPS

Why replace MailHog with Mailpit

What Mailpit delivers in practice

• Modern interface with full-text search, HTML/text rendering, mobile preview and header inspection
• Single statically compiled Go binary — no system dependencies, runs in a 20 MB container
• Memory footprint below 50 MB at rest, stable even with thousands of messages in a session
• REST API backward compatible with MailHog (/api/v1/messages, /api/v1/search) for existing scripts
• Authenticated SMTP support, optional TLS, and network-based access control
• Configurable webhook to notify an external endpoint on each received email

Prerequisites

Deploy Mailpit in 5 steps

1. 01

   Create the directory and Compose file

   mkdir -p /opt/mailpit && cd /opt/mailpit

   Create the following docker-compose.yml file:

   services:
     mailpit:
       image: axllent/mailpit:latest
       container_name: mailpit
       restart: unless-stopped
       ports:
         - "127.0.0.1:1025:1025"
         - "127.0.0.1:8025:8025"
       environment:
         MP_MAX_MESSAGES: 500
         MP_SMTP_AUTH_ACCEPT_ANY: "true"
         MP_SMTP_AUTH_ALLOW_INSECURE: "true"
         MP_UI_AUTH: "admin:changeme"
       volumes:
         - mailpit_data:/data
   volumes:
     mailpit_data:

   Ports are bound to 127.0.0.1 only: Mailpit is never exposed directly on the public IP. The MP_UI_AUTH variable enables HTTP basic authentication on the web interface — change the password. MP_MAX_MESSAGES limits the number of emails kept in memory per session.

2. 02

   Start the container

   docker compose up -d
   docker compose logs -f mailpit

   The line starting on [::]:1025 confirms the SMTP server is listening. Check that the ports are correctly bound to localhost:

   ss -tlnp | grep -E '1025|8025'

   Expected: 127.0.0.1:1025 and 127.0.0.1:8025 only — never 0.0.0.0.

3. 03

   Configure the Nginx reverse proxy

   Create /etc/nginx/sites-available/mailpit:

   server {
       listen 443 ssl;
       server_name mail.your-domain.com;
   
       ssl_certificate     /etc/letsencrypt/live/mail.your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/mail.your-domain.com/privkey.pem;
   
       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_read_timeout 86400;
       }
   }

   The proxy_read_timeout 86400 is required for WebSocket connections used by the real-time interface. Enable the vhost and reload Nginx:

   ln -s /etc/nginx/sites-available/mailpit /etc/nginx/sites-enabled/
   nginx -t && systemctl reload nginx

   Obtain a Let's Encrypt certificate if not already done:

   certbot --nginx -d mail.your-domain.com

4. 04

   Test sending with curl

   Verify the SMTP server receives a message:

   curl --url 'smtp://127.0.0.1:1025' \
     --mail-from '[email protected]' \
     --mail-rcpt '[email protected]' \
     --upload-file - <<EOF
   From: [email protected]
   To: [email protected]
   Subject: Mailpit Test
   
   Test message body.
   EOF

   Then open https://mail.your-domain.com in your browser. The message should appear in the interface. If you configured MP_UI_AUTH, enter the credentials at the HTTP basic auth prompt.

5. 05

   Configure your application to point to Mailpit

   In your .env file (Laravel, Symfony, n8n, Django…), replace the SMTP configuration with:

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

   For applications running in Docker on the same host, use the Docker network name or the gateway IP (172.17.0.1 by default) instead of 127.0.0.1.

Mailpit in CI/CD: testing emails in the pipeline

CI/CD integration by framework

1. 06

   GitHub Actions — Mailpit service

   services:
     mailpit:
       image: axllent/mailpit:latest
       ports:
         - 1025:1025
         - 8025:8025

   In your job environment variables, set MAIL_HOST=127.0.0.1 and MAIL_PORT=1025. Mailpit accepts any email without authentication by default — no additional SMTP configuration is needed.

2. 07

   Laravel — PHPUnit

   In phpunit.xml, replace the transport with SMTP:

   <env name="MAIL_MAILER" value="smtp"/>
   <env name="MAIL_HOST" value="127.0.0.1"/>
   <env name="MAIL_PORT" value="1025"/>

   In your test, send the mail then query the Mailpit API to verify receipt:

   $response = Http::get('http://127.0.0.1:8025/api/v1/messages');
   $this->assertSame($response->json('total'), 1);
   $this->assertStringContainsString(
       'Welcome',
       $response->json('messages.0.Subject')
   );

3. 08

   Django — pytest

   In settings.py (or settings_test.py):

   EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
   EMAIL_HOST = '127.0.0.1'
   EMAIL_PORT = 1025

   In your pytest test, verify via the Mailpit API:

   import requests
   
   def test_welcome_email_sent():
       # trigger the send in your view/service
       r = requests.get('http://127.0.0.1:8025/api/v1/messages')
       assert r.json()['total'] == 1
       assert 'Welcome' in r.json()['messages'][0]['Subject']

4. 09

   n8n — workflow testing

   In n8n's Send Email node, configure the SMTP server to 127.0.0.1:1025 without authentication. To automatically verify that a workflow triggered a send, call GET http://127.0.0.1:8025/api/v1/messages from an HTTP Request node and validate the total in an IF node.

Securing access to Mailpit

Troubleshooting — 4 common cases

Mailpit vs MailHog vs Mailtrap vs Inbucket vs smtp4dev

Scroll the table

Advanced use cases