proton2m365 0.1.0__tar.gz

proton2m365-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+.gstack/
+.pytest_cache/
+.venv/
+*.egg-info/
+*.log
+# migration data: never commit (scripts/publish-files.txt has the same never-list)
+*.sqlite*
+*.bak-v*
+*.receipt.*
+verify-report*.csv
+token_cache*
+upload-probe.log
+upload-trial.log

proton2m365-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to proton2m365. Versions follow the git tags (`vX.Y.Z`).
+
+## v0.1.0 (2026-11-07)
+
+First public release. Microsoft 365 work and school accounts are supported; Outlook.com and Microsoft 365
+Personal/Family are experimental.
+
+- Move a Proton Mail Export Tool backup into Microsoft 365 over IMAP and Microsoft Graph: received dates, read
+  state, folders (from Proton's metadata) and labels as categories are kept; drafts, Trash and Spam are left out
+  unless included; stopping and resuming never uploads a message twice.
+- `migrate EXPORT` runs the whole thing in one resumable command; `scan`, `plan`, `upload`, `tag`, `verify` and
+  `prune` remain available one at a time, each ending with a `Next:` line.
+- `verify` ends with one outcome (PASSED, SAMPLE OK, INCOMPLETE, FAILED) and writes a receipt
+  (`.receipt.html`, `.txt`, `.json`) that accounts for every export file; `--all` also finds duplicate copies,
+  and `--content` compares text, attachments, HTML text and links with the export.
+- Bring your own sign-in app (docs/setup-own-app.md); device-code sign-in over SSH; each state file is bound to
+  one mailbox; a lease in the mailbox keeps two computers from uploading into it at once.
+- `plan --exclude-label`, `--exclude-file`, `--map-folder` and `--map-label`, saved and reused by a re-plan.
+- Adaptive upload pacing, `selftest`, `doctor --issue`, `sample-export`, `--json` on every command, stable
+  `P2M-` error codes and exit codes, and tested on Linux, macOS and Windows.

proton2m365-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Cilley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proton2m365-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: proton2m365
+Version: 0.1.0
+Summary: Move a Proton Mail Export Tool backup into Microsoft 365 or Outlook.com, with a receipt for every message.
+Project-URL: Homepage, https://github.com/jonathan-opmodi/proton2m365
+Project-URL: Documentation, https://github.com/jonathan-opmodi/proton2m365#readme
+Project-URL: Issues, https://github.com/jonathan-opmodi/proton2m365/issues
+Project-URL: Changelog, https://github.com/jonathan-opmodi/proton2m365/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email migration,eml,imap,microsoft 365,outlook,proton,proton mail
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: imapclient>=4.1.0
+Requires-Dist: msal-extensions>=1.3.1
+Requires-Dist: msal>=1.39.0
+Description-Content-Type: text/markdown
+
+# proton2m365
+
+Move a **Proton Mail Export Tool** backup into **Microsoft 365** or **Outlook.com**, without Proton Mail
+Bridge or a paid Proton plan, and get a receipt that accounts for every message.
+
+- Keeps each message's original received date and read/unread state.
+- Puts mail in the right folder (Inbox, Sent Items, Archive, your own folders) using Proton's metadata.
+- Turns Proton labels into Outlook categories, and stars into a category or a flag.
+- Can stop and resume at any time without uploading anything twice.
+- Ends with `verify`: one outcome (PASSED, SAMPLE OK, INCOMPLETE or FAILED) and a receipt file listing every
+  export file as migrated, intentionally skipped (and why), or unresolved.
+
+Status: v0.1. Microsoft 365 work and school accounts are tested live. **Outlook.com and Microsoft 365
+Personal/Family are experimental** until the live checks in [docs/how-it-works.md](docs/how-it-works.md#outlookcom)
+have passed. Support is best effort through GitHub issues.
+
+## Prerequisites
+
+- Python 3.12 or newer, and either [pipx](https://pipx.pypa.io) or [uv](https://docs.astral.sh/uv/).
+  - macOS: `brew install pipx` (or `brew install uv`)
+  - Windows: install Python from python.org, then `py -m pip install --user pipx` (or `winget install astral-sh.uv`)
+  - Linux: your distribution's `pipx` package (or the uv installer)
+- A Proton Mail export made with Proton's **Export Tool** (the folder that contains `labels.json` and pairs of
+  `.eml` and `.metadata.json` files). Unzip it first.
+- The mailbox you are moving into: a Microsoft 365 work or school account, or an Outlook.com account.
+- **Your own sign-in app** for migrating (not needed to try it). proton2m365 does not ship one, so your mail is only
+  ever reached through an app you control. Registering it is a one-time setup, see
+  [docs/setup-own-app.md](docs/setup-own-app.md):
+  - work or school account: an administrator of your organization registers it, about 10 minutes;
+  - personal account (Outlook.com, Microsoft 365 Family): Microsoft lets only organizations register apps, so
+    you first create a free Azure account (it asks for a card to verify you; the app itself costs nothing),
+    about 20 minutes.
+
+## Try it (no sign-in, nothing written to any mailbox)
+
+```sh
+pipx install proton2m365
+proton2m365 sample-export ./sample
+proton2m365 scan ./sample
+proton2m365 plan --dry-run ./sample
+```
+
+With uv instead of pipx, run each command as `uvx proton2m365 ...` and skip the install line.
+
+`plan --dry-run` shows what would be uploaded: 34 of the sample's 40 messages, which folders they would go
+to, which labels become categories, and the 6 that are skipped and why. Try it on your own export next; it
+still writes nothing anywhere.
+
+## Migrate your export
+
+First register your sign-in app and put its client ID and tenant in `~/.config/proton2m365/config.toml`
+([docs/setup-own-app.md](docs/setup-own-app.md)). Then:
+
+```sh
+proton2m365 selftest                       # live checks with synthetic messages; cleans up after itself
+proton2m365 scan /path/to/export
+proton2m365 plan /path/to/export           # writes ./state.sqlite; add --exclude-label "Name" to leave mail out
+proton2m365 upload                         # hours for a large export; safe to stop and run again
+proton2m365 tag                            # applies categories and flags
+proton2m365 verify --all                   # the outcome, and the receipt
+```
+
+Or all of it in one command, which asks before uploading and can be run again to continue where it stopped:
+
+```sh
+proton2m365 migrate /path/to/export        # add --exclude-label "Name" to leave mail out
+```
+
+Every command ends with a `Next:` line naming the command to run next. `verify` writes three receipt files next
+to the state file: `state.receipt.html` (open it in a browser, or print it), `state.receipt.txt` and the full
+per-message `state.receipt.json`. Keep your Proton export until you have read the receipt.
+
+### Signing in
+
+The first online command opens your browser. Choose the mailbox you are moving **into**, and approve the
+permissions your app asks for. Over SSH or without a display, proton2m365 uses a device code instead (it may ask twice:
+once for Microsoft Graph, once for IMAP). Each state file remembers its mailbox and refuses any other.
+
+## What you will see in Outlook
+
+| From Proton | In Outlook |
+|---|---|
+| Inbox, Sent, Archive | Inbox, Sent Items, Archive |
+| your folders (`Projects/Alpha`) | the same folders, created for you |
+| labels | categories (with the nearest Outlook color) |
+| starred | a "Starred" category, or a flag with `plan --starred-as-flag` |
+| received date, read/unread | kept |
+| drafts, Trash, Spam | skipped (Trash and Spam can be included with `--include-trash`, `--include-spam`) |
+
+Want it somewhere else? `plan --map-folder "Projects=Clients"` moves a folder (and its subfolders), and
+`--map-label "Work=Office"` renames a category (`"Work="` drops it). The same mappings can live in
+`~/.config/proton2m365/config.toml` under `[map.folders]` and `[map.labels]`.
+
+Each uploaded message carries an added `X-Proton-Id` header, which is how proton2m365 finds it again. While
+`upload` or `prune` runs, a folder `_proton2m365_lease` holds one small message so that a second computer does
+not upload the same mail; it is emptied when the run ends.
+
+## What is not preserved
+
+Proton's conversation grouping, snooze and scheduled sends, and labels you exclude. Messages larger than the
+mailbox's size limit (35 MB by default) are skipped and listed. `verify` checks dates, read state, flags,
+categories, drafts and folders; `verify --content` also downloads the checked messages and compares their text,
+attachments, HTML text and links with the export (`verify --all --content` downloads the whole mailbox). The
+receipt says which of these were done.
+
+## If it stops
+
+Run the same command again: nothing that already arrived is sent twice. `proton2m365 status` shows where
+things stand without signing in. To start over, delete the state file (and its `.receipt.*` files) and run
+`plan` again; mail already uploaded is detected by its `X-Proton-Id` header.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done (verify: PASSED) |
+| 1 | unexpected error: a crash log was written; attach `proton2m365 doctor --issue` output to an issue |
+| 2 | usage, configuration, sign-in or connection error (the message starts with a `P2M-` code, see [docs/errors.md](docs/errors.md)) |
+| 3 | mailbox full |
+| 10 | verify: SAMPLE OK, some messages not checked yet (`verify --all`) |
+| 11 | incomplete: messages still need work (the `Next:` line says which command) |
+| 12 | failed: a check did not match, or a selftest check failed |
+| 13 | interrupted: run the same command again to resume |
+| 14 | verify would have PASSED, but its receipt could not be saved |
+
+## Why not Thunderbird or a paid EML converter?
+
+They can move `.eml` files, and that may be all you need. As far as we know none of them reads Proton's
+metadata files, so Proton's folders, labels and read state are not carried over, and nothing tells you
+afterwards whether every message arrived. proton2m365 exists for those things.
+Tools built on Proton Mail Bridge (imapsync and others) need a paid Proton plan and a running Bridge.
+
+## More
+
+- [How it works](docs/how-it-works.md): export format, folder routing, why IMAP plus Graph
+- [Errors](docs/errors.md): every `P2M-` code and what to do
+- [Upgrading](docs/upgrading.md): pinning a version, resuming across versions
+- [Using your own Entra app](docs/setup-own-app.md)
+- [Security](SECURITY.md): what stays on your computer
+- [Contributing](CONTRIBUTING.md)
+
+MIT licensed. Not affiliated with Proton AG or Microsoft.

proton2m365-0.1.0/README.md

@@ -0,0 +1,142 @@
+# proton2m365
+
+Move a **Proton Mail Export Tool** backup into **Microsoft 365** or **Outlook.com**, without Proton Mail
+Bridge or a paid Proton plan, and get a receipt that accounts for every message.
+
+- Keeps each message's original received date and read/unread state.
+- Puts mail in the right folder (Inbox, Sent Items, Archive, your own folders) using Proton's metadata.
+- Turns Proton labels into Outlook categories, and stars into a category or a flag.
+- Can stop and resume at any time without uploading anything twice.
+- Ends with `verify`: one outcome (PASSED, SAMPLE OK, INCOMPLETE or FAILED) and a receipt file listing every
+  export file as migrated, intentionally skipped (and why), or unresolved.
+
+Status: v0.1. Microsoft 365 work and school accounts are tested live. **Outlook.com and Microsoft 365
+Personal/Family are experimental** until the live checks in [docs/how-it-works.md](docs/how-it-works.md#outlookcom)
+have passed. Support is best effort through GitHub issues.
+
+## Prerequisites
+
+- Python 3.12 or newer, and either [pipx](https://pipx.pypa.io) or [uv](https://docs.astral.sh/uv/).
+  - macOS: `brew install pipx` (or `brew install uv`)
+  - Windows: install Python from python.org, then `py -m pip install --user pipx` (or `winget install astral-sh.uv`)
+  - Linux: your distribution's `pipx` package (or the uv installer)
+- A Proton Mail export made with Proton's **Export Tool** (the folder that contains `labels.json` and pairs of
+  `.eml` and `.metadata.json` files). Unzip it first.
+- The mailbox you are moving into: a Microsoft 365 work or school account, or an Outlook.com account.
+- **Your own sign-in app** for migrating (not needed to try it). proton2m365 does not ship one, so your mail is only
+  ever reached through an app you control. Registering it is a one-time setup, see
+  [docs/setup-own-app.md](docs/setup-own-app.md):
+  - work or school account: an administrator of your organization registers it, about 10 minutes;
+  - personal account (Outlook.com, Microsoft 365 Family): Microsoft lets only organizations register apps, so
+    you first create a free Azure account (it asks for a card to verify you; the app itself costs nothing),
+    about 20 minutes.
+
+## Try it (no sign-in, nothing written to any mailbox)
+
+```sh
+pipx install proton2m365
+proton2m365 sample-export ./sample
+proton2m365 scan ./sample
+proton2m365 plan --dry-run ./sample
+```
+
+With uv instead of pipx, run each command as `uvx proton2m365 ...` and skip the install line.
+
+`plan --dry-run` shows what would be uploaded: 34 of the sample's 40 messages, which folders they would go
+to, which labels become categories, and the 6 that are skipped and why. Try it on your own export next; it
+still writes nothing anywhere.
+
+## Migrate your export
+
+First register your sign-in app and put its client ID and tenant in `~/.config/proton2m365/config.toml`
+([docs/setup-own-app.md](docs/setup-own-app.md)). Then:
+
+```sh
+proton2m365 selftest                       # live checks with synthetic messages; cleans up after itself
+proton2m365 scan /path/to/export
+proton2m365 plan /path/to/export           # writes ./state.sqlite; add --exclude-label "Name" to leave mail out
+proton2m365 upload                         # hours for a large export; safe to stop and run again
+proton2m365 tag                            # applies categories and flags
+proton2m365 verify --all                   # the outcome, and the receipt
+```
+
+Or all of it in one command, which asks before uploading and can be run again to continue where it stopped:
+
+```sh
+proton2m365 migrate /path/to/export        # add --exclude-label "Name" to leave mail out
+```
+
+Every command ends with a `Next:` line naming the command to run next. `verify` writes three receipt files next
+to the state file: `state.receipt.html` (open it in a browser, or print it), `state.receipt.txt` and the full
+per-message `state.receipt.json`. Keep your Proton export until you have read the receipt.
+
+### Signing in
+
+The first online command opens your browser. Choose the mailbox you are moving **into**, and approve the
+permissions your app asks for. Over SSH or without a display, proton2m365 uses a device code instead (it may ask twice:
+once for Microsoft Graph, once for IMAP). Each state file remembers its mailbox and refuses any other.
+
+## What you will see in Outlook
+
+| From Proton | In Outlook |
+|---|---|
+| Inbox, Sent, Archive | Inbox, Sent Items, Archive |
+| your folders (`Projects/Alpha`) | the same folders, created for you |
+| labels | categories (with the nearest Outlook color) |
+| starred | a "Starred" category, or a flag with `plan --starred-as-flag` |
+| received date, read/unread | kept |
+| drafts, Trash, Spam | skipped (Trash and Spam can be included with `--include-trash`, `--include-spam`) |
+
+Want it somewhere else? `plan --map-folder "Projects=Clients"` moves a folder (and its subfolders), and
+`--map-label "Work=Office"` renames a category (`"Work="` drops it). The same mappings can live in
+`~/.config/proton2m365/config.toml` under `[map.folders]` and `[map.labels]`.
+
+Each uploaded message carries an added `X-Proton-Id` header, which is how proton2m365 finds it again. While
+`upload` or `prune` runs, a folder `_proton2m365_lease` holds one small message so that a second computer does
+not upload the same mail; it is emptied when the run ends.
+
+## What is not preserved
+
+Proton's conversation grouping, snooze and scheduled sends, and labels you exclude. Messages larger than the
+mailbox's size limit (35 MB by default) are skipped and listed. `verify` checks dates, read state, flags,
+categories, drafts and folders; `verify --content` also downloads the checked messages and compares their text,
+attachments, HTML text and links with the export (`verify --all --content` downloads the whole mailbox). The
+receipt says which of these were done.
+
+## If it stops
+
+Run the same command again: nothing that already arrived is sent twice. `proton2m365 status` shows where
+things stand without signing in. To start over, delete the state file (and its `.receipt.*` files) and run
+`plan` again; mail already uploaded is detected by its `X-Proton-Id` header.
+
+### Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | done (verify: PASSED) |
+| 1 | unexpected error: a crash log was written; attach `proton2m365 doctor --issue` output to an issue |
+| 2 | usage, configuration, sign-in or connection error (the message starts with a `P2M-` code, see [docs/errors.md](docs/errors.md)) |
+| 3 | mailbox full |
+| 10 | verify: SAMPLE OK, some messages not checked yet (`verify --all`) |
+| 11 | incomplete: messages still need work (the `Next:` line says which command) |
+| 12 | failed: a check did not match, or a selftest check failed |
+| 13 | interrupted: run the same command again to resume |
+| 14 | verify would have PASSED, but its receipt could not be saved |
+
+## Why not Thunderbird or a paid EML converter?
+
+They can move `.eml` files, and that may be all you need. As far as we know none of them reads Proton's
+metadata files, so Proton's folders, labels and read state are not carried over, and nothing tells you
+afterwards whether every message arrived. proton2m365 exists for those things.
+Tools built on Proton Mail Bridge (imapsync and others) need a paid Proton plan and a running Bridge.
+
+## More
+
+- [How it works](docs/how-it-works.md): export format, folder routing, why IMAP plus Graph
+- [Errors](docs/errors.md): every `P2M-` code and what to do
+- [Upgrading](docs/upgrading.md): pinning a version, resuming across versions
+- [Using your own Entra app](docs/setup-own-app.md)
+- [Security](SECURITY.md): what stays on your computer
+- [Contributing](CONTRIBUTING.md)
+
+MIT licensed. Not affiliated with Proton AG or Microsoft.

proton2m365-0.1.0/SECURITY.md

@@ -0,0 +1,23 @@
+# Security
+
+## What leaves your computer
+
+Only calls to Microsoft: sign-in (login.microsoftonline.com), Microsoft Graph and Outlook IMAP. proton2m365
+sends no telemetry and talks to no other service.
+
+## What stays on your computer, and holds mailbox data
+
+| File | Holds | Protection |
+|---|---|---|
+| token cache (`~/.config/proton2m365/token_cache.bin`, or the OS secret store) | sign-in tokens | macOS Keychain, Windows DPAPI or Linux libsecret; otherwise an owner-only file (0600 on macOS and Linux) |
+| state file (`state.sqlite` by default) and its `.bak-v*` upgrade backups | message IDs, folder and category names, the mailbox address | your file permissions |
+| `<state>.receipt.json`, `.receipt.txt`, `.receipt.html`, `verify-report.csv` | the same, per message | owner-only (0600) where the OS supports it; on Windows they inherit your profile's permissions |
+| `crash-*.log` | a traceback, which can include addresses | owner-only (0600) |
+
+`doctor --issue` prints a report with names and addresses replaced by hashes; attach that to issues, never the
+files above.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting on this repository rather than a public issue. Support is
+best effort; expect a reply within a couple of weeks.

proton2m365-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "proton2m365"
+dynamic = ["version"]
+description = "Move a Proton Mail Export Tool backup into Microsoft 365 or Outlook.com, with a receipt for every message."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+keywords = ["proton", "proton mail", "microsoft 365", "outlook", "email migration", "imap", "eml"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: System Administrators",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Email",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "imapclient>=4.1.0",
+    "msal>=1.39.0",
+    "msal-extensions>=1.3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/jonathan-opmodi/proton2m365"
+Documentation = "https://github.com/jonathan-opmodi/proton2m365#readme"
+Issues = "https://github.com/jonathan-opmodi/proton2m365/issues"
+Changelog = "https://github.com/jonathan-opmodi/proton2m365/blob/main/CHANGELOG.md"
+
+[project.scripts]
+proton2m365 = "proton2m365.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+# Builds without git metadata (an sdist, a shallow checkout) still get a version.
+fallback-version = "0.0.0+unknown"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md", "SECURITY.md", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/proton2m365"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

proton2m365-0.1.0/src/proton2m365/__init__.py

@@ -0,0 +1 @@
+"""proton2m365: move a Proton Mail export into a Microsoft 365 mailbox."""