llms.txt

# UniversalInvoiceMail

Canonical repository: https://github.com/doc-bricks/UniversalInvoiceMail

UniversalInvoiceMail is a local-first Windows desktop app for collecting invoices and receipts from email accounts. It supports IMAP, optional Gmail API access, profile-based filters, Gmail raw queries, attachment-to-PDF conversion, OCR hooks, duplicate detection, a private local archive and DATEV-style cp1252 CSV export.

## Audience

- **Freelancers and small businesses** in German-speaking markets who collect invoices from Gmail or IMAP accounts and need DATEV-compatible CSV exports for their tax advisor.
- **Privacy-conscious Windows users** who want a local-first invoice archive without storing data in cloud services.
- **Bookkeepers and accountants** who fetch and pre-sort client invoices from email before handing off to DATEV or similar systems.
- **Developers** building or extending PySide6 Windows desktop workflows with IMAP, Gmail API, OCR, and CSV export.
- **Power users** who want profile-based mail filtering, Gmail raw query support, and duplicate-safe archiving without a subscription.

## Search Phrases

- `local invoice email archive`
- `Gmail invoice downloader`
- `IMAP receipt extractor`
- `DATEV CSV export from email`
- `PySide6 invoice manager`
- `OCR invoice attachment archive`
- `privacy-first accounting document workflow`
- `Windows local-first bookkeeping handoff`
- `DATEV Buchungsstapel aus E-Mail`
- `Rechnungen aus Gmail archivieren`

## Last-checked: 2026-06-12

Important files:

- `README.md`: English user-facing project overview.
- `README-DE.md`: German project overview.
- `USER_GUIDE.md`: German setup and workflow guide.
- `EXPORTFORMAT.md`: implemented `universalinvoicemail-invoicebundle-v1.json` exchange contract with desktop export/import.
- `UniversalInvoiceMail.py`: PySide6 desktop application.
- `datev_exporter.py`: DATEV CSV export helper.
- `tests/`: mocked unit and integration tests.

Safety boundary:

- Do not commit real invoices, mailbox exports, Gmail OAuth tokens, `credentials.json`, `token.json`, passwords or local archive folders.
- Runtime data belongs under `%USERPROFILE%\.universal_invoice_mail\`.
- The exchange format is metadata-first; full attachments or mail bodies must be explicit opt-in exports.
- This is not a hosted invoice platform, mail marketing tool or cloud bookkeeping service.

Verification:

- Run `PYTHONIOENCODING=utf-8 python -m pytest -q`.
- Run `PYTHONIOENCODING=utf-8 python -m py_compile UniversalInvoiceMail.py datev_exporter.py test_helpers.py tests/test_integration.py tests/test_ui_accessibility.py`.