Proton-Api/README.md

# 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.