Skip to content

README.md

Latest commit

 

History

History
319 lines (248 loc) · 10.9 KB

README.md

File metadata and controls

319 lines (248 loc) · 10.9 KB

webdekeepalive

A Python script for automatic IMAP Keep-Alive for WEB.DE Freemail accounts to prevent email account expiration.

Problem

WEB.DE Freemail accounts expire when no login occurs over a longer period (usually 6-12 months). This affects:

  • Inactive email accounts are automatically deactivated
  • Important email addresses are lost
  • No notification before expiration
  • Manual logins are time-consuming and easily forgotten

Solution

webdekeepalive solves this problem by:

  • Automatic IMAP logins via Cron job
  • Per-account configuration for multiple email addresses
  • Centralized logging with account identification
  • Email notifications about success/failure
  • Robust error handling with retry mechanism
  • Lockfile protection against overlapping executions

Installation

1. Clone repository

git clone https://github.com/drhdev/webdekeepalive.git
cd webdekeepalive

2. Create virtual environment (recommended)

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Setup configuration

# Copy templates to real configuration
cp secrets/user1.env.example secrets/user1.env
cp secrets/user2.env.example secrets/user2.env

# Set security permissions
chmod 600 secrets/*.env

# Enter real values in secrets/*.env
nano secrets/user1.env
nano secrets/user2.env

Configuration

Prepare WEB.DE account

IMPORTANT: Before first use, IMAP/SMTP must be activated and an app-specific password must be created in the WEB.DE web interface:

  1. Open WEB.DE Webmail → Login
  2. Settings → Email Programs or IMAP/POP3
  3. Activate IMAP (for email receiving)
  4. Activate SMTP (for email sending)
  5. Create App-Specific Password:
    • Go to Security Settings → App-Specific Passwords
    • Create a new password for "webdekeepalive" or similar
    • Copy the generated password (you won't see it again!)
  6. Save settings
  7. Wait 15 minutes for activation to take effect

Important:

  • Disable 2FA (not supported)
  • Activation takes 5-15 minutes to take effect
  • Password type varies by account:
    • Some accounts: Use app-specific password (create in WEB.DE security settings)
    • Other accounts: Use your standard WEB.DE login password
    • Check your WEB.DE account settings to determine which type is required
  • Script always uses SSL (no TLS configuration needed)

Account configuration

Each account is configured in secrets/{account_id}.env:

# Account identification
ACCOUNT_ID=user1
ACCOUNT_EMAIL=my.email@web.de

# IMAP server (WEB.DE standard)
ACCOUNT_IMAP_HOST=imap.web.de
ACCOUNT_IMAP_PORT=993
ACCOUNT_IMAP_TIMEOUT=30

# Retry configuration
ACCOUNT_RETRY_MAX=5
ACCOUNT_RETRY_BASE=5.0
ACCOUNT_RETRY_MAX_WAIT=120.0
ACCOUNT_RETRY_MIN_WAIT=30.0  # Minimum delay between retries (prevents rate limiting)
ACCOUNT_JITTER=0.5

# Email sending delay after IMAP NOOP command (seconds)
ACCOUNT_EMAIL_DELAY=11.0

# Secrets (ENTER REAL VALUES!)
ACCOUNT_FROM_NAME=Max Mustermann
ACCOUNT_SMTP_USER=my.email@web.de
ACCOUNT_SMTP_PASS=my_password  # Use app-specific password OR standard password (check WEB.DE settings)

# Email notifications
MAIL_SEND=true
MAIL_SMTP_HOST=smtp.web.de
MAIL_SMTP_PORT=465
MAIL_TO_EMAIL=my.email@web.de

# Email templates
TEMPLATE_SUBJECT=WEB.DE KeepAlive [{status}] {time} — {email}
TEMPLATE_BODY=Hello,\n\nthis is the KeepAlive report for your web.de email-account.\n\nAccount: {email}\nTime: {time}\nStatus: {status}\nMessage: {message}\n\nRecent log entries:\n{log_excerpt}\n\nRegards, your webdekeepalive-Bot from {hostname}

# Template variables:
# {email} - Account email address
# {time} - Current timestamp
# {status} - Login status (OK/ERROR)
# {message} - Status message
# {log_excerpt} - Recent log entries from current run
# {hostname} - Hostname of the server running the script

# Logging
LOG_DIR=logs
LOG_LEVEL=DEBUG

# Lockfile
LOCK_USE=true
LOCK_DIR=logs

Setup Cron Jobs

Example: Weekly execution

# Edit crontab
crontab -e

# user1: Every Saturday at 17:31
31 17 * * 6 cd /path/to/webdekeepalive && /path/to/webdekeepalive/venv/bin/python /path/to/webdekeepalive/webdekeepalive.py --account user1 >> /path/to/webdekeepalive/cron_user1.out 2>&1

# user2: Every Saturday at 18:44
44 18 * * 6 cd /path/to/webdekeepalive && /path/to/webdekeepalive/venv/bin/python /path/to/webdekeepalive/webdekeepalive.py --account user2 >> /path/to/webdekeepalive/cron_user2.out 2>&1

Example: Monthly execution

# user1: 1st of every month at 10:00
0 10 1 * * cd /path/to/webdekeepalive && /path/to/webdekeepalive/venv/bin/python /path/to/webdekeepalive/webdekeepalive.py --account user1 >> /path/to/webdekeepalive/cron_user1.out 2>&1

# user2: 15th of every month at 14:30
30 14 15 * * cd /path/to/webdekeepalive && /path/to/webdekeepalive/venv/bin/python /path/to/webdekeepalive/webdekeepalive.py --account user2 >> /path/to/webdekeepalive/cron_user2.out 2>&1

Example: Daily execution

# user1: Daily at 08:00
0 8 * * * cd /path/to/webdekeepalive && /path/to/webdekeepalive/venv/bin/python /path/to/webdekeepalive/webdekeepalive.py --account user1 >> /path/to/webdekeepalive/cron_user1.out 2>&1

# user2: Daily at 20:00
0 20 * * * cd /path/to/webdekeepalive && /path/to/webdekeepalive/venv/bin/python /path/to/webdekeepalive/webdekeepalive.py --account user2 >> /path/to/webdekeepalive/cron_user2.out 2>&1

Testing

Manual test

# Activate virtual environment
source venv/bin/activate

# Test with verbose output
python3 webdekeepalive.py --account user1 -v
python3 webdekeepalive.py --account user2 -v

Expected output on success

2025-10-26 17:31:00,123 [INFO] [ACCOUNT=user1] Directory check completed successfully
2025-10-26 17:31:00,124 [INFO] [ACCOUNT=user1] IMAP login attempt 1/5 for my.email@web.de (imap.web.de:993)
2025-10-26 17:31:00,245 [INFO] [ACCOUNT=user1] ✅ my.email@web.de: Login successful – Account is active.
2025-10-26 17:31:00,246 [INFO] [ACCOUNT=user1] ✅ Email successfully sent to my.email@web.de

Email notification content

The script sends personalized email notifications with:

  • Subject: WEB.DE KeepAlive [OK] 2025-10-26 17:31:00 — my.email@web.de
  • Body: KeepAlive report with account details, status, and recent log entries
  • Signature: Regards, your webdekeepalive-Bot from [hostname]
  • Log entries: Only from the current script execution (filtered for INFO level and above)

Monitoring

Central logfile

# Monitor all accounts (rotating log, max 1MB, 3 backups)
tail -f logs/webdekeepalive.log

# Account-specific monitoring
grep "\[ACCOUNT=user1\]" logs/webdekeepalive.log | tail -f
grep "\[ACCOUNT=user2\]" logs/webdekeepalive.log | tail -f

# Error monitoring
grep "ERROR.*\[ACCOUNT=" logs/webdekeepalive.log
grep "WARNING.*\[ACCOUNT=" logs/webdekeepalive.log

# Debug information (detailed server responses)
grep "DEBUG.*\[ACCOUNT=" logs/webdekeepalive.log | tail -20

Monitor cron output

tail -f cron_user1.out
tail -f cron_user2.out

Common Problems

1. IMAP/SMTP not activated

Problem: authentication failed Solution: Activate IMAP/SMTP in WEB.DE web interface and wait 15 minutes

2. Wrong password type

Problem: authentication failed despite correct password Solution: Check your WEB.DE account settings to determine the required password type:

  • Some accounts: Require app-specific password (create in WEB.DE security settings)
  • Other accounts: Use your standard WEB.DE login password
  • Test both types if unsure which is required for your account

3. 2FA enabled

Problem: authentication failed despite correct password Solution: Disable 2FA in WEB.DE settings

4. Wrong server data

Problem: Connection errors Solution: Use correct server data:

  • IMAP: imap.web.de:993 with SSL
  • SMTP: smtp.web.de:465 with SSL (script always uses SSL, no TLS configuration needed)

5. Virtual environment not activated

Problem: Exit code 4 Solution: Activate virtual environment or use --no-venv-check

6. Lockfile blocking

Problem: "Another run active" Solution: Manually delete lockfile: rm logs/.keepalive_user1.lock

Project Structure

webdekeepalive/
├── webdekeepalive.py              # Main script (v0.9.9)
├── secrets/
│   ├── user1.env.example          # Template for user1 (79 lines, structured)
│   ├── user2.env.example          # Template for user2 (79 lines, structured)
│   ├── user1.env                  # Real configuration (ignored by git)
│   └── user2.env                  # Real configuration (ignored by git)
├── logs/
│   └── webdekeepalive.log         # Central logfile (rotating, 1MB max)
├── requirements.txt               # Python Dependencies
├── .gitignore                     # Git Ignore Rules
└── README.md                      # This documentation

Features

  • ✅ Per-account configuration in separate .env files with consistent structure
  • ✅ Centralized logging with account identification and detailed debug information
  • ✅ Email notifications with personalized hostname signature and current run logs only
  • ✅ Integrated email workflow (sends during active IMAP session)
  • ✅ Configurable retry delays with minimum wait time to prevent rate limiting
  • ✅ Robust error handling with exponential backoff and detailed server response logging
  • ✅ Lockfile protection against overlapping executions
  • ✅ Virtual environment required (security)
  • ✅ No root privileges needed
  • ✅ WEB.DE-optimized with correct server data (IMAP: 993 SSL, SMTP: 465 SSL)
  • ✅ Always SSL for secure email transmission (no TLS configuration needed)
  • ✅ App-specific password support for WEB.DE
  • ✅ English language throughout (logs, emails, messages)
  • ✅ Structured .env files with clear sections and comprehensive comments

Exit Codes

  • Exit 0: Success
  • Exit 1: IMAP login failed
  • Exit 2: Configuration error (missing email, password)
  • Exit 3: Directory problems (logs, lockfiles)
  • Exit 4: Virtual environment missing or dependencies not met

Security

  • No credentials in logs: Passwords are never logged
  • Secure .env files: chmod 600 for secrets
  • Lockfiles: Prevent overlapping executions
  • Virtual environment: Isolated Python environment

License

GNU PUBLIC LICENSE - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Support

For problems or questions:

  1. Create Issues on GitHub
  2. Check logs in logs/webdekeepalive.log
  3. Verify WEB.DE settings (IMAP/SMTP activated?)
  4. Virtual environment activated?