tutorial

Monitoring MailHog with Vigilmon

MailHog is the standard email testing tool for dev and staging environments — but if its SMTP port goes down, your app's email flows break silently. Here's how to monitor MailHog's SMTP server, web UI, and REST API with Vigilmon.

MailHog is the go-to email sandbox for development and staging environments — it catches outgoing SMTP traffic, stores emails in memory, and displays them in a clean web inbox. It sounds low-stakes, but when MailHog's SMTP server goes down in a staging environment and your app silently starts dropping password reset emails, registration confirmations, and notification flows, debugging why can cost hours. Vigilmon monitors MailHog's SMTP port, web UI, REST API, and WebSocket endpoint so you know immediately when email capture breaks.

What You'll Set Up

  • TCP monitor for the SMTP capture port (1025)
  • HTTP uptime monitor for the MailHog web UI (port 8025)
  • REST API health check (/api/v2/messages, port 8025)
  • WebSocket endpoint availability check (real-time email push)
  • Optional: authentication middleware check (if --auth-file is configured)

Prerequisites

  • MailHog running (default: SMTP port 1025, web UI port 8025)
  • A free Vigilmon account

Step 1: Monitor the SMTP Capture Port (TCP)

MailHog's core function is catching SMTP traffic on port 1025. If this port goes down, your application's outgoing emails stop being captured — and depending on your SMTP configuration, they may either fail silently or attempt delivery to real addresses.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to TCP Port.
  3. Host: YOUR_MAILHOG_HOST.
  4. Port: 1025.
  5. Check interval: 1 minute.
  6. Click Save.

A TCP check on port 1025 confirms MailHog's SMTP server is accepting connections. This is the most critical monitor — if it fails, email capture is broken.

Step 2: Monitor the MailHog Web UI

The web inbox runs on port 8025. Monitoring it separately from the SMTP port catches cases where the Go HTTP server crashes while the SMTP listener is still running (possible due to goroutine panics in the web layer):

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://YOUR_MAILHOG_HOST:8025.
  3. Check interval: 2 minutes.
  4. Expected HTTP status: 200.
  5. Click Save.

If MailHog is behind a reverse proxy (nginx, Traefik) with a domain, use the proxied URL and enable Monitor SSL certificate with a 21-day alert threshold.

Step 3: Monitor the REST API (/api/v2/messages)

The MailHog REST API provides programmatic access to captured emails. Monitoring the messages endpoint confirms both the API layer and the in-memory message store are healthy:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://YOUR_MAILHOG_HOST:8025/api/v2/messages.
  3. Check interval: 2 minutes.
  4. Expected HTTP status: 200.
  5. Expected response body contains: total (the response JSON includes "total": for the message count).
  6. Click Save.
# Verify manually
curl -s http://YOUR_MAILHOG_HOST:8025/api/v2/messages | python3 -m json.tool
# Returns: {"total":0,"count":0,"start":0,"items":[]}

The API returns a valid response even with zero messages — "total":0 is a healthy state. Vigilmon's body check on "total" confirms the JSON structure is intact.

Step 4: Monitor the v1 API Endpoint

MailHog also exposes a legacy v1 API on port 1080 (configurable). If you use the v1 API in tests or CI pipelines, add a separate monitor:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://YOUR_MAILHOG_HOST:8025/api/v1/messages (or http://YOUR_MAILHOG_HOST:1080/api/v1/messages if using the legacy port).
  3. Check interval: 5 minutes.
  4. Expected HTTP status: 200.
  5. Click Save.
# Check which port your MailHog uses for the v1 API
curl -sv http://YOUR_MAILHOG_HOST:8025/api/v1/messages 2>&1 | head -5

Step 5: WebSocket Health Check

MailHog pushes new email notifications to the web UI via WebSocket. If the WebSocket endpoint fails, the browser inbox stops updating in real time — users don't see new emails without manual refresh.

MailHog's WebSocket endpoint is at ws://HOST:8025/api/v2/websocket. While Vigilmon doesn't natively probe WebSocket handshakes, you can test the HTTP upgrade path with an HTTP monitor:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://YOUR_MAILHOG_HOST:8025/api/v2/websocket.
  3. Expected HTTP status: 400 (WebSocket endpoints return 400 to plain HTTP GET requests — this confirms the route is alive).
  4. Check interval: 5 minutes.
  5. Click Save.

A 400 response from a WebSocket endpoint is healthy — it means the server received the request and rejected it because it wasn't a valid WebSocket upgrade. A 404 or 502 means the route is missing or the proxy is broken.

Step 6: Authentication Middleware Check (Optional)

If MailHog is started with --auth-file to password-protect the web UI, unauthenticated requests return 401. This is important in staging environments where MailHog is exposed to a broader network:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://YOUR_MAILHOG_HOST:8025.
  3. Expected HTTP status: 401 (when auth is enabled, the root returns 401 without credentials).
  4. Check interval: 5 minutes.
  5. Click Save.

If this monitor returns 200 instead of 401, it means the auth middleware is disabled or bypassed — a security signal worth alerting on in staging environments.

Alternatively, monitor with credentials:

# Verify auth is working
curl -s -o /dev/null -w "%{http_code}" http://YOUR_MAILHOG_HOST:8025
# Should return 401 if auth is enabled

Step 7: SMTP TLS Health Check (Optional)

If MailHog is configured with TLS on the SMTP port (e.g. for testing STARTTLS or SMTPS flows), add a certificate expiry monitor:

# Check SMTP TLS certificate
echo | openssl s_client -starttls smtp -connect YOUR_MAILHOG_HOST:1025 2>/dev/null | \
  openssl x509 -noout -dates

In Vigilmon, add an HTTP monitor for the web UI with SSL certificate monitoring enabled. For the SMTP TLS certificate specifically, set up a script-based heartbeat that checks the cert and pings Vigilmon if it's valid:

#!/bin/bash
# /usr/local/bin/check_mailhog_smtp_tls.sh
EXPIRY=$(echo | openssl s_client -starttls smtp -connect localhost:1025 2>/dev/null | \
  openssl x509 -noout -enddate 2>/dev/null | cut -d= -f2)

if [ -n "$EXPIRY" ]; then
    EXPIRY_EPOCH=$(date -d "$EXPIRY" +%s 2>/dev/null || date -j -f "%b %d %T %Y %Z" "$EXPIRY" +%s)
    NOW_EPOCH=$(date +%s)
    DAYS_LEFT=$(( (EXPIRY_EPOCH - NOW_EPOCH) / 86400 ))
    
    if [ "$DAYS_LEFT" -gt 14 ]; then
        curl -s https://vigilmon.online/heartbeat/YOUR_TLS_HEARTBEAT_ID
    fi
fi

Step 8: Configure Alert Channels

MailHog issues in staging affect developers immediately — a broken SMTP port stops registration flow tests and CI email assertions from passing.

  1. Go to Alert Channels in Vigilmon and add Slack or email for your development team.
  2. For the SMTP TCP monitor (port 1025), set Consecutive failures before alert to 1 — SMTP port loss is immediate and critical.
  3. For the web UI and API monitors, set the threshold to 2 — Go HTTP servers can take a moment to recover from GC pauses.
  4. Route alerts to a #staging-alerts channel rather than a paging channel — MailHog issues are urgent for developers but rarely need 3am wakeups.

Summary

| Monitor | Target | What It Catches | |---|---|---| | SMTP TCP | HOST:1025 | Email capture port down | | Web UI | http://HOST:8025 | Go HTTP server crash | | API v2 messages | http://HOST:8025/api/v2/messages | REST API + message store health | | API v1 messages | http://HOST:8025/api/v1/messages | Legacy API endpoint | | WebSocket route | http://HOST:8025/api/v2/websocket | Real-time push endpoint | | Auth middleware | http://HOST:8025 → expects 401 | Auth bypass detection |

MailHog keeps your development and staging email flows clean and testable — Vigilmon makes sure MailHog itself stays up so your email testing never breaks silently.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles