Initial commit: IMAP email downloader

Single-file Python script to download emails from IMAP servers: - Downloads emails as .eml files preserving folder structure - Extracts attachments to zip files - Supports SSL and STARTTLS connections - Incremental updates using UID tracking (default behavior) - Multi-account support with separate folders per email - Safety checks to prevent duplicate downloads Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-29 17:37:11 +00:00
commit a0e7a494e4
5 changed files with 660 additions and 0 deletions
@@ -0,0 +1,133 @@
+# IMAP Downloader
+
+A simple Python script to download all emails from an IMAP server into individual EML files, preserving the folder structure.
+
+## Features
+
+- Downloads emails as standard `.eml` files
+- Preserves IMAP folder hierarchy locally
+- Extracts attachments into zip files alongside each email
+- Supports SSL and STARTTLS connections
+- Incremental updates using UID tracking (only download new emails)
+- Multi-account support (separate folders per email address)
+- Configurable download limit for testing/debugging
+
+## Requirements
+
+- Python 3.6+
+- No external dependencies (uses only standard library)
+
+## Installation
+
+```bash
+# Clone or download the script
+git clone <repo-url>
+cd imapdown
+
+# Create virtual environment (optional but recommended)
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+## Usage
+
+### Basic Usage
+
+By default, the script only downloads new emails since the last run (incremental mode). On first run, it downloads everything.
+
+```bash
+# Download emails using SSL (most common)
+./imapdown.py --server imap.example.com --email me@example.com --user me@example.com --password "secret" --ssl
+
+# Using STARTTLS
+./imapdown.py --server imap.example.com --email me@example.com --user me@example.com --password "secret" --starttls
+
+# Custom port
+./imapdown.py --server imap.example.com --email me@example.com --user me@example.com --password "secret" --ssl --port 12993
+```
+
+### Full Download
+
+To force a complete download of all emails (ignoring previous state):
+
+```bash
+./imapdown.py --server imap.example.com --email me@example.com --user me@example.com --password "secret" --ssl --full
+```
+
+**Note:** As a safety measure, `--full` will refuse to run if the download folder already contains emails. This prevents accidental duplicates. To re-download everything, first delete the folder:
+
+```bash
+rm -rf download/me@example.com/
+./imapdown.py --server imap.example.com --email me@example.com --user me@example.com --password "secret" --ssl --full
+```
+
+### Debugging/Testing
+
+Limit the number of emails downloaded:
+
+```bash
+./imapdown.py --server imap.example.com --email me@example.com --user me@example.com --password "secret" --ssl --limit 10
+```
+
+## Command Line Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--server` | Yes | IMAP server hostname |
+| `--email` | Yes | Email address (used for folder organization) |
+| `--user` | Yes | Username for authentication |
+| `--password` | Yes | Password for authentication |
+| `--ssl` | No | Use implicit SSL/TLS (default port 993) |
+| `--starttls` | No | Use STARTTLS (default port 143) |
+| `--port` | No | Custom port (overrides defaults) |
+| `--limit` | No | Maximum number of emails to download |
+| `--full` | No | Download all emails (default: only new since last run) |
+
+Note: `--ssl` and `--starttls` are mutually exclusive.
+
+## Output Structure
+
+```
+./download/
+├── user@example.com/
+│   ├── .imapdown_state.json      # Tracks last downloaded UID per folder
+│   ├── INBOX/
+│   │   ├── 123_20240115_Meeting_notes.eml
+│   │   ├── 124_20240116_Report.eml
+│   │   └── 124_20240116_Report.zip    # Attachments (if any)
+│   ├── Sent/
+│   │   └── 456_20240114_RE_Question.eml
+│   └── Archive/
+│       └── 789_20240101_Old_email.eml
+└── another@example.com/
+    └── ...
+```
+
+### File Naming
+
+Email files are named: `{UID}_{date}_{subject}.eml`
+
+- **UID**: Unique identifier from the IMAP server
+- **date**: Message date in `YYYYMMDD_HHMMSS` format
+- **subject**: Sanitized email subject (truncated to 50 characters)
+
+### Attachments
+
+When an email contains attachments, they are extracted and saved in a zip file with the same base name as the `.eml` file but with a `.zip` extension.
+
+## State Tracking
+
+The script maintains a `.imapdown_state.json` file in each email account's folder. This file tracks the highest downloaded UID for each IMAP folder, enabling efficient incremental updates with `--update`.
+
+Example state file:
+```json
+{
+  "INBOX": 19334,
+  "INBOX.Archive": 1770,
+  "Sent": 892
+}
+```
+
+## License
+
+MIT