tutorial

Monitoring Maddy Mail Server with Vigilmon

Maddy is a composable, all-in-one mail server written in Go. Here's how to monitor Maddy's SMTP, IMAP, and management API with Vigilmon to catch failures before they affect email delivery.

Maddy is a Go-written, composable mail server that handles SMTP, message routing, DKIM signing, spam filtering, and IMAP delivery in a single binary — no Postfix/Dovecot combination required. That lean footprint is operationally elegant, but it means a single process failure takes down your entire mail stack. Vigilmon provides external monitoring across every Maddy-exposed protocol port so you catch failures in seconds rather than minutes.

What You'll Set Up

  • TCP port checks for SMTP, IMAP, and submission ports
  • SMTP banner verification to confirm the mail daemon is responding
  • Health endpoint monitoring (if configured)
  • TLS certificate expiry alerts
  • Alert channels for immediate notification

Prerequisites

  • Maddy installed and running (maddy binary or systemd service)
  • Mail domain configured (e.g. mail.yourdomain.com)
  • SMTP listening on port 25 and/or 587
  • IMAP listening on port 143 and/or 993
  • A free Vigilmon account

Step 1: TCP Port Check for SMTP (Port 25)

Port 25 handles inbound mail from other mail servers. Monitoring it from outside your network verifies that Maddy's SMTP listener is up and your firewall is passing traffic correctly.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to TCP Port.
  3. Host: mail.yourdomain.com, Port: 25.
  4. Set Check interval to 2 minutes.
  5. Click Save.

A TCP failure on port 25 means remote MTAs cannot deliver mail to your domain — your MX records point to a dead socket.

Step 2: SMTP Submission (Port 587) and SMTPS (Port 465)

Port 587 is used by email clients and applications to send outbound mail with STARTTLS. Port 465 is used for implicit TLS submission.

Port 587:

  1. Add Monitor → TCP Port.
  2. Host: mail.yourdomain.com, Port: 587.
  3. Set Check interval to 2 minutes.
  4. Click Save.

Port 465:

  1. Add Monitor → TCP Port.
  2. Host: mail.yourdomain.com, Port: 465.
  3. Click Save.

If port 587 goes down, every email client and application trying to send via Maddy will fail authentication and queue messages locally.

Step 3: IMAP Port Monitoring (Ports 143 and 993)

Maddy's built-in IMAP server stores and serves mail to clients. Monitor both the plain and TLS IMAP ports:

IMAP (port 143):

  1. Add Monitor → TCP Port.
  2. Host: mail.yourdomain.com, Port: 143.
  3. Click Save.

IMAPS (port 993):

  1. Add Monitor → TCP Port.
  2. Host: mail.yourdomain.com, Port: 993.
  3. Click Save.

A failure on port 993 means Thunderbird, Apple Mail, and mobile email clients can't sync — users start getting "connection refused" errors.

Step 4: Verify the SMTP Greeting Banner

A TCP connection to port 25 that never returns a greeting is a Maddy-specific failure mode — the socket opens but the daemon is hung. Verify the SMTP banner to catch this:

  1. Open the SMTP TCP monitor you created in Step 1.
  2. Under Advanced, enable Verify response and set the expected string to 220.
  3. Click Save.

The SMTP 220 greeting must be the first response after the connection is established. If Maddy opens the socket but hangs before greeting, this check catches what a pure TCP check misses.

Step 5: Add a Lightweight HTTP Health Endpoint

Maddy doesn't expose an HTTP health endpoint by default, but you can add one with a small sidecar or use Maddy's control socket. The simplest approach is a shell script checked by a small HTTP server:

#!/bin/bash
# /usr/local/bin/maddy-healthcheck.sh
# Returns 0 if maddy is running, 1 otherwise
systemctl is-active --quiet maddy && echo "ok" || exit 1

Expose this via a lightweight HTTP endpoint using socat or a minimal Go/Python server, then add a Vigilmon HTTP monitor:

  1. Add Monitor → HTTP / HTTPS.
  2. URL: http://mail.yourdomain.com:9090/health (your sidecar's port).
  3. Set Expected HTTP status to 200.
  4. Set Expected body contains to ok.
  5. Set Check interval to 1 minute.
  6. Click Save.

Alternatively, if you run Maddy behind a reverse proxy with a management API, point Vigilmon at that API's health route instead.

Step 6: Monitor Maddy's systemd Service via a Heartbeat

If Maddy runs as a systemd service, set up a Vigilmon Heartbeat monitor that your systemd service pings after each successful startup:

  1. In Vigilmon, go to Add Monitor → Heartbeat.
  2. Give it a name like "Maddy service heartbeat".
  3. Set the expected interval to 5 minutes.
  4. Copy the generated heartbeat URL.
  5. Add a systemd ExecStartPost directive to ping the URL after Maddy starts:
# /etc/systemd/system/maddy.service.d/override.conf
[Service]
ExecStartPost=/usr/bin/curl -fsS --max-time 5 https://hb.vigilmon.online/YOUR_HEARTBEAT_ID
  1. Reload systemd: systemctl daemon-reload && systemctl restart maddy.

If Maddy crashes and restarts unexpectedly, the heartbeat URL is never pinged on schedule and Vigilmon raises an alert.

Step 7: TLS Certificate Expiry Alerts

Maddy uses Let's Encrypt (or manual certificates) for TLS on all mail ports. Expiry takes down SMTPS, IMAPS, and STARTTLS simultaneously.

For each monitor covering a TLS endpoint (SMTPS :465, IMAPS :993):

  1. Open the monitor.
  2. Enable Monitor SSL certificate.
  3. Set Alert when certificate expires in less than 14 days.
  4. Click Save.

Maddy's ACME module auto-renews certificates but requires port 80 or DNS challenge access. Add a TCP monitor on port 80 if Maddy handles ACME directly:

  1. Add Monitor → TCP Port, Host: mail.yourdomain.com, Port: 80.
  2. Click Save.

Step 8: Configure Alert Channels

  1. In Vigilmon, go to Alert Channels → Add Channel.
  2. Choose your preferred channel: Email, Slack, or Webhook.
  3. Assign all Maddy monitors to this channel.
  4. Set Consecutive failures before alert to 2 on port monitors — brief network hiccups during Maddy's own TLS renewal can cause transient TCP failures.

Putting It All Together

Here's a reference Vigilmon monitor set for a standard Maddy deployment:

mail.yourdomain.com:25   → TCP (SMTP inbound)        + SMTP banner: 220
mail.yourdomain.com:587  → TCP (Submission/STARTTLS)
mail.yourdomain.com:465  → TCP (SMTPS)               + SSL cert expiry
mail.yourdomain.com:143  → TCP (IMAP)
mail.yourdomain.com:993  → TCP (IMAPS)               + SSL cert expiry
mail.yourdomain.com:9090 → HTTP /health (sidecar)
Heartbeat                → Maddy systemd restart ping

Summary

| Monitor | Target | What It Catches | |---|---|---| | SMTP | :25 + banner 220 | Inbound delivery broken, hung daemon | | Submission | :587 | Outbound client email broken | | SMTPS | :465 | Secure submission broken | | IMAP | :143 | Mail retrieval failure | | IMAPS | :993 | Secure IMAP failure | | Health sidecar | http://:9090/health | Process down, service stopped | | Heartbeat | Vigilmon heartbeat URL | Unexpected crash without restart | | SSL certificate | :465, :993 | TLS certificate expiry |

Maddy's composable, single-binary design makes deployment simple — Vigilmon's external monitoring makes sure that simplicity doesn't come at the cost of observability.

Get started free at vigilmon.online — no credit card, monitors start running in under a minute.

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