License Activation

Cleanmails requires a valid license key to operate. The license is verified during the onboarding wizard and periodically checked by a background task.

Activating Your License

License activation happens during the onboarding wizard (Step 1):

1. Open your Cleanmails instance in a browser
2. Enter your license key on the first step of the setup wizard
3. The system validates the key against the license server
4. On success, proceed to branding and admin account creation

License Validation

A periodic background task (system:license_check) re-validates your license against the license server. Behavior:

• Server unreachable: License remains active (fail-safe, no disruption)
• License valid: Normal operation continues
• License revoked: The license guard middleware blocks all API routes with a 403 response

License Guard

A middleware runs on every API request that checks the license status stored in the database. If the license is marked as revoked, all endpoints (except health and setup) return:

{"error": "License revoked or expired"}

What Requires a License

All authenticated API endpoints are protected by the license guard. Without an active license:

• Campaigns cannot be created or started
• Leads cannot be uploaded or validated
• Mailboxes cannot be added
• Warmup pool registration fails
• AI features are disabled
• System updates are blocked

Always Accessible (No License Required)

• GET /health — System health check
• /api/v1/setup/* — Onboarding wizard endpoints
• /api/v1/auth/login — Login
• /api/v1/auth/register — Registration
• Tracking pixels, click redirects, unsubscribe pages