Mailpit

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for Mailpit. Select the SecureAnyCloud listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, then create or select a security group. The group must allow inbound port 22 from your management network, inbound ports 80 and 443 from the networks your users use, and inbound port 25 from the application hosts that will send mail.

Leave the root volume at the default size or larger. The image adds a separate data volume for the message database automatically.

Select Launch instance. First-boot initialization takes under a minute after the instance state becomes Running and the status checks pass.

Launch an instance from the SecureAnyCloud Mailpit Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, 443 and 25 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=mailpit-01}]'

On success, the command prints a JSON document. Note the instance ID, then retrieve the public address once the instance is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Connect over SSH with the key pair you selected and the public IP address from Step 2. The SSH login user depends on the operating system of the AMI variant you launched. For Mailpit 1.30 on Ubuntu 24.04, the login user is ubuntu.

The first-boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/mailpit-credentials.txt

The plain-text file contains the Mailpit URL, the username admin, and the per-instance UI password. From the same SSH session, confirm the deployment is healthy. The health endpoint is open and served by nginx.

curl -fsS http://127.0.0.1/healthz

ok

An ok response confirms nginx is fronting the application. Next, confirm the services that make up the stack are running, and check the Mailpit version.

systemctl is-active mailpit nginx mailpit-firstboot /usr/local/bin/mailpit version

active active active /usr/local/bin/mailpit v1.30.3 compiled with go1.26.4 on linux/amd64

Mailpit listens for SMTP on port 25 on all interfaces and serves its UI and API on the loopback interface. Confirm the listeners.

sudo ss -tlnp | grep -E ':25 |:8025 '

LISTEN 0 1024 *:25 *:* users:(("mailpit",pid=1742,fd=8)) LISTEN 0 1024 127.0.0.1:8025 *:* users:(("mailpit",pid=1742,fd=9))

Open a web browser and navigate to http://<public-ip>/. Mailpit protects its web UI with HTTP Basic authentication, so your browser prompts for a username and password. Enter the username admin and the per-instance password from /root/mailpit-credentials.txt.

Mailpit opens on the inbox. It lists every captured message, newest first, with the sender, recipient, subject, size and time received. A search box filters the mailbox. As new mail arrives, the list updates live over the WebSocket.

Configure your application's SMTP settings to send through this instance: host <public-ip>, port 25, with no authentication and no TLS required by default. Every message your application sends is then captured by Mailpit instead of being delivered to a real mail server.

Prove the capture path end to end from the instance itself. Send a test message to the SMTP port, then confirm it appears through the authenticated API. The following command sends one message with the Python standard library.

python3 -c "import smtplib; from email.message import EmailMessage; m=EmailMessage(); m['From']='app@example.com'; m['To']='inbox@example.com'; m['Subject']='Hello from my app'; m.set_content('This message was captured by Mailpit.'); s=smtplib.SMTP('127.0.0.1',25,timeout=10); s.send_message(m); s.quit(); print('sent')"

sent

Now read the mailbox back through Mailpit's REST API, authenticating with the per-instance password. The total field is the number of captured messages.

PW=$(sudo grep '^MAILPIT_PASSWORD=' /root/mailpit-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PW" http://127.0.0.1/api/v1/messages | jq '.total'

1

A non-zero count confirms the message was captured. The same message now appears at the top of the inbox in the web UI.

Select any message in the inbox to open it. Mailpit shows the envelope (From, To, Subject, Date and size) above a set of tabs. The default HTML tab renders the message exactly as an email client would, so you can check layout, images and links. The Text tab shows the plain-text alternative and the Raw tab shows the complete raw source. Use the Download control to download the message or any attachment. The HTML Source, Headers, HTML Check and Link Check tabs sit alongside the others.

Switch to the Headers tab to see every header on the message, with a filter box to jump to a specific one. This is where you confirm details such as Content-Type, Message-Id, Return-Path and the Received trace that Mailpit added when it accepted the message over SMTP.

Mailpit analyzes an HTML message for email-client compatibility and for broken links. Open the HTML Check tab to see an overall support score. It also shows a breakdown across email clients and platforms such as Outlook, macOS, iOS, Android and webmail, and a list of the HTML and CSS features in the message that are only partially supported.

Open the Link Check tab to validate every link and image URL in the message. The tab reports any that fail.

For any deployment reachable beyond a trusted network, serve Mailpit over HTTPS. This keeps the Basic-auth credentials and the WebSocket the live message list uses from being intercepted. The image ships with nginx, which certbot can configure automatically.

The following commands assume you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d mailpit.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

certbot obtains a certificate and rewrites the nginx server block to serve HTTPS and redirect HTTP. The WebSocket upgrade headers already in the site are preserved. The certbot systemd timer renews the certificate automatically.

Scope the security group rule for port 25 to the application hosts that need to send mail, so the SMTP port is reachable only from those sources.

The UI password is stored as an htpasswd bcrypt credential in /etc/mailpit/ui-auth. To set your own password, write a new bcrypt entry for the admin user and restart Mailpit. Replace <new-password> with the password you want.

sudo htpasswd -bB /etc/mailpit/ui-auth admin '<new-password>'
sudo systemctl restart mailpit

The -B flag stores the password as a bcrypt hash, and -b takes it from the command line so the update is scriptable. Mailpit reads the file at startup, so the new password takes effect as soon as the service restarts. To have htpasswd prompt for the password interactively, omit -b and the password argument.

Mailpit keeps its SQLite message store under /var/lib/mailpit on the dedicated data volume. Confirm that the store sits on its own disk.

df -h /var/lib/mailpit | tail -1

/dev/nvme1n1 20G 724K 19G 1% /var/lib/mailpit

Because the store is on a separate EBS volume, you can take a coordinated EBS snapshot of it for point-in-time backups. Alternatively, archive the store to object storage.

sudo systemctl stop mailpit
sudo tar czf <backup-dir>/mailpit-$(date +%F).tgz -C /var/lib mailpit
sudo systemctl start mailpit

Ship the archive to an Amazon S3 bucket or another object store. Mailpit runs under systemd with a restart policy. You can empty the captured mailbox at any time, either from the UI or by deleting the store while the service is stopped. Check the service state.

systemctl is-active mailpit nginx

active active

• Scale up: Increase the instance size for a busy shared inbox. Mailpit stays responsive because it stores mail in SQLite and streams new messages over the WebSocket.
• Restrict SMTP: Scope the port 25 security group rule to only the application hosts that need to send mail. Keep the UI on 80/443 behind your management network or a load balancer.
• Load balancing: Put the web tier behind an Application Load Balancer and terminate TLS there. Forward the WebSocket upgrade so the live message list connects, and use the open /livez and /readyz endpoints for target health checks.
• Storage: Grow the data volume by extending the EBS data volume and running sudo resize2fs on /var/lib/mailpit.
• Testing: Wire the REST API on /api/v1/messages into your automated integration tests to assert that a message was sent. Delete the message between test runs.
• Versioning: Pin the Mailpit version for a fleet by controlling which AMI version you launch.

The official Mailpit documentation is available at https://mailpit.axllent.org/docs/.