Metadata-Version: 2.4
Name: spark-mail-export
Version: 0.0.1
Summary: Export emails from Spark Mail's local cache on macOS — works even when accounts are disabled.
Author: Batuhan Göbekli
License: MIT
Project-URL: Homepage, https://github.com/batuhangobekli/spark-mac-mail-export
Project-URL: Repository, https://github.com/batuhangobekli/spark-mac-mail-export
Project-URL: Issues, https://github.com/batuhangobekli/spark-mac-mail-export/issues
Project-URL: Changelog, https://github.com/batuhangobekli/spark-mac-mail-export/blob/master/CHANGELOG.md
Keywords: spark,email,export,backup,macos,eml,mbox
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: System :: Archiving :: Backup
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ✉️ Spark Mac Mail Export

<div align="left">
  <img height="450" alt="Spark Mac Mail Export Showcase" src="https://github.com/user-attachments/assets/184d6a36-73bb-41fc-86e3-f6fc4fed4e25" />
</div>
<br>

Export your emails from [Spark Mail](https://sparkmailapp.com)'s local cache on macOS.

> Works even when email accounts are **disabled or deleted** — as long as Spark still has the data cached locally on your Mac.

## ⚙️ Compatibility

| Spark Version | Status |
|---------------|--------|
| **Spark Classic (v2)** | ✅ Tested|
| **Spark Desktop (v3, +AI)** | ✅ Tested|

Spark Classic stores mail data in the shared Group Container (`3L68KQB4HG.group.com.readdle.smartemail/databases`). Spark Desktop stores mail data under its own `Spark Desktop/core-data` directory. The schemas are compatible for the export fields this tool reads, and the tool detects both installed apps so you can choose the source with `--app` or the interactive selector.


## ✨ Features

- **Zero setup** — single Python script, no external dependencies
- **Auto-detects** Spark Classic (Legacy) and Spark Desktop (New)
- **Interactive UI** — persistent header, Spark app selection, arrow-key navigation with checkboxes, or use CLI flags for automation
- **Multiple formats** — export to `.eml` files, `.mbox` archives, or both
- **Organized output** — emails sorted by folder with a searchable CSV index
- **Read-only** — opens databases in read-only mode, cannot modify Spark's data
- **Fully offline** — no network access, no telemetry, no cloud
- **Attachments included** — locally cached attachments are embedded in `.eml` files

## ⚡ Quick Start

```bash
# Clone or download
git clone https://github.com/batuhangobekli/spark-mac-mail-export.git
cd spark-mac-mail-export

# Run (Python 3.8+ required — included with macOS)
python3 spark_mail_export.py
```

That's it. The script will auto-detect installed Spark apps, ask which source to export from, show your accounts, and guide you through the export.

## 📖 Usage

### Interactive Mode

Run the script with **no arguments** to get the full interactive experience:

```bash
python3 spark_mail_export.py
```

You'll get:
1. Auto-detection of Spark Classic (Legacy) and Spark Desktop (New)
2. A Spark app/source selector when both apps are available
3. A list of email accounts from the selected source, sorted by email count
4. **Arrow-key navigation** (↑/↓) with **Space** to toggle and **Enter** to confirm
5. Selected-account context on folder/date/output prompts
6. Step-by-step prompts for format and output directory

> **Note:** The interactive UI uses Python's built-in `curses` module. If your terminal doesn't support it, the tool falls back to plain text input automatically.

### Command-Line Mode

Pass **any argument** and the tool runs directly — no interactive UI:

```bash
# Export a specific account
python3 spark_mail_export.py --account user@example.com

# Export using Spark Desktop's local cache
python3 spark_mail_export.py --app desktop --account user@example.com

# Export using Spark Classic's local cache
python3 spark_mail_export.py --app classic --account user@example.com

# Export all accounts
python3 spark_mail_export.py --all

# Export to MBOX format with custom output directory
python3 spark_mail_export.py --account user@example.com --format mbox -o ~/Documents/backup

# Export only Inbox emails from a date range
python3 spark_mail_export.py --account user@example.com --folder INBOX --date-from 2024-01-01

# Export everything in both formats
python3 spark_mail_export.py --all --format both

# Preview what would be exported (no files written)
python3 spark_mail_export.py --all --dry-run

# List all accounts
python3 spark_mail_export.py --list-accounts

# List Spark Desktop accounts
python3 spark_mail_export.py --app desktop --list-accounts

# List folders for a specific account
python3 spark_mail_export.py --list-folders user@example.com
```

### All Options

```
--account EMAIL        Export specific account (by email address or display name)
--all                  Export all accounts without prompting
--app APP              Source app: auto, classic, or desktop (default: auto)
--output, -o DIR       Output directory (default: ~/Desktop/spark-export)
--format, -f FMT       eml, mbox, or both (default: eml)
--folder NAME          Filter by folder name (e.g., INBOX, 'Sent Mail')
--date-from DATE       Start date filter (YYYY-MM-DD)
--date-to DATE         End date filter (YYYY-MM-DD)
--dry-run              Show what would be exported without writing files
--list-accounts        List all accounts and exit
--list-folders EMAIL   List all folders for an account and exit
--include-no-body      Include emails even if no body is cached (default: all included)
--quiet, -q            Suppress progress output
--version              Show version
--help                 Show help message
```

> **Tip:** Any argument triggers non-interactive mode. Use `--account` or `--all` to specify what to export. If you forget, the tool will show an error with the correct usage.

## 📁 Output Structure

```
~/Desktop/spark-export/
└── user@example.com/
    ├── eml/
    │   ├── INBOX/
    │   │   ├── 2025-10-15_143021_JohnDoe_Project-Update.eml
    │   │   └── ...
    │   ├── Sent Mail/
    │   │   └── ...
    │   └── ...
    ├── mbox/                    # Only if --format mbox or both
    │   ├── INBOX.mbox
    │   └── Sent Mail.mbox
    ├── email_index.csv          # Searchable index of all emails
    └── export_summary.txt       # Human-readable summary
```

Accounts are sorted by email count (highest first). Emails are organized into per-folder subdirectories with date-prefixed filenames for easy sorting.

## 📬 How to View .eml Files

| Method | Instructions |
|--------|-------------|
| **macOS Quick Look** | Select `.eml` file → press **Space** |
| **Apple Mail** | Drag `.eml` files into a mailbox |
| **Thunderbird** | Install "ImportExportTools NG" add-on → Import directory |
| **Outlook** | Double-click any `.eml` file |
| **Gmail** | Import via Thunderbird + IMAP sync |
| **Web browser** | Open `.eml` file directly for HTML emails |

For detailed instructions, see [docs/viewing_eml_files.md](docs/viewing_eml_files.md).

### Requirements

- **macOS** (any recent version)
- **Python 3.8+** (included with macOS)
- **Spark Mail** must have been used at least once (to create local data)

## ⚠️ Limitations

1. **macOS only** — Spark's local storage is macOS-specific
2. **Only locally cached data** — If Spark never synced/opened an email's body, only metadata + a short preview will be available
3. **Attachments** — Only locally downloaded attachments are exported; cloud-only attachments will have metadata but no file content
4. **Database lock** — Spark should be quit before running the export (the tool will warn you if the database is locked)
5. **Account must exist in Spark** — The account entry must still be in Spark's database (not fully removed from the app)

## ⚖️ Legal Notice

This tool reads **your own email data** from standard SQLite database files stored on **your own filesystem** by the Spark Mail application.

This tool does **not** reverse engineer, decompile, or disassemble any application binary. It does not bypass any encryption or security measures. It does not access any remote servers. It does not modify Spark's data in any way (read-only access).

This project is **not affiliated with** Readdle Inc. or Spark Mail Limited.

**You are solely responsible** for ensuring your use of this tool complies with applicable laws and Terms of Service.

For the full disclaimer, see [DISCLAIMER.md](DISCLAIMER.md).

## 🔒 Security

- **Read-only** database access (`?mode=ro`)
- **Zero** network requests
- **Zero** external dependencies
- **No** passwords or credentials are accessed
- **No** telemetry or data collection

You can audit the entire tool — it's a single Python file. See [SECURITY.md](SECURITY.md) for details.

## 📦 Installation (Optional)

### Direct Download (Simplest)

```bash
curl -sLO https://raw.githubusercontent.com/batuhangobekli/spark-mac-mail-export/master/spark_mail_export.py
python3 spark_mail_export.py
```

### pip / pipx

```bash
pip install spark-mac-mail-export
spark-mac-mail-export
```

Or with pipx (recommended for CLI tools):

```bash
pipx install spark-mac-mail-export
spark-mac-mail-export
```

## 🤝 Contributing

Contributions are welcome! Please:

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

### Running Tests

```bash
python3 tests/test_sanitize.py
python3 tests/test_address_parser.py
python3 tests/test_utils.py
python3 tests/test_db_reader.py
python3 tests/test_detector.py
```

### Technical Documentation

- [Database Schema](docs/spark_database_schema.md) — How Spark stores emails locally
- [Viewing EML Files](docs/viewing_eml_files.md) — Guide to opening exported emails

## 📄 License

[MIT](LICENSE) — Copyright (c) 2026 Batuhan Göbekli
