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

npm install

Required dependencies:

• express
• imap
• mailparser

---

Configuration

Create a data.json file in the project root:

{
	"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

node index.js

Default port:

http://localhost:3000

---

API Endpoints

List recent emails (last 10)

GET /emails

Response:

{
	"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.