gitignore

README.md

@@ -1,2 +1,70 @@
 # olm2eml
 
+Convert emails extracted from an Outlook for Mac OLM file into standard `.eml` files. This code is written by OpenCode Zen/Big Pickle.
+
+## Installation
+
+```bash
+git clone https://git.wimpomp.nl/wim/olm2eml.git
+cd olm2eml
+pip install .
+```
+
+## Usage
+
+Point the tool at the directory containing the OLM-extracted XML files:
+
+```bash
+olm2eml /path/to/olm_extracted_emails /path/to/output
+```
+
+Use `--preserve-structure` to mirror the account/folder hierarchy in the output:
+
+```bash
+olm2eml /path/to/olm_extracted_emails /path/to/output --preserve-structure
+```
+
+Use `--overwrite` to replace existing `.eml` files:
+
+```bash
+olm2eml /path/to/olm_extracted_emails /path/to/output --overwrite
+```
+
+You can also run the module directly without installing:
+
+```bash
+python olm_xml_to_eml.py /path/to/olm_extracted_emails /path/to/output
+```
+
+## Input format
+
+The tool expects the directory structure produced by OLM extraction tools (e.g. `olm-export`):
+
+```
+emails_root/
+├── Accounts/
+│   └── account@example.com/
+│       └── com.microsoft.__Messages/
+│           ├── Inbox/
+│           │   ├── message_00000.xml
+│           │   ├── message_00001.xml
+│           │   └── ...
+│           └── Sent Items/
+│               └── ...
+├── Local/
+│   └── ...
+└── Categories.xml
+```
+
+Each `message_*.xml` file contains the email metadata and body. Attachments are stored in sibling
+`com.microsoft.__Attachments/` folders and are referenced by the XML.
+
+## Output
+
+Standard `.eml` files (RFC 2822) compatible with any email client (Thunderbird, Outlook, Apple Mail, etc.). Each email
+preserves:
+
+- Subject, From, To, CC
+- Date, Message-ID, References, In-Reply-To
+- HTML body with plain text fallback
+- Attachments and inline images