Install Mailpit on CasaOS with the official axllent/mailpit Docker image, port 8025 for the web inbox, and port 1025 for SMTP. Persist /data only if you want messages and settings to survive container recreation.
The old BigBearCasaOS tutorial is still useful as a one-click example, but current upstream Mailpit documentation now provides the exact Docker image, persistent database option, authentication options, and TLS/relay settings. Those should define the 2026 guide.
What Mailpit Is For
Mailpit is a local SMTP testing server for developers. Applications send test email to Mailpit instead of a real mail provider, and you inspect messages through a browser.
It is not a normal production mailbox or internet-facing mail server.
Use the Official Docker Image
The current Mailpit Docker guide documents:
axllent/mailpitCasaOS Port Mapping
- 8025/TCP: Mailpit Web UI
- 1025/TCP: SMTP receiver
If another service already uses either host port, change the host-side port while keeping the container-side port unchanged.
Basic CasaOS Custom App Settings
image: axllent/mailpit
restart: unless-stopped
ports:
- "8025:8025"
- "1025:1025"After startup, open http://CASAOS-IP:8025.
Point Your Application at Mailpit
For another container on the same Docker network, use the Mailpit service/container name and port 1025. For a LAN application, use the CasaOS host IP and the published SMTP host port.
Persist Messages Only If You Need To
Current Mailpit docs support a SQLite database under /data using:
MP_DATABASE=/data/mailpit.dbMap a CasaOS AppData folder to /data if you want message history to survive container replacement.
Keep Mailpit Private
A test inbox can contain password-reset links, API notifications, and application data. Do not expose the Web UI or unauthenticated SMTP listener directly to the internet.
Current Mailpit configuration guide documents HTTP, SMTP, and POP3 authentication plus TLS options.
When You Do Not Need to Publish Port 1025
If only containers on the same Compose network send mail to Mailpit, you can omit the host publication for SMTP and keep it internal to Docker.
The Docker networking guide explains the same isolation model.
Test the SMTP Path Before Wiring It into Your App
After Mailpit starts, confirm the web UI opens and then send one test message from a simple SMTP client or your application. If the message appears instantly in the Mailpit inbox, both the network path and SMTP listener are working.
If the application reports connection refused, confirm it is using the correct hostname from its own network context. A container should usually use the Mailpit service name; a laptop on the LAN should use the CasaOS host IP.
Use Authentication Only When Your Test Requires It
Mailpit can accept unauthenticated SMTP for simple local development, but current configuration options also support SMTP authentication and UI authentication. Enable those when multiple users share the lab or when the service is reachable beyond a single trusted Docker network.
Keep Test Mail Separate from Production Mail
Mailpit is designed to capture messages so they do not accidentally reach real users. Point development and staging applications at Mailpit explicitly, and keep production SMTP credentials in a separate configuration. This prevents a test reset-password email or notification flood from reaching customers.
Set a Message Limit for Long-Running Labs
Mailpit can retain thousands of messages. In a continuously running CI or homelab environment, set a sensible maximum and persist only what you actually need. Otherwise a small testing tool can slowly become another database you have to maintain.
FAQ
What are Mailpit's default ports?
8025 for the web interface and 1025 for SMTP.
Does Mailpit send real email?
Its main role is capturing test email locally. It can be configured for forwarding/relaying, but that is a separate explicit setup.
Do I need a database?
No for temporary testing. Use the SQLite database option if you want persistent message history.
Should I expose Mailpit publicly?
No. Keep it on a trusted network or protect it with authentication and TLS.
