Knowledgebase

The Mailcow Fail2ban Manager script allows you to review and manage banned IPs from your Mailcow server using a web-based interface. It also supports email-based magic links for secure login without credentials.

Requirements

• A working Mailcow instance
• API key from your Mailcow admin panel
• A web server (e.g., Apache/Nginx with PHP 7.4+)
• SMTP credentials for sending magic links (optional, but recommended)

Step 1: Upload the Script

1. Unzip the downloaded archive mailcow-fail2ban.zip.
2. Upload the contents to your desired location on your web server (e.g., /var/www/html/blocklist).

Step 2: Configure config.php

Navigate to the /includes/ directory and open config.php. You’ll need to update the following fields:

<?php
// Base URL of the Mailcow instance (no trailing slash)
$mailcow_base_url = 'https://mail.domain.com';

// Mailcow API Key from the Admin UI
$mailcow_api_key = '######-######-######-######-######';

// Optional password protection for access
$password_protect = 'password';

// Site URL for generating magic login links (no trailing slash)
$site_base_url = 'https://blocklist.domain.com';
$site_name = 'Blocklist Manager';

// SMTP settings for magic link email delivery
$smtp_host = 'mail.domain.com';
$smtp_port = 587;
$smtp_user = 'noreply@mail.domain.com';
$smtp_pass = '###########';
$from_email = 'noreply@mail.domain.com';
$from_name = 'Mailcow IP Manager';
?>
  

???? Tip: For security, restrict access to this script using .htaccess, IP restrictions, or password protection.

Magic Link Authentication (Optional)

The script supports passwordless login via magic email links. To use this feature:

1. Configure your SMTP credentials in config.php as shown above.
2. Ensure your server is allowed to send outbound email.
3. Test by entering your email on the login page. A link will be sent to authenticate.

Security Recommendations

• Set proper file and directory permissions.
• Consider placing the script behind basic HTTP authentication.
• Keep your Mailcow API key secret and rotate it if needed.

You're Done!

Once the config is saved, navigate to the script’s URL in your browser (e.g., https://blocklist.domain.com) and login with your magic link or password.

For further support or feature requests, please contact your system administrator or consult the README file included in the ZIP.