Mailpit

beginner

Modern email testing tool with API.

Overview

Mailpit is a modern email testing tool designed as a direct replacement for the now-deprecated MailHog. Built with Go and featuring a React-based web interface, Mailpit provides developers with a local SMTP server that captures outgoing emails during development and testing phases. Unlike production mail servers, Mailpit prevents emails from actually being sent while providing a comprehensive interface to view, analyze, and debug email content. This Docker configuration establishes Mailpit as a standalone email testing environment with persistent storage for captured messages. The setup exposes both the SMTP server on port 1025 for applications to send emails and the web interface on port 8025 for developers to review captured messages. The SQLite database storage ensures that email history persists between container restarts, making it suitable for ongoing development workflows. Development teams working on applications with email functionality will find this configuration invaluable for testing registration confirmations, password resets, notifications, and marketing emails without risking accidental sends to real users. QA engineers can verify email content and formatting, while DevOps teams can integrate Mailpit's REST API into automated testing pipelines to validate email delivery in CI/CD workflows.

Key Features

Modern React-based web interface with real-time message updates and search capabilities
SMTP server with STARTTLS encryption and authentication support for secure email capture
SQLite database storage for persistent message history across container restarts
Built-in link checking to validate URLs and detect broken links in email content
HTML email preview with mobile and desktop responsive design testing
REST API endpoints for automated testing and CI/CD integration
Message tagging and filtering system for organizing captured emails
Attachment handling with preview capabilities for common file types

Common Use Cases

1Local development environment for testing user registration and authentication email flows
2QA testing of transactional emails like order confirmations and shipping notifications
3Marketing team preview and approval of newsletter templates and promotional campaigns
4CI/CD pipeline integration for automated email content validation in staging environments
5E-commerce development testing for cart abandonment and purchase confirmation emails
6Educational environments for teaching email integration without external dependencies
7API testing scenarios where email verification is part of the application workflow

Prerequisites

Docker Engine 20.10+ and Docker Compose V2 for container orchestration
At least 100MB available RAM for Mailpit container and SQLite database operations
Ports 1025 and 8025 available on the host system for SMTP and web interface access
Basic understanding of SMTP configuration in your application framework
Web browser with JavaScript enabled for accessing the React-based interface
Familiarity with email headers and MIME structure for debugging email issues

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  mailpit: 
3    image: axllent/mailpit:latest
4    container_name: mailpit
5    restart: unless-stopped
6    ports: 
7      - "1025:1025"
8      - "8025:8025"
9    volumes: 
10      - mailpit_data:/data
11    environment: 
12      MP_DATABASE: /data/mailpit.db
13
14volumes: 
15  mailpit_data:

.env Template

.env

1# More features than MailHog

Usage Notes

1Docs: https://mailpit.axllent.org/docs/
2Web UI at http://localhost:8025 - modern MailHog alternative
3SMTP on port 1025, supports STARTTLS and AUTH
4REST API at /api/v1 for CI/CD email verification
5Link checking, message storage, and HTML preview
6Actively maintained replacement for MailHog

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  mailpit:
5    image: axllent/mailpit:latest
6    container_name: mailpit
7    restart: unless-stopped
8    ports:
9      - "1025:1025"
10      - "8025:8025"
11    volumes:
12      - mailpit_data:/data
13    environment:
14      MP_DATABASE: /data/mailpit.db
15
16volumes:
17  mailpit_data:
18EOF
19
20# 2. Create the .env file
21cat > .env << 'EOF'
22# More features than MailHog
23EOF
24
25# 3. Start the services
26docker compose up -d
27
28# 4. View logs
29docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/mailpit/run | bash

Troubleshooting

Connection refused on port 1025: Verify the container is running and port mapping is correct in docker-compose.yml
Web interface shows 'no messages': Check application SMTP configuration points to localhost:1025, not port 8025
Database locked errors: Stop the container completely before restarting to release SQLite file locks
Messages not persisting between restarts: Ensure mailpit_data volume is properly mounted and has write permissions
STARTTLS connection failures: Verify your application's SMTP client supports opportunistic TLS encryption
API endpoints returning 404: Confirm you're accessing the REST API at http://localhost:8025/api/v1/ with correct HTTP methods

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

mailpit

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download