Configuration

Environment Variables

Cleanmails is configured entirely through environment variables. These are set in your .env file (located at /opt/cleanmails/.env after installation).

MASTER_KEY is required in production

The MASTER_KEY must be exactly 16, 24, or 32 characters. It's used for AES encryption of passwords and tokens. Generate with: openssl rand -hex 16

Core Settings

Variable	Default	Description
`APP_ENV`	development	Set to `production` for production deployments
`ADDR`	:8080	Server listen address (auto-switches to :80 in production)
`MASTER_KEY`	—	Required. AES encryption key (16/24/32 chars)
`SITE_URL`	http://localhost:8080	Public URL of your instance (used for tracking links)
`PUBLIC_DIR`	./public	Path to the frontend static files
`TRUST_PROXY`	false	Trust X-Forwarded-For header (set true behind Caddy/Nginx)

SMTP Verification

Variable	Default	Description
`SMTP_FROM_EMAIL`	user@example.org	MAIL FROM address for SMTP checks
`SMTP_HELO_NAME`	localhost	HELO/EHLO hostname for SMTP checks
`SMTP_CONNECT_TIMEOUT`	10s	TCP connection timeout
`SMTP_OPERATION_TIMEOUT`	10s	SMTP command timeout
`SMTP_CATCH_ALL`	true	Enable catch-all detection
`LOCAL_IPS`	—	Comma-separated IPs for rotation

Validation Engine

Variable	Default	Description
`MAX_EMAILS`	100000	Max emails per bulk request
`LEVEL1_CONCURRENCY`	1000	Concurrent Level 1 checks
`LEVEL2_CONCURRENCY`	100	Concurrent Level 2 (SMTP) checks
`JOB_CONCURRENCY`	200	Default workers per bulk job
`VALIDATION_RATE`	20.0	Emails/second rate limit for SMTP checks
`RATE_JITTER`	0.1	Random jitter (±10%) on rate limit
`RESULT_TTL`	15m	How long bulk results are kept in memory
`STORE_RESULTS`	true	Store results for later retrieval

Outreach Workers

Variable	Default	Description
`OUTREACH_WORKERS`	50	Number of concurrent email sending workers
`OUTREACH_BUFFER`	5000	Task queue buffer size
`OUTREACH_BATCH_SIZE`	100	Leads processed per campaign tick
`VALIDATION_WORKERS`	20	Workers for list validation
`VALIDATION_BUFFER`	50000	Validation task queue size

Mail Server (Mailcow/docker-mailserver)

Variable	Default	Description
`MAILCOW_URL`	—	Mailcow API URL (or `docker-exec` for docker-mailserver)
`MAILCOW_KEY`	—	Mailcow API key (or `docker-exec`)
`MAILCOW_SMTP_HOST`	localhost	SMTP host for internal mailboxes
`MAILCOW_IMAP_HOST`	localhost	IMAP host for reply checking
`MAIL_HOSTNAME`	mail.localhost	Mail server hostname (for HELO, rDNS)

AI & Warmup

Variable	Default	Description
`AI_RATE_LIMIT`	10	Gemini API calls per second
`WARMUP_REPLY_MIN_DELAY`	5m	Min delay before warmup auto-reply
`WARMUP_REPLY_MAX_DELAY`	30m	Max delay before warmup auto-reply

HTTP & Security

Variable	Default	Description
`READ_TIMEOUT`	30s	HTTP read timeout
`WRITE_TIMEOUT`	30s	HTTP write timeout
`MAX_REQUEST_BODY_MB`	10	Max request body size in MB
`BLACKLIST_CHECK_INTERVAL`	4h	How often to check IP blacklists