Operations

Monitoring & Health

Cleanmails provides health endpoints and Docker-native monitoring for your instance.

Basic Health Check

bash

curl http://YOUR_SERVER/health

Returns 200 OK with {"status":"ok"} if the API server and PostgreSQL database are healthy. Returns 500 if the database connection is lost or ping fails.

Docker Health Checks

All containers have built-in health checks that Docker monitors continuously:

Service	Health Check	Interval
PostgreSQL	`pg_isready -U cleanmails`	5s
Redis	`redis-cli ping`	5s
API	`curl -f http://localhost:8080/health`	10s
Frontend	`wget --spider http://localhost:3000`	10s

Checking Service Status

bash

cd /opt/cleanmails
docker compose -f docker-compose.prod.yml ps

This shows all containers with their current state and health status.

Queue Monitoring

The admin dashboard includes a Queue Health Monitor at /dashboard/admin/queues showing pending, active, completed, and failed jobs per queue. The background worker uses three priority queues:

Queue	Priority	Tasks
`critical`	6	Bounce/complaint handling
`default`	3	Campaign dispatch, lead validation
`low`	1	IMAP sync, AI replies, warmup

Application Logs

bash

cd /opt/cleanmails

# All services
docker compose -f docker-compose.prod.yml logs -f

# API only
docker compose -f docker-compose.prod.yml logs -f api

# Worker only
docker compose -f docker-compose.prod.yml logs -f worker

# Last 100 lines
docker compose -f docker-compose.prod.yml logs --tail=100 api

Worker Tasks

The worker processes these background tasks (logged at startup):

Task	Description
`imap:sync`	Sync inbound emails from IMAP mailboxes
`imap:schedule_sync`	Schedule periodic IMAP syncs for all mailboxes
`ai:reply`	Generate and send AI auto-replies
`ai:reset_daily_tokens`	Reset daily AI token budgets
`campaign:dispatch`	Send scheduled campaign emails
`system:reset_daily_caps`	Reset daily send limits per mailbox
`webhook:dispatch`	Deliver webhook payloads to subscribers
`leads:validate`	Validate lead email addresses
`system:license_check`	Periodic license validation
`warmup:cycle`	Send warmup emails on schedule
`warmup:reply`	Auto-reply to warmup emails

Resource Usage

bash

# Check memory usage per container
docker stats --no-stream

# Check disk usage
docker system df

Production memory limits are set per container (total ~1.5GB for the full stack). See the Docker Compose page for details.

Common Alerts to Watch

API unhealthy — Check PostgreSQL connectivity and disk space
Worker not processing — Check Redis connectivity and worker logs
High bounce rate — Campaign auto-pauses at 5% bounce rate
IMAP sync failures — Mailbox credentials may have expired
License check failures — Network connectivity to license server