Add flexible import folder functionality

- Add IMPORT_FOLDER_NAME configuration variable
- Support organized import (subfolders) or consolidated import (all to INBOX)
- Implement get_destination_folder() method for folder mapping
- Add email.utils import for proper date handling
- Update logging to show source → destination folder mappings
- Auto-create import folders as needed

Configuration examples:
- IMPORT_FOLDER_NAME=Imported → organized subfolders
- IMPORT_FOLDER_NAME= → all emails to INBOX

- Update .env.template with comprehensive explanations
- Add Host Europe and German hosting provider examples
- Include detailed configuration guides and troubleshooting
- Add realistic migration scenarios

- Update README.md with complete documentation
- Add feature overview and configuration guide
- Include usage examples and troubleshooting section
- Document both import modes with clear examples

.env.template

@@ -1,27 +1,150 @@
-# Source IMAP Server Configuration (Host Europe)
-SOURCE_IMAP_SERVER=
-SOURCE_IMAP_PORT=
-SOURCE_IMAP_USE_SSL=
-SOURCE_EMAIL=
-SOURCE_PASSWORD=
+# ============================================================================
+# EMAIL MIGRATION CONFIGURATION FILE
+# ============================================================================
+# Copy this file to '.env' and fill in your actual values.
+# NEVER commit the .env file to version control - it contains passwords!
 
-# Destination IMAP Server Configuration (Securehost.de)
-DEST_IMAP_SERVER=
-DEST_IMAP_PORT=
-DEST_IMAP_USE_SSL=
-DEST_EMAIL=
-DEST_PASSWORD=
+# ============================================================================
+# SOURCE EMAIL ACCOUNT (migrating FROM) - Host Europe Example
+# ============================================================================
 
-# Migration Settings
-TEMP_DOWNLOAD_DIR=
-LOG_LEVEL=
-BATCH_SIZE=
-PRESERVE_FLAGS=
-PRESERVE_DATES=
+# SOURCE_IMAP_SERVER: IMAP server hostname
+# Host Europe: wpxxxxxxxx.mail.server-he.de | Gmail: imap.gmail.com | Outlook: outlook.office365.com
+SOURCE_IMAP_SERVER=wp123456.mail.server-he.de
 
-# Optional: Folder filtering (comma-separated list, leave empty for all folders)
+# SOURCE_IMAP_PORT: IMAP port number
+# 993 (SSL recommended) | 143 (TLS/STARTTLS)
+SOURCE_IMAP_PORT=993
+
+# SOURCE_EMAIL: Your source email address
+# Example: user@yourdomain.de
+SOURCE_EMAIL=user@example-domain.de
+
+# SOURCE_PASSWORD: Email account password
+# Use your Host Europe email password (NOT app password needed here)
+SOURCE_PASSWORD=your_hosteurope_password
+
+# SOURCE_IMAP_USE_SSL: Use SSL encryption
+# True (port 993) | False (port 143 with TLS)
+SOURCE_IMAP_USE_SSL=True
+
+# ============================================================================
+# DESTINATION EMAIL ACCOUNT (migrating TO) - German Hosting Example
+# ============================================================================
+
+# DEST_IMAP_SERVER: Destination IMAP server
+# Common formats: mail.yourdomain.de | imap.provider.de
+DEST_IMAP_SERVER=mail.yourdomain.de
+
+# DEST_IMAP_PORT: Destination IMAP port
+# 993 (SSL) | 143 (TLS/STARTTLS)
+DEST_IMAP_PORT=993
+
+# DEST_EMAIL: Your destination email address
+# Example: user@newdomain.de
+DEST_EMAIL=user@newdomain.de
+
+# DEST_PASSWORD: Destination email password
+# Your hosting provider email password
+DEST_PASSWORD=your_destination_password
+
+# DEST_IMAP_USE_SSL: Use SSL for destination
+# True (recommended) | False
+DEST_IMAP_USE_SSL=True
+
+# ============================================================================
+# IMPORT FOLDER CONFIGURATION
+# ============================================================================
+
+# IMPORT_FOLDER_NAME: Where to organize imported emails
+#
+# Set to folder name: Creates organized subfolders
+#   "Imported" → Imported/INBOX, Imported/Sent, Imported/Drafts
+#   "Migration" → Migration/INBOX, Migration/Sent, etc.
+#
+# Leave empty: All emails go to main INBOX
+#   "" → All emails regardless of source folder → INBOX
+#
+# Examples: Imported | Migration_2024 | HostEurope_Backup | (empty)
+IMPORT_FOLDER_NAME=Imported
+
+# ============================================================================
+# FOLDER FILTERING
+# ============================================================================
+
+# INCLUDE_FOLDERS: Only migrate these folders (comma-separated)
+# Empty = migrate all folders
+# Host Europe common folders: INBOX,Sent,Drafts,Trash
 INCLUDE_FOLDERS=
-EXCLUDE_FOLDERS=
 
-# Connection timeout in seconds
-IMAP_TIMEOUT=
+# EXCLUDE_FOLDERS: Skip these folders (comma-separated)
+# Recommended: skip trash and spam folders
+EXCLUDE_FOLDERS=Trash,Spam,Junk
+
+# ============================================================================
+# MIGRATION SETTINGS
+# ============================================================================
+
+# BATCH_SIZE: Emails processed at once
+# 10 (conservative) | 50 (balanced) | 100 (aggressive)
+BATCH_SIZE=50
+
+# PRESERVE_FLAGS: Keep read/unread status
+# True (recommended) | False
+PRESERVE_FLAGS=True
+
+# PRESERVE_DATES: Keep original email dates
+# True (recommended) | False
+PRESERVE_DATES=True
+
+# ============================================================================
+# TECHNICAL SETTINGS
+# ============================================================================
+
+# IMAP_TIMEOUT: Connection timeout in seconds
+# 60 (default) | 120 (slow connections) | 30 (fast connections)
+IMAP_TIMEOUT=60
+
+# LOG_LEVEL: Logging detail level
+# INFO (recommended) | DEBUG (troubleshooting) | ERROR (minimal)
+LOG_LEVEL=INFO
+
+# TEMP_DOWNLOAD_DIR: Temporary files directory
+# ./temp_emails (default) | /tmp/emails | C:\Temp\emails
+TEMP_DOWNLOAD_DIR=./temp_emails
+
+# ============================================================================
+# PROVIDER-SPECIFIC EXAMPLES
+# ============================================================================
+
+# Host Europe Settings:
+# SOURCE_IMAP_SERVER=wpxxxxxxxx.mail.server-he.de
+# SOURCE_IMAP_PORT=993
+# SOURCE_IMAP_USE_SSL=True
+# Note: Replace 'wpxxxxxxxx' with your actual server name from Host Europe KIS
+
+# Common German Hosting Providers:
+# Strato: imap.strato.de:993
+# 1und1/IONOS: imap.1und1.de:993
+# All-Inkl: mail.all-inkl.com:993
+# Hetzner: mail.your-server.de:993
+
+# Gmail (if needed):
+# Gmail: imap.gmail.com:993 (requires app password)
+
+# ============================================================================
+# MIGRATION EXAMPLES
+# ============================================================================
+
+# Example 1: Host Europe to new hosting with organization
+# IMPORT_FOLDER_NAME=HostEurope_Migration
+# Result: Clean separation in destination
+
+# Example 2: Consolidate everything to main inbox
+# IMPORT_FOLDER_NAME=
+# Result: All emails in main INBOX
+
+# Example 3: Test migration with one folder
+# INCLUDE_FOLDERS=INBOX
+# BATCH_SIZE=10
+# LOG_LEVEL=DEBUG