{"id":47679547,"url":"https://github.com/heymumford/mailpail","last_synced_at":"2026-04-02T13:55:01.727Z","repository":{"id":344674183,"uuid":"1182633427","full_name":"heymumford/mailpail","owner":"heymumford","description":"Carry your mail away in a pail — export email to PDF, Excel, CSV. Multi-provider IMAP with plugin system, GUI wizard + CLI.","archived":false,"fork":false,"pushed_at":"2026-03-24T01:58:46.000Z","size":287,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T01:53:51.065Z","etag":null,"topics":["cli","csv","email","email-export","excel","export","gui","imap","mailpail","pdf","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heymumford.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T19:21:34.000Z","updated_at":"2026-03-24T01:57:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/heymumford/mailpail","commit_stats":null,"previous_names":["heymumford/aol-email-exporter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/heymumford/mailpail","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymumford%2Fmailpail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymumford%2Fmailpail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymumford%2Fmailpail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymumford%2Fmailpail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heymumford","download_url":"https://codeload.github.com/heymumford/mailpail/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymumford%2Fmailpail/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","csv","email","email-export","excel","export","gui","imap","mailpail","pdf","python"],"created_at":"2026-04-02T13:55:01.020Z","updated_at":"2026-04-02T13:55:01.718Z","avatar_url":"https://github.com/heymumford.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mailpail\n\n[![CI](https://github.com/heymumford/mailpail/actions/workflows/ci.yml/badge.svg)](https://github.com/heymumford/mailpail/actions/workflows/ci.yml)\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)\n\nYour email, your files, your machine. A friendly wizard to download and export your email to CSV, Excel, PDF, MBOX, and EML — with attachments.\n\n## Features\n\n- **GUI wizard** -- step-by-step guided export for non-technical users\n- **CLI mode** -- scriptable headless export with full filter support\n- **6 export formats** -- gzipped CSV, Excel (single or grouped), PDF, MBOX, EML\n- **Attachment download** -- saves all attachments alongside exports\n- **Filtered export** -- by date range, sender, subject, folder, unread status\n- **5 built-in providers** -- AOL, Gmail, Outlook, Yahoo, custom IMAP\n- **Batch export** -- process multiple accounts from a CSV credential file\n- **Incremental export** -- skip already-exported emails on subsequent runs\n- **Audit trail** -- SHA-256 manifest, timestamped export log, zip archive\n- **Plugin system** -- third-party providers and exporters via entry points\n- **Cross-platform** -- Windows (.exe), POSIX\n- **Dark mode** -- WCAG AA compliant dark palette\n\n## Quick Start\n\n```bash\npip install mailpail\nmailpail              # launch GUI wizard\nmailpail --cli        # headless mode\n```\n\nOr grab the latest `.exe` from [Releases](https://github.com/heymumford/mailpail/releases).\n\n## CLI Usage\n\n```bash\n# Export AOL inbox to gzipped CSV (default)\nmailpail --cli --username user@aol.com --format csv\n\n# Gmail with date range filter\nmailpail --cli --username user@gmail.com --provider gmail \\\n    --date-from 2024-01-01 --date-to 2025-01-01 --format csv\n\n# Filter by sender and subject\nmailpail --cli --username user@aol.com \\\n    --sender \"friend@aol.com\" --subject \"vacation\" --format pdf\n\n# Export to multiple formats at once\nmailpail --cli --username user@aol.com --format csv excel pdf\n\n# Incremental export (skip already-downloaded emails)\nmailpail --cli --username user@aol.com --incremental --format csv\n\n# Batch export from CSV credential file\nmailpail --cli --batch accounts.csv --output-dir ./exports\n\n# Dry run (show count without exporting)\nmailpail --cli --username user@aol.com --dry-run\n\n# List available IMAP folders\nmailpail --cli --username user@aol.com --list-folders\n\n# Custom IMAP server\nmailpail --cli --username user@example.com --provider imap \\\n    --server mail.example.com --port 993 --format csv\n```\n\n### Providers\n\n| Provider | Flag | Server |\n|----------|------|--------|\n| AOL (default) | `--provider aol` | export.imap.aol.com |\n| Gmail | `--provider gmail` | imap.gmail.com |\n| Outlook / Hotmail | `--provider outlook` | outlook.office365.com |\n| Yahoo | `--provider yahoo` | imap.mail.yahoo.com |\n| Custom | `--provider imap --server HOST` | (you specify) |\n\n### Export Formats\n\n| Format | Flag | Description |\n|--------|------|-------------|\n| CSV | `--format csv` | Gzipped `.csv.gz` with attachment filenames column |\n| Excel | `--format excel` | Single-sheet `.xlsx` workbook |\n| Excel (grouped) | `--format excel-sheets` | Multi-sheet `.xlsx`, one sheet per folder |\n| PDF | `--format pdf` | One PDF with all emails, attachment names listed |\n| MBOX | `--format mbox` | Standard email archive with embedded attachments |\n| EML | `--format eml` | One `.eml` file per email with attachments |\n\n### Batch Export\n\nCreate a CSV file with one account per row:\n\n```csv\nusername,password,provider,folder,format\nmargaret@aol.com,abcd-efgh-ijkl-mnop,aol,INBOX,csv\nderek@gmail.com,wxyz-1234-5678-abcd,gmail,INBOX,excel\n```\n\nOnly `username` and `password` are required. Other columns default to: provider=aol, folder=INBOX, format=csv.\n\n```bash\nmailpail --cli --batch accounts.csv --output-dir ./exports\n```\n\nEach account gets its own subdirectory with export files, manifest, and zip.\n\n## App Password Setup\n\nMost providers require an **app password** (not your regular password):\n\n| Provider | Setup link |\n|----------|-----------|\n| AOL | [AOL Account Security](https://login.aol.com/account/security/app-passwords) |\n| Gmail | [Google App Passwords](https://myaccount.google.com/apppasswords) (requires 2FA) |\n| Outlook | [Microsoft App Passwords](https://support.microsoft.com/en-us/account-billing/manage-app-passwords-for-two-step-verification) |\n| Yahoo | [Yahoo App Passwords](https://help.yahoo.com/kb/generate-manage-third-party-passwords-sln15241.html) |\n\n## Export Output\n\nEvery export produces a self-contained directory:\n\n```\nMailpail_Export/\n    mail_export.csv.gz          # your emails\n    attachments/                # saved attachment files\n        1_invoice.pdf\n        5_beach.jpg\n    manifest.json               # SHA-256 hashes for every file\n    export_log.json             # timestamps, filters, results\n    .mailpail_exported          # UID tracking for incremental\nMailpail_Export.zip             # single portable archive\n```\n\n## Plugin System\n\nMailpail supports two plugin entry point groups:\n\n### Provider plugins (`mailpail.providers`)\n\n```toml\n[project.entry-points.\"mailpail.providers\"]\nmy-provider = \"my_plugin.descriptor:DESCRIPTOR\"\n```\n\n### Exporter plugins (`mailpail.exporters`)\n\n```toml\n[project.entry-points.\"mailpail.exporters\"]\nmy-format = \"my_plugin.exporter:MyExporter\"\n```\n\nPlugins are discovered automatically. Provider plugins appear in the GUI dropdown and CLI `--provider` flag. Exporter plugins appear in `--format` choices.\n\n## Development\n\nRequires Python 3.12+ and [uv](https://docs.astral.sh/uv/).\n\n```bash\njust install    # set up environment\njust test       # run all tests (217 tests)\njust lint       # check code style\njust format     # fix code style\njust all        # format + lint + test\n```\n\n### Test tiers\n\n- **Tier A** (`just test-a`) -- must-pass product feature scenarios (AOL pipeline, exports, attachments, manifest, zip, batch, incremental)\n- **Tier B** (`just test-b`) -- regression, fitness, persona, dark mode, plugin system, GUI integration\n\n### Architecture\n\n```\nsrc/mailpail/\n    __main__.py          # CLI + GUI entry point\n    auth.py              # AuthFlow Protocol, Credential, Capability flags\n    batch.py             # Batch export from CSV credential files\n    client.py            # IMAPClient (built-in IMAP adapter)\n    credentials.py       # Credential storage (env, memory, file)\n    filters.py           # Client-side email filtering\n    models.py            # EmailRecord, FilterParams, ExportConfig\n    plugin.py            # Entry-point-based plugin discovery\n    providers.py         # ProviderDescriptor, 5 built-in providers\n    exporters/\n        __init__.py      # Exporter registry + plugin discovery\n        attachments.py   # Save attachments to disk\n        csv_export.py    # Gzipped CSV with attachment column\n        eml_export.py    # Individual .eml files\n        excel_export.py  # Single-sheet and grouped Excel\n        export_log.py    # Timestamped audit log\n        incremental.py   # UID tracking for skip-already-exported\n        manifest.py      # SHA-256 hash manifest\n        mbox_export.py   # Standard MBOX archive\n        pdf_export.py    # PDF document\n        zipper.py        # Zip the export directory\n    ui/\n        app.py           # Main wizard window\n        strings.py       # All user-visible text (i18n-ready)\n        theme.py         # Light + dark palettes (WCAG AA)\n        screens/         # 7 wizard screens + BaseScreen skeleton\n```\n\n## License\n\nGPL-3.0-or-later. See [LICENSE](LICENSE) for details.\n\nCopyright (c) 2026+ Eric C. Mumford \u003ceric@mumfordengineering.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheymumford%2Fmailpail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheymumford%2Fmailpail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheymumford%2Fmailpail/lists"}