Knowledgebase

Table of Contents

1. System Requirements
2. Installation
3. Configuration
4. Using the Tool
5. Features Overview
6. Troubleshooting
7. Security Considerations

System Requirements

Before installing the Mailcow Import Export Tool, ensure your system meets the following requirements:

• PHP Version: 7.4 or higher
• Mailcow: Working Mailcow installation with API access enabled
• Web Server: Apache, Nginx, or similar with PHP support
• Extensions: PHP cURL extension enabled
• Permissions: Write access to the installation directory
• API Access: Valid Mailcow API key with appropriate permissions

Installation

Step 1: Download and Extract

1. Download the Mailcow Import Export Tool package from your account
2. Extract the ZIP file to a temporary location
3. You should see the following file structure:
    

   mailcow-import-export/
   ├── index.php
   ├── export.php
   ├── mailbox_import.php
   ├── domain_import.php
   ├── domain.php
   ├── outbound.php
   ├── sync.php
   ├── includes/
   │   ├── config.php
   │   └── functions.php
   ├── css/
   │   ├── custom.css
   │   └── mailcow-darkmode.css
   └── README.md

Step 2: Upload Files

1. Upload all files to your web server
2. Choose a directory that's accessible via web browser but secure
3. Recommended locations:
   • /var/www/html/mailcow-tools/
   • /home/user/public_html/admin/mailcow/
   • Or any subdirectory on your domain

Step 3: Set Permissions

Ensure proper file permissions are set:

# Set directory permissions
chmod 755 /path/to/mailcow-tools/

# Set file permissions
chmod 644 /path/to/mailcow-tools/*.php
chmod 644 /path/to/mailcow-tools/includes/*.php
chmod 644 /path/to/mailcow-tools/css/*.css

# Make sure the web server can read the files
chown -R www-data:www-data /path/to/mailcow-tools/

Configuration

Step 1: Obtain Mailcow API Key

1. Log into your Mailcow admin interface
2. Navigate to System > Configuration > API
3. Enable API access if not already enabled
4. Generate a new API key or use an existing one
5. Copy the API key - you'll need it for configuration

Step 2: Configure the Tool

Edit the includes/config.php file with your specific settings:

<?php
// includes/config.php

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

// Mailcow API key with appropriate permissions
$mailcow_api_key = 'YOUR_API_KEY_HERE';

// Password to protect access to the tool
$password_protect = 'YOUR_SECURE_PASSWORD_HERE';

// Optional: Site name for branding
$site_name = 'Mailcow Management Tools';

// Optional: Base URL for magic links (if using Fail2ban manager)
$site_base_url = 'https://tools.yourdomain.com';
?>

Step 3: Configuration Parameters Explained

• $mailcow_base_url: The full URL to your Mailcow instance (without trailing slash)
• $mailcow_api_key: Your Mailcow API key with read/write permissions
• $password_protect: A strong password to protect access to the tool
• $site_name: Optional branding for the tool interface
• $site_base_url: Base URL for generating links (used in some features)

Step 4: Test Installation

1. Navigate to your tool URL in a web browser
2. You should see a login screen requesting the password
3. Enter the password you configured in $password_protect
4. If successful, you'll see the main tool interface

Using the Tool

Main Interface

The tool provides a tabbed interface with the following sections:

1. Import Mailcow Aliases - Bulk import email aliases
2. Export Mailcow Aliases - Export existing aliases to CSV
3. Import Mailcow Mailboxes - Bulk import mailboxes
4. Import Mailcow Domains - Bulk import domains
5. Domain Analyzer - Analyze and troubleshoot domains
6. Outbound Monitor - Monitor outbound email activity
7. Sync Manager - Synchronize and maintain consistency

Importing Aliases

Method 1: Manual Entry

1. Click on Import Mailcow Aliases
2. Select Manual Entry radio button
3. Fill in the alias email and recipient email fields
4. Click Add Another Alias to add more entries
5. Click Submit to process

Method 2: Bulk CSV Import

1. Select Bulk Upload via Text radio button
2. Paste CSV data in the format:
    

   alias1@yourdomain.com,recipient1@yourdomain.com
   alias2@yourdomain.com,recipient2@yourdomain.com
   alias3@yourdomain.com,recipient3@yourdomain.com

3. Click Submit to process all entries

Exporting Aliases

1. Navigate to Export Mailcow Aliases
2. Select export criteria (domain, date range, etc.)
3. Choose export format (CSV recommended)
4. Click Export to download the file

Importing Mailboxes

1. Go to Import Mailcow Mailboxes
2. Prepare CSV data with columns:
    

   username,password,domain,quota,active
   user1,SecurePass123,yourdomain.com,5120,1
   user2,AnotherPass456,yourdomain.com,2048,1

3. Paste data or upload CSV file
4. Configure default settings (quota, active status)
5. Click Import to process

Importing Domains

1. Navigate to Import Mailcow Domains
2. Prepare domain list or CSV with domain configurations
3. Set default parameters (quota limits, relay settings)
4. Submit for processing

Domain Analyzer

1. Go to Domain Analyzer
2. Enter domain name to analyze
3. Review DNS records, MX records, and configuration
4. Check for common issues and misconfigurations
5. Follow recommendations for fixes

Outbound Monitor

1. Access Outbound Monitor
2. Review outbound email statistics
3. Check for spam complaints or delivery issues
4. Monitor sending reputation and patterns

Sync Manager

1. Open Sync Manager
2. Compare local and remote configurations
3. Identify inconsistencies
4. Apply synchronization fixes as needed

Features Overview

Security Features

• Password Protection: All access requires authentication
• Session Management: Secure session handling
• API Key Protection: Secure storage and transmission of API credentials
• Input Validation: All user inputs are validated and sanitized

Data Management

• CSV Import/Export: Standard CSV format support
• Bulk Operations: Process hundreds of entries at once
• Manual Entry: Single-entry forms for individual items
• Data Validation: Automatic validation of email addresses and domains

User Interface

• Responsive Design: Works on desktop and mobile devices
• Dark Mode Support: Automatic dark theme detection
• Real-time Feedback: Instant success/error messages
• Progress Indicators: Visual feedback during bulk operations

Troubleshooting

Common Installation Issues

Problem: "Permission denied" errors Solution:

chmod 755 /path/to/tool/
chown -R www-data:www-data /path/to/tool/

Problem: "API connection failed" Solution:

• Verify $mailcow_base_url is correct
• Check API key has proper permissions
• Ensure Mailcow API is enabled

Problem: "Password authentication failed" Solution:

• Verify $password_protect in config.php
• Clear browser cache and cookies
• Check for typos in password

Common Usage Issues

Problem: CSV import fails Solution:

• Check CSV format matches expected columns
• Ensure no special characters in email addresses
• Verify domains exist in Mailcow before adding aliases

Problem: Slow performance with large imports Solution:

• Process in smaller batches (50-100 entries)
• Check server resources (CPU, memory)
• Increase PHP execution time limits

Problem: Some aliases not importing Solution:

• Check for duplicate email addresses
• Verify domain exists and is active
• Review error messages for specific failures

Debug Mode

To enable debug mode for troubleshooting:

1. Edit includes/config.php
2. Add: $debug_mode = true;
3. Check detailed error logs in browser console

Security Considerations

Best Practices

1. Strong Passwords: Use complex passwords for $password_protect
2. HTTPS Only: Always access the tool over HTTPS
3. IP Restrictions: Consider restricting access by IP address
4. Regular Updates: Keep the tool updated to latest version
5. API Key Security: Regularly rotate Mailcow API keys

Access Control

Consider implementing additional security measures:

// Add to config.php for IP restrictions
$allowed_ips = ['192.168.1.100', '10.0.0.50'];
$client_ip = $_SERVER['REMOTE_ADDR'];
if (!in_array($client_ip, $allowed_ips)) {
    die('Access denied');
}

File Security

Protect sensitive files with .htaccess:

# Place in includes/ directory
<Files "config.php">
    Order Allow,Deny
    Deny from all
</Files>

Support and Updates

Getting Help

• Check the troubleshooting section above
• Review error messages carefully
• Submit support tickets through your account
• Include relevant log files and error messages

Version Updates

1. Backup your current installation
2. Download the latest version
3. Replace files except includes/config.php
4. Test functionality after update
5. Review changelog for new features

Backup Recommendations

• Backup includes/config.php before updates
• Export important data before major changes
• Keep backups of CSV import files
• Document custom configurations

This guide covers the essential aspects of installing, configuring, and using the Mailcow Import Export Tool. For additional support or specific use cases, please contact our support team.