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

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

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

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

./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:

rm -rf me@example.com/

Debugging/Testing

Limit the number of emails downloaded:

./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:

{
  "INBOX": 19334,
  "INBOX.Archive": 1770,
  "Sent": 892
}

Building from Source

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

# 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