A wrapper over proton-mail-export-cli to categorise the EML files into their original folders.

This helps with importing emails in a third party provider that does not have specific support for Proton's emails exports.

This script was generated by Claude Sonnet 4, with some prompted guidance to define the technical specification of Proton's mail export and requirements for this script.

• Copy the eml files into a directory on the file system which name corresponds to the Proton folder / tag the email is labelled with.

• An email can be in multiple folders and have multiple tags. However, in the output, the email will be filed in a single directory.

• Order of precedence for determining the label that will act as the destination directory:

• prefer a user created folder, if present
• failing that, use the system folder (Inbox, Trash, Sent, etc)
• and finally, use the tag, if nothing else applies

This guarantees that no matter how many labels an email is tagged on, only a single copy will be present in the organized_emails directory.

First run Proton's CLI tool: /Applications/proton-mail-export-cli.app/Contents/MacOS/proton-mail-export-cli.sh

Once the export has been produced, run the script:

# Organize emails in the export directory
python3 proton_eml_organizer.py /full/path/to/proton/export/folder

# Preview what would be organized (dry-run mode)
python3 proton_eml_organizer.py /full/path/to/proton/export/folder --dry-run

# Enable detailed logging for troubleshooting
python3 proton_eml_organizer.py /full/path/to/proton/export/folder --debug

# Combine dry-run with debug for detailed preview
python3 proton_eml_organizer.py /full/path/to/proton/export/folder --dry-run --debug

• --dry-run: Preview the organization without actually copying files
• --debug: Enable detailed logging including file operations and decision details

Example output (fictitious, counts don't add up):

Completed! Processed 1075 emails with 0 errors
Organized emails are in: /full/path/to/proton/export/folder/[email protected]/mail_20250620_123456/organized_emails

Created 20 folders:
  Important emails: 181 emails
  All Drafts: 2 emails
  All Mail: 150 emails
  All Sent: 580 emails
  Prsonal stuff: 152 emails
  Drafts: 2 emails
  Bills: 22 emails
  Family: 191 emails
  Follow-Up: 5 emails
  Inbox: 231 emails
  Receipts: 9 emails
  Sent: 168 emails
  Triage: 117 emails

✅ Email organization completed successfully!

Each label has a type:

• 1: Tag
• 3: Folder

Labels with a numerical id are "system" folders / tags (supplied by Proton) whereas labels with a "complex" ID (a string that bears resemblance with a base64 coded string) are user-defined.

The project includes comprehensive unit tests for all core logic components. To run the tests:

# Run all tests
python3 test_proton_eml_organizer.py

# Run tests with verbose output
python3 test_proton_eml_organizer.py -v

The test suite covers:

• Label categorization and priority selection logic
• Email metadata parsing
• File path utilities and sanitization
• Error handling scenarios
• Edge cases and malformed data

All tests should pass before making changes to the core logic.