tutorial

Monitoring Inbucket Email Testing Infrastructure with Vigilmon

Inbucket is a fast, self-hosted email testing server with SMTP, POP3, and a REST API — but a crashed SMTP listener silently drops your test emails. Here's how to monitor every Inbucket interface with Vigilmon.

Inbucket is a lightweight, zero-dependency email testing server written in Go. It accepts all inbound SMTP, stores messages in memory or on disk, and exposes them via a clean web UI, a REST API, and a POP3 server for email client testing. It's the fastest path from "my app sends email" to "did that email actually arrive?" — but Inbucket has no built-in alerting when its own services fail. A crashed SMTP listener silently drops test emails, broken REST API responses leave CI pipelines waiting, and a downed web UI blocks your team from inspecting messages. Vigilmon covers every Inbucket interface so you find out when something is wrong before your developers do.

What You'll Set Up

  • SMTP server availability (port 2500)
  • Web UI availability and response time (port 9000)
  • POP3 server availability (port 9001)
  • REST API endpoint health (/api/v1/mailbox and /api/v1/message)
  • WebSocket push notification endpoint health
  • Admin/metrics endpoint monitoring

Prerequisites

  • Inbucket running (Docker or binary) with SMTP on 2500, web UI on 9000, POP3 on 9001
  • A free Vigilmon account

Step 1: Monitor the Inbucket Web UI (Port 9000)

The Inbucket web UI is the primary interface for browsing received test emails. Monitor it first — a failing UI is immediately visible to your team.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Inbucket URL: http://inbucket.yourdomain.com:9000 or http://localhost:9000.
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Enable Keyword match: Inbucket (appears in the page title).
  7. Click Save.

Also set a response time threshold:

  • Enable Response time threshold and alert at 1000 ms — Inbucket's Go HTTP server responds in single-digit milliseconds under normal conditions. A 1-second latency indicates resource exhaustion.

Step 2: Monitor the SMTP Server (Port 2500)

The SMTP listener is the most critical Inbucket component. Without it, no test emails arrive and your application's email flow appears broken.

Use Vigilmon's TCP port monitor:

  1. Click Add Monitor → TCP Port.
  2. Host: inbucket.yourdomain.com (or localhost).
  3. Port: 2500.
  4. Check interval: 1 minute.
  5. Timeout: 5 seconds.
  6. Click Save.

A TCP monitor at port 2500 confirms the SMTP listener is accepting connections — it won't catch misrouted email, but it immediately detects a crashed smtpd goroutine.

For more thorough validation, use an SMTP banner check via Vigilmon's TCP Port with keyword option if available, or a custom HTTP probe via the Inbucket metrics endpoint (Step 6).

Step 3: Monitor the POP3 Server (Port 9001)

Inbucket's POP3 server lets email clients connect to retrieve messages — useful for testing full email client flows. Monitor it with a TCP check:

  1. Click Add Monitor → TCP Port.
  2. Host: inbucket.yourdomain.com.
  3. Port: 9001.
  4. Check interval: 2 minutes.
  5. Timeout: 5 seconds.
  6. Click Save.

POP3 is less frequently used than the REST API and web UI, but it's the component most likely to crash silently in low-memory conditions because it shares the same process.

Step 4: Monitor the REST API — Mailbox Endpoint

Inbucket's REST API is used by CI pipelines and test frameworks to retrieve and assert on received email. The /api/v1/mailbox endpoint is the primary integration point:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://inbucket.yourdomain.com:9000/api/v1/mailbox/healthcheck (Replace healthcheck with any mailbox name — Inbucket returns an empty array for non-existent mailboxes, not an error.)
  3. Check interval: 2 minutes.
  4. Expected HTTP status: 200.
  5. Enable Keyword match: [ — Inbucket returns a JSON array, so the response always starts with [.
  6. Click Save.

This confirms the REST API handler is alive and the JSON response pipeline is functioning end-to-end.

Step 5: Monitor the Message Retrieval API

The message retrieval endpoint (/api/v1/message) is the second critical REST path — it's what test code uses to read email content for assertion:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://inbucket.yourdomain.com:9000/api/v1/mailbox/healthcheck
  3. Check interval: 5 minutes.
  4. Expected HTTP status: 200.
  5. Click Save.

You can differentiate this monitor by label from Step 4 — name it Inbucket REST API — message endpoint to distinguish alerts.

Step 6: Monitor the Metrics / Admin Endpoint

Inbucket exposes runtime metrics at /api/v1/server/info (or /metrics depending on version). Use this for a deeper health signal than a simple HTTP 200:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://inbucket.yourdomain.com:9000/api/v1/server/info
  3. Check interval: 5 minutes.
  4. Expected HTTP status: 200.
  5. Enable Keyword match: "version" — appears in all Inbucket server info responses.
  6. Click Save.

The server info endpoint also exposes uptime, storage mode (memory vs disk), and SMTP/POP3 connection counts. A change from 200 to 500 here is a strong indicator of internal goroutine panic.

Step 7: Cron Heartbeat for Expiry Job Monitoring

Inbucket can be configured to expire old messages on a schedule. If this job stops running, disk usage (in disk-mode) or memory usage (in memory-mode) grows unbounded. Use Vigilmon's cron heartbeat to track it:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set expected ping interval to your Inbucket sweepInterval setting (e.g., 60 minutes).
  3. Copy the heartbeat URL.
  4. If you've wrapped Inbucket in a custom startup script or systemd service, add the heartbeat ping after each successful sweep cycle:
#!/bin/bash
# Inbucket sweep wrapper
/usr/local/bin/inbucket &
INBUCKET_PID=$!

while kill -0 $INBUCKET_PID 2>/dev/null; do
    sleep 3600
    curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID
done

If Inbucket's sweep goroutine crashes, the heartbeat stops and Vigilmon alerts after the expected interval.

Step 8: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook pointed at your team's incident channel.
  2. For the SMTP and POP3 TCP monitors: Consecutive failures before alert = 1 — there's no reason for these to flap, so alert immediately.
  3. For the web UI and REST API monitors: Consecutive failures before alert = 2 — one failed check may be a transient network hiccup between your monitoring location and Inbucket.
  4. For the cron heartbeat: accept Vigilmon's default — it alerts as soon as the interval is missed.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | :9000 | UI process crash, slow response | | SMTP server | :2500 TCP | SMTP listener crash | | POP3 server | :9001 TCP | POP3 listener crash | | REST API (mailbox) | :9000/api/v1/mailbox/* | API handler failure | | Server info | :9000/api/v1/server/info | Internal panic, version check | | Cron heartbeat | Heartbeat URL | Message expiry job crash |

Inbucket's simplicity is its strength — but that simplicity means no built-in health dashboard. With Vigilmon probing SMTP, POP3, and the REST API independently, you get per-component visibility instead of "Inbucket is broken" without knowing which part.

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