imapdown/README.md

# IMAP Downloader

Download all emails from an IMAP server into individual EML files, preserving the folder structure.

Single self-contained binary written in Go - fast, cross-platform, no dependencies.

## Quickstart

```bash
# Build the binary
make build

# Download all emails (creates a folder named after your email address)
./imapdown -server imap.gmail.com -email you@gmail.com -user you@gmail.com -password "your-password" -ssl

# Subsequent runs only download new emails
./imapdown -server imap.gmail.com -email you@gmail.com -user you@gmail.com -password "your-password" -ssl
```

## Features

- Downloads emails as standard `.eml` files (open in any email client)
- Preserves IMAP folder hierarchy locally
- Extracts attachments into zip files alongside each email
- Supports SSL/TLS and STARTTLS connections
- Incremental updates using UID tracking (only download new emails)
- Automatic state tracking - never re-downloads the same email
- Configurable download limit for testing/debugging
- Works with Gmail, Outlook, FastMail, and any IMAP server

## Requirements

- Go 1.21+ (for building from source)
- OR use pre-compiled binaries (no requirements)

## Installation

Download from releases page (coming soon) or build from source:

```bash
# Clone repository
git clone <repo-url>
cd imapdown

# Build the binary
make build

# Or cross-compile for all platforms
make build-all
```

## Usage

### Basic Usage

By default, only new emails since the last run are downloaded (incremental mode). On first run, everything is downloaded.

```bash
# Generic IMAP server with SSL (most common)
./imapdown -server imap.example.com -email me@example.com -user me@example.com -password "secret" -ssl

# Gmail (requires app-specific password if 2FA enabled)
./imapdown -server imap.gmail.com -email you@gmail.com -user you@gmail.com -password "app-password" -ssl

# Outlook/Office 365
./imapdown -server outlook.office365.com -email you@outlook.com -user you@outlook.com -password "password" -ssl

# Custom storage directory
./imapdown -server imap.example.com -email me@example.com -user me@example.com -password "secret" -ssl -output /path/to/backup

# Using STARTTLS instead of SSL
./imapdown -server imap.example.com -email me@example.com -user me@example.com -password "secret" -starttls

# Custom port
./imapdown -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 -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 me@example.com/
```

### Debugging/Testing

Limit the number of emails downloaded:

```bash
./imapdown -server imap.example.com -email me@example.com -user me@example.com -password "secret" -ssl -limit 10
```

## Command Line Arguments

| Argument | Flag | Required | Description |
|----------|------|----------|-------------|
| Server | `-server` | Yes | IMAP server hostname |
| Email | `-email` | Yes | Email address (used for folder organization) |
| User | `-user` | Yes | Username for authentication |
| Password | `-password` | Yes | Password for authentication |
| SSL | `-ssl` | No | Use implicit SSL/TLS (default port 993) |
| STARTTLS | `-starttls` | No | Use STARTTLS (default port 143) |
| Port | `-port` | No | Custom port (overrides defaults) |
| Limit | `-limit` | No | Maximum number of emails to download |
| Full | `-full` | No | Download all emails (default: only new since last run) |
| Output | `-output` | No | Directory to store downloaded emails (default: ./{email}) |

**Notes:**
- `-ssl` and `-starttls` are mutually exclusive

## Output Structure

**Without `-output` flag** (default: `./{email_address}/`):
```
./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
```

**With `-output /path/to/backup`** (emails go directly into specified directory):
```
/path/to/backup/
├── .imapdown_state.json
├── INBOX/
│   ├── 123_20240115_Meeting_notes.eml
│   ├── 124_20240116_Report.eml
│   └── 124_20240116_Report.zip
├── Sent/
│   └── 456_20240114_RE_Question.eml
└── Archive/
    └── 789_20240101_Old_email.eml
```

### 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

A `.imapdown_state.json` file is maintained in the download folder. This file tracks the highest downloaded UID for each IMAP folder, enabling efficient incremental updates.

Example state file:
```json
{
  "INBOX": 19334,
  "INBOX.Archive": 1770,
  "Sent": 892
}
```

## Building from Source

```bash
# Build for current platform
make build

# Cross-compile for all platforms
make build-all
# Produces: imapdown-linux-amd64, imapdown-linux-arm64,
#           imapdown-darwin-amd64, imapdown-darwin-arm64,
#           imapdown-windows-amd64.exe

# Install to $GOPATH/bin
make install

# Clean build artifacts
make clean

# Or use Go directly
go build -ldflags="-s -w" -o imapdown
```

## Troubleshooting

### Gmail Authentication

Gmail requires an app-specific password if you have 2-factor authentication enabled:
1. Go to Google Account Settings → Security → 2-Step Verification → App passwords
2. Generate a new app password for "Mail"
3. Use this password instead of your regular password

### Connection Issues

- **SSL errors**: Make sure you're using the correct port (993 for SSL, 143 for STARTTLS)
- **Authentication failed**: Verify username and password are correct
- **Timeout**: Some servers require STARTTLS instead of SSL - try `-starttls` flag

### First Run Not Downloading

If the first run doesn't download anything:
1. Check the folder actually contains emails on the server
2. Try with `-limit 10` to test with a small batch first
3. Verify your credentials work by logging into webmail

### Re-downloading Everything

To start fresh and re-download all emails:
```bash
# Delete the email folder (and state file)
rm -rf ./your-email@example.com/

# Run with -full flag
./imapdown -server imap.example.com -email your-email@example.com -user your-email@example.com -password "password" -ssl -full
```

## License

MIT