213 lines
3.1 KiB
Markdown
213 lines
3.1 KiB
Markdown
# 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.
|
|
|