jeena/email-forwarder
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Email Forwarder is a Python-based tool that automates email synchronization between IMAP accounts (e.g., GMX to MXRoute). It forwards new emails, prevents duplicates using Message-ID tracking, supports multi-folder sync, and integrates with systemd for scheduled runs and Uptime Kuma monitoring.
6 commits 1 branch 0 tags 62 KiB
Find a file
Jeena f70f1853f0 Refactor main.py for readability and maintainability 
Introduce class-based architecture with inheritance for IMAP clients:
- ImapClient base class with private low-level methods
- SourceImap and DestImap subclasses for specific operations
- EmailForwarder orchestrator class for coordination
- Global load_config and main functions

Improvements:
- Clear separation of concerns and encapsulation
- Private methods for internal IMAP calls
- Better error handling and logging
- Maintains all original functionality
2026-01-04 16:41:58 +09:00
email_forwarder.service.d Add sample drop-in config 2026-01-04 16:15:04 +09:00
.env.example Implement multi-folder synchronization 2026-01-04 16:27:54 +09:00
.gitignore Clean up unused code and config 2026-01-04 15:44:57 +09:00
email_forwarder-fail-notify.service Implement email forwarder 2026-01-04 15:34:31 +09:00
email_forwarder.service Implement email forwarder 2026-01-04 15:34:31 +09:00
email_forwarder.timer Implement email forwarder 2026-01-04 15:34:31 +09:00
install.sh Add install script 2026-01-04 16:20:46 +09:00
main.py Refactor main.py for readability and maintainability 2026-01-04 16:41:58 +09:00
pyproject.toml Implement email forwarder 2026-01-04 15:34:31 +09:00
README.md Implement multi-folder synchronization 2026-01-04 16:27:54 +09:00

README.md

Email Forwarder

This script forwards new emails from a source IMAP account (e.g., GMX) to a destination IMAP account (e.g., MXRoute), avoiding duplicates by tracking Message-IDs and using time-based searches.

Setup

Automated Install (Recommended)

Run the install script: ./install.sh

This will set up the virtual environment, systemd services, and provide post-install instructions.

Manual Setup

  1. Copy .env.example to .env and fill in your IMAP credentials, Uptime URLs, and settings.

  2. Create virtual environment: python -m venv venv

  3. Activate and install: source venv/bin/activate && pip install -e .

  4. For user services (recommended):

    • Copy services: cp *.service *.timer ~/.config/systemd/user/
    • Copy drop-in: cp -r email_forwarder.service.d ~/.config/systemd/user/
    • Copy ~/.config/systemd/user/email_forwarder.service.d/override.conf.sample to override.conf and edit to set your PROJECT_DIR and ENV_FILE paths.

  5. Reload and enable: systemctl --user daemon-reload && systemctl --user enable email_forwarder.timer && systemctl --user start email_forwarder.timer

  6. Check status: systemctl --user status email_forwarder.timer

Configuration (.env)

  • SOURCE_HOST: Source IMAP server (e.g., imap.gmx.com)
  • SOURCE_PORT: Port (default 993)
  • SOURCE_USER: Source email/username
  • SOURCE_PASS: Source password
  • DEST_HOST: Destination IMAP server (e.g., yourserver.mxrouting.net)
  • DEST_PORT: Port (default 993)
  • DEST_USER: Destination email/username
  • DEST_PASS: Destination password
  • FOLDERS: Folders to sync (default INBOX; use "all" for all folders or comma-separated list like "INBOX,Sent")
  • DRY_RUN: Set to true for testing without forwarding (default false)
  • UPTIME_SUCCESS_URL: URL for success ping
  • UPTIME_FAIL_URL: URL for failure ping

How It Works

  • Uses time-based search (SINCE) with last_run.txt to find emails since last run.
  • Extracts Message-ID, checks against local file and destination IMAP for duplicates.
  • Forwards via IMAP APPEND; updates last_run.txt on success.
  • Logs activity; systemd handles Uptime Kuma pings.

Monitoring with Uptime Kuma

  • Success: Pings ${UPTIME_SUCCESS_URL} after forwarding.
  • Failure: OnFailure pings ${UPTIME_FAIL_URL}.

Dependencies

  • imaplib, email (built-in)
  • python-dotenv, imap-tools
  • systemd (for user services)

Troubleshooting

  • Logs: journalctl --user -u email_forwarder.service
  • Test: source venv/bin/activate && python main.py
  • Timezone issues: Adjust UTC offset in script if needed.