From e1d9dcbba3c2590787baeccf55ba5337313e6444 Mon Sep 17 00:00:00 2001
From: kaj dijkstra <kajdijkstra@protonmail.com>
Date: Tue, 30 Dec 2025 20:35:14 +0100
Subject: [PATCH] Readme

---
 README.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 212 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9c5518f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,212 @@
+# ProtonMail IMAP HTTP Gateway
+
+This project exposes a lightweight HTTP API on top of an IMAP mailbox, intended for **read-only inspection and basic message management** (read, delete) using ProtonMail Bridge or any IMAP-compatible server.
+
+It uses Node.js, Express, and IMAP to translate mailbox operations into JSON responses.
+
+---
+
+## Overview
+
+The application consists of two layers:
+
+1. **IMAP access layer**
+
+   * Connects to an IMAP server
+   * Fetches recent messages or individual messages
+   * Parses emails into structured objects
+   * Supports folder listing, marking messages as read, and deletion
+
+2. **HTTP server layer**
+
+   * Exposes REST-style endpoints
+   * Returns formatted JSON responses
+   * Designed for local tools, dashboards, or automation
+
+---
+
+## Requirements
+
+* Node.js 18 or newer (ES modules required)
+* ProtonMail Bridge **or** any IMAP server
+* Valid IMAP credentials
+
+---
+
+## Installation
+
+```bash
+npm install
+```
+
+Required dependencies:
+
+* `express`
+* `imap`
+* `mailparser`
+
+---
+
+## Configuration
+
+Create a `data.json` file in the project root:
+
+```json
+{
+	"user": "imap-username",
+	"password": "imap-password",
+	"host": "127.0.0.1",
+	"port": 1143,
+	"tls": false
+}
+```
+
+Notes:
+
+* ProtonMail **requires ProtonMail Bridge** to expose IMAP locally.
+* TLS depends on your bridge or server configuration.
+
+---
+
+## Running the Server
+
+```bash
+node index.js
+```
+
+Default port:
+
+```
+http://localhost:3000
+```
+
+---
+
+## API Endpoints
+
+### List recent emails (last 10)
+
+```
+GET /emails
+```
+
+Response:
+
+```json
+{
+	"type": "emails",
+	"data": [
+		{
+			"seqno": 42,
+			"subject": "Example subject",
+			"from": "Sender <sender@example.com>",
+			"date": "2025-01-01T12:00:00.000Z"
+		}
+	]
+}
+```
+
+---
+
+### List emails from a specific folder
+
+```
+GET /emails/folder/{folderPath}
+```
+
+Example:
+
+```
+/emails/folder/INBOX/Archive
+```
+
+Folder paths are URL-decoded and support nesting.
+
+---
+
+### Fetch a single email (full body)
+
+```
+GET /message/{seqno}
+```
+
+Response includes:
+
+* subject
+* sender
+* date
+* plain text body
+
+---
+
+### Mark email as read
+
+```
+GET /flag/read/{seqno}
+```
+
+Adds the `\Seen` flag.
+
+---
+
+### Remove an email
+
+```
+GET /removeMessage/{seqno}
+```
+
+Marks the message as `\Deleted` and expunges it.
+
+---
+
+### List all folders
+
+```
+GET /folders
+```
+
+Returns a flattened list of folder paths.
+
+---
+
+## Design Notes
+
+* IMAP connections are **short-lived**
+
+  * Each request opens and closes its own connection
+* Messages are referenced by **sequence number**
+
+  * Sequence numbers change when the mailbox changes
+* Responses are formatted with tab-indented JSON for readability
+* No authentication layer is provided
+
+  * Intended for trusted local usage
+
+---
+
+## Limitations
+
+* No pagination support
+* No attachment handling
+* Sequence numbers are not stable identifiers
+* No concurrency control
+* No caching
+
+---
+
+## Intended Use Cases
+
+* Local dashboards
+* Email inspection tools
+* Automation scripts
+* Bridging IMAP into environments that cannot speak IMAP directly
+
+---
+
+## Security Notice
+
+This server exposes mailbox access over HTTP.
+Run it **only on trusted machines and networks**.
+
+Do not expose it publicly.
+