A Python-based web application for managing mail aliases on a Mailcow instance. Built with Flask and a dark theme interface for internal network use. This application uses malias as base. Malias it self is a CLI application for managing aliases on a Mailcow Instance. If you already are using the CLI instance you can copy the the DB file over to your /data directory and you'll keep you API key etc. If you start with a blank DB you can use the Sync Aliases function to populate existing aliases to your local db.

Features

Dark-themed user interface
Simple password authentication
Manage Mailcow mail aliases through a web interface
List all aliases on your Mailcow server (paginated view)
Search for aliases in local database
Create new permanent aliases
Create time-limited aliases (1 year validity)
Delete existing aliases
Sync aliases from Mailcow server to local database
View all mail domains

Setup Instructions

Option A: Docker (Recommended)

1. Download the docker-compose.yml file

Download docker-compose.yml to your preferred directory.

2. Start the application

docker compose up -d

The application will be available at: http://localhost:5172

3. View logs (optional)

docker compose logs -f

4. Stop the application (when needed)

docker compose down

Option B: Manual Python Installation

1. Create a virtual environment (recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

3. Run the application

python app.py

The application will be available at: http://localhost:5172

Configuration

1. Access Mode Configuration

The application supports two access modes:

Direct Access (Default) - Access via IP:port

Set ENABLE_PROXY=false in docker-compose.yml (default)
Access at: http://your-server-ip:5172
Works over HTTP (no HTTPS required)
Login: Enter app password
Perfect for internal/LAN access

Proxy Access - Access via reverse proxy (Authelia, Nginx, Traefik, etc.)

Set ENABLE_PROXY=true in docker-compose.yml
Access at: https://alias.yourdomain.com (through your proxy)
Requires HTTPS
Login: Automatic when using Authelia (no password needed!)
See PROXY_SETUP.md for detailed configuration

To switch modes:

Edit docker-compose.yml and change ENABLE_PROXY value
Restart: docker compose down && docker compose up -d
Clear browser cookies and login again

2. Configure Mailcow Connection

You can configure your Mailcow server connection either:

Option A: Using the web interface (Recommended)

Click the "Configuration" button in the web interface
Enter your Mailcow server (e.g., mail.example.com without https://)
Enter your Mailcow API key
Click Save

Option B: Using malias.py directly

python3 malias.py -s your.mailcow.server YOUR_API_KEY

2. Initial Sync

After configuring the connection, sync your aliases from the Mailcow server:

Click the "Sync Aliases" button in the web interface
This will populate the local database with your existing aliases

Navigate to the login page
Enter the default password: admin123
You'll be redirected to the main application
IMPORTANT: Immediately go to Configuration and change your password!

4. Change Default Password

After first login:

Click the "Configuration" button
Scroll to "Change Password" section
Enter current password: admin123
Enter your new password (minimum 6 characters)
Confirm your new password
Click "Change Password"

The password is stored encrypted in the database using bcrypt hashing.

Usage

Available Functions

List All Aliases

Shows all aliases in a paginated table (20 per page)
Navigate through pages using Previous/Next buttons

Sync Aliases

Synchronizes aliases from Mailcow server to local database
Run this periodically to keep local database up to date

Show Domains

Lists all mail domains configured on your Mailcow instance

Create Alias

Opens a dialog to create a new permanent alias
Enter the alias email (e.g., alias@example.com)
Enter the destination email where mail should be forwarded

Delete Alias

Opens a dialog to delete an existing alias
Enter the alias email to remove

Create Timed Alias

Creates a time-limited alias (valid for 1 year)
Enter the destination email (where the mail goes)
Enter the domain to create the alias on
The system will generate a unique timed alias

Search Aliases

Search for aliases in the local database
Searches both alias addresses and destination addresses
Results show matching aliases with their destinations

Configuration

Configure your Mailcow server address and API key
Server address should be without https:// (e.g., mail.example.com)
Change your application password for security

Mailcow API Integration

This application integrates with your existing malias.py script, which provides:

Connection to Mailcow API
Local SQLite database for caching aliases
CRUD operations for mail aliases
Time-limited alias creation
Search and sync functionality

The web interface provides a user-friendly way to access these functions without using the command line.

Security Note

This application uses password authentication with bcrypt hashing and is designed for internal network use. Security features:

Passwords are hashed using bcrypt before storage
Session-based authentication
Password change functionality
Minimum password length enforcement (6 characters)

For production use on a public network, consider implementing:

HTTPS/TLS encryption
More robust authentication mechanisms (2FA, OAuth, etc.)
Rate limiting for login attempts
Session timeout configuration
Account lockout after failed attempts

Do not expose this application to the public internet without additional security measures, particularly HTTPS.

Docker Details

The application runs in Docker with persistent data storage.

Data Persistence

Your data is stored in the ./data directory on your host machine:

malias2.db - Database containing aliases and configuration
malias2.log - Application logs

This directory persists across container restarts and updates.

Customization

You can customize the timezone by editing docker-compose.yml:

environment:
  - TZ=Europe/Oslo  # Change to your timezone

You can change the port by editing docker-compose.yml:

ports:
  - "8080:5172"  # Change 8080 to your preferred port

Useful Docker Commands

View logs:

docker compose logs -f

Restart:

docker compose restart

Stop:

docker compose down

Update to newer version:

docker compose pull
docker compose up -d

Environment Variables:

You can customize the timezone in docker-compose.yml:

environment:
  - TZ=Europe/Oslo  # Change to your timezone

Docker Commands:

Build and start (development):

docker-compose up -d

View logs:

docker-compose logs -f mailcow-alias-manager

Restart:

docker-compose restart

Stop:

docker-compose down

Rebuild after code changes:

docker-compose up -d --build

Documentation

README.md - Main documentation (this file)
DOCKER.md - Docker usage guide for end users

What You Need

For Docker deployment:

docker-compose.yml - The only file you need to download
Docker and Docker Compose installed on your system

The application will automatically:

Pull the Docker image
Create the data/ directory for your database
Start on port 5172

For manual Python installation:

All application files from the repository
Python 3.11 or higher

Troubleshooting

"Error: No mailcow server or API key registered"

Make sure you've configured the Mailcow server and API key in the Configuration page
The API key must have permissions to manage aliases on your Mailcow instance

Search returns no results

Make sure you've run "Sync Aliases" first to populate the local database
The search only searches the local database, not the live Mailcow server

Connection errors

Verify your Mailcow server is accessible from the machine running this app
Check that the API key is valid and has the correct permissions
Review logs in data/malias2.log

License

This project is licensed under the MIT License - see the LICENSE file for details.

README.md

Mailcow Alias Manager Web Interface..