Operations

Monitoring & Health

Cleanmails provides health endpoints and runtime metrics for monitoring your instance.

Basic Health Check

bash

curl http://YOUR_SERVER/health

Returns 200 OK with {"status":"ok"} if the server and database are healthy. Returns 503 if the database is unreachable.

Detailed Outreach Health

bash

curl http://YOUR_SERVER/v1/outreach/health \
  -H "Cookie: auth_token=YOUR_SESSION"

Returns comprehensive system status:

json

{
  "status": "healthy",
  "checks": {
    "port_25_outgoing": true,
    "database": "connected"
  },
  "runtime": {
    "goroutines": 142,
    "heap_alloc_mb": 45.2,
    "sys_mb": 120.8,
    "gc_cycles": 234
  },
  "queues": {
    "outreach_pending": 12,
    "validator_pending": 0
  },
  "counts": {
    "total_deliveries": 15420,
    "active_campaigns": 3,
    "active_senders": 8
  }
}

Port 25 Monitoring

Cleanmails automatically checks port 25 connectivity every 30 minutes. If your VPS provider blocks it after deployment, the system detects this and logs a warning. Email validation and sending will be degraded until port 25 is restored.

Application Logs

Logs are written to both stdout and cleanmails.log. Every HTTP request is logged with method, path, and duration.

bash

# Docker
docker compose logs -f cleanmails

# Systemd
journalctl -u cleanmails -f

# Log file
tail -f /opt/cleanmails/cleanmails.log

Key Log Prefixes

Prefix	Meaning
`[Init]`	Startup messages (port 25 status, Mailcow, public IP)
`[Worker]`	Outreach worker activity (sends, errors, retries)
`[Warmup]`	Warmup email activity
`[Auth]`	Login attempts, lockouts, session cleanup
`[AI]`	Gemini API calls and errors
`[Webhooks]`	Webhook delivery attempts and failures
`[Monitor]`	Port 25 status changes
`[DB]`	Database initialization and migrations
`[HTTP]`	Request logging (method, path, duration)