Monitoring Mailpit with Vigilmon

Mailpit is an open-source email testing tool that captures outgoing SMTP traffic and displays it in a clean web UI — the modern successor to MailHog. Development teams route their app's outgoing email through Mailpit's SMTP listener (port 1025) so they can inspect messages without spamming real inboxes. When Mailpit's SMTP server or web interface goes down, your app throws email errors, CI pipelines break, and developers lose visibility into notification content. Vigilmon keeps every Mailpit component under continuous surveillance so you know the moment something breaks.

What You'll Set Up

• Web UI uptime monitor (port 8025)
• SMTP listener TCP port check (port 1025)
• REST API endpoint health monitor (/api/v1/messages)
• Heartbeat for long-running Mailpit process health
• SSL/TLS certificate alert (if Mailpit is TLS-terminated)
• Storage and WebSocket health via API probe

Prerequisites

• Mailpit running as a service (systemd, Docker, or binary)
• Web UI accessible at http://yourhost:8025 (or behind a reverse proxy)
• A free Vigilmon account

Step 1: Monitor the Mailpit Web UI

The web UI at port 8025 is the primary interface developers use to inspect captured emails. If it's unreachable, the email sandbox is effectively offline.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Mailpit web UI URL: http://yourhost:8025 (or https://mail.yourdomain.com if behind a reverse proxy).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

If Mailpit is behind nginx or Caddy with TLS, use the HTTPS URL and enable Monitor SSL certificate with an expiry alert of 21 days.

Step 2: Check the SMTP Listener on Port 1025

The SMTP server is Mailpit's core function. Your application connects here to send test emails. A TCP check confirms the listener is accepting connections even before any email is sent.

1. Click Add Monitor → select TCP Port.
2. Enter your host and port: yourhost:1025.
3. Set Check interval to 1 minute.
4. Click Save.

A TCP failure on port 1025 means your app's SMTP calls will fail immediately. This check fires before your application error logs even mention it.

Step 3: Monitor the REST API Endpoint

Mailpit exposes a REST API at /api/v1/messages that returns the list of captured messages. Monitoring this endpoint validates that the HTTP server is healthy and the storage backend (SQLite or in-memory) is responding.

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://yourhost:8025/api/v1/messages.
3. Set Expected HTTP status to 200.
4. Set Check interval to 2 minutes.
5. Under Response validation, check that the body contains "messages" (a JSON key present in a healthy response).
6. Click Save.

This check catches situations where the web UI serves its HTML shell but the API layer or storage backend has failed, which would cause the message list to never load.

Step 4: Check SMTP Authentication Middleware (if enabled)

If you've started Mailpit with --smtp-auth-required, only authenticated connections are accepted. You can validate this without sending a real email by probing the SMTP greeting:

# Quick manual check — should return Mailpit's SMTP banner
openssl s_client -connect yourhost:1025 -starttls smtp 2>/dev/null | head -5
# Or for non-TLS:
echo "QUIT" | nc yourhost 1025

For automated monitoring, the TCP check in Step 2 already confirms the port is open. If you have a test script that authenticates and sends a probe email, wrap it in a heartbeat:

1. Click Add Monitor → Cron Heartbeat.
2. Set expected interval to 5 minutes.
3. Copy the heartbeat URL.
4. Add to your probe script:

#!/bin/bash
# Send a test email via authenticated SMTP
swaks --to test@localhost --server yourhost --port 1025 \
      --auth-user testuser --auth-password testpass \
      --from probe@localhost --body "Mailpit probe" >/dev/null 2>&1

if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID
fi

Schedule with cron:

*/5 * * * * /opt/mailpit-probe.sh

Step 5: Monitor Storage Disk Space

Mailpit stores captured messages in SQLite (default) or in-memory. Long-running instances accumulate large message databases. Monitor the host's disk space before Mailpit starts failing silently:

1. Click Add Monitor → Cron Heartbeat.
2. Set expected interval to 10 minutes.
3. Copy the heartbeat URL.
4. Create a disk-space probe script:

#!/bin/bash
THRESHOLD=90  # alert above 90% usage
USAGE=$(df /var/lib/mailpit | awk 'NR==2 {print $5}' | tr -d '%')

if [ "$USAGE" -lt "$THRESHOLD" ]; then
  curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID
fi
# If usage >= 90%, the heartbeat is NOT sent, triggering a Vigilmon alert

Schedule every 10 minutes:

*/10 * * * * /opt/mailpit-disk-check.sh

Step 6: Validate WebSocket Real-Time Push

Mailpit uses WebSocket connections to push new email notifications to the browser UI in real time. A WebSocket failure means developers must manually refresh to see new messages. Check that the WebSocket upgrade endpoint is reachable:

1. Add an HTTP / HTTPS monitor for http://yourhost:8025/api/events.
2. Set Expected HTTP status to 200 or 101 (WebSocket upgrade).
3. Set Check interval to 5 minutes.

This ensures the event stream endpoint hasn't silently stopped serving connections.

Step 7: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add your preferred channel (Slack, email, webhook).
2. For development-environment Mailpit, set Consecutive failures before alert to 2 to avoid noise from brief restarts.
3. If Mailpit restarts automatically (e.g., via systemd Restart=always), a single failure followed by a recovery is normal. Two consecutive failures indicate a real problem.

For staging or pre-production Mailpit instances that CI pipelines depend on, set the threshold to 1 for immediate alerting.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI (HTTP) | http://yourhost:8025 | Process crash, port conflict | | SMTP listener (TCP) | yourhost:1025 | SMTP server down, port blocked | | REST API | /api/v1/messages | Storage backend failure, API errors | | Auth probe (heartbeat) | Heartbeat URL | Authentication middleware failure | | Disk space (heartbeat) | Host filesystem | SQLite database filling disk | | WebSocket events | /api/events | Real-time push broken |

Mailpit is a developer infrastructure component — when it's down, application email flows fail and CI pipelines lose their test email verification step. With Vigilmon monitoring the SMTP listener, web UI, REST API, and storage backend, you get instant notification of any Mailpit failure before it blocks your team's work.