Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gerold-penz/gp-imap-rest-api
IMAP REST API with Bun und SvelteKit
https://github.com/gerold-penz/gp-imap-rest-api
api bun docker imap imapflow postal-mime rest server sveltekit typescript
Last synced: 1 day ago
JSON representation
IMAP REST API with Bun und SvelteKit
- Host: GitHub
- URL: https://github.com/gerold-penz/gp-imap-rest-api
- Owner: gerold-penz
- License: mit
- Created: 2024-09-26T16:57:36.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-11-20T09:10:22.000Z (2 months ago)
- Last Synced: 2024-11-20T11:13:15.864Z (2 months ago)
- Topics: api, bun, docker, imap, imapflow, postal-mime, rest, server, sveltekit, typescript
- Language: TypeScript
- Homepage:
- Size: 164 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Gp-Imap-Rest-Api
This is a small program that can be executed via Docker.
The calls are passed as HTTP requests.
The return is always a JSON string.
This program is based on the wonderful work of
[ImapFlow](https://github.com/postalsys/imapflow) and
[Postal-Mime](https://github.com/postalsys/postal-mime).
What can the program do so far?
- List all IMAP mailboxes.
- List the UIDs of all messages in a mailbox.
- Parse and return a message including attachments (Base64 encoded).
This is all the program can do at the moment, but further functions are planned.
## Docker-Compose File
This Docker Compose file is all you need to start the server.
No data is saved.
_docker-compose.yaml:_
```yaml
services:
gp-imap-rest-api:
image: ghcr.io/gerold-penz/gp-imap-rest-api
ports:
- "3000:3000"
```
## Data storage
**No data is saved.**
Each request must contain the credentials to the IMAP server in the header.
## HTTP Header
with IMAP credentials
Every HTTP request to the “Gp-Imap-Rest-Api Server” must contain the
access data to the IMAP server.
To ensure that this is not transferred in plain text,
this access data must be transferred in the HTTP header.
If HTTPS is used, the header is transmitted to the server in encrypted form.
The header entries required for this all start with `X-Imap-`.
### X-Imap Headers
Descriptions taken from the
[documentation of ImapFlow](https://imapflow.com/module-imapflow-ImapFlow.html)
_Example:_
```http request
X-Imap-Host: imap.example.com
X-Imap-Port: 993
X-Imap-Secure: true
X-Imap-User: [email protected]
X-Imap-Pass: examplePassword123
```
#### X-Imap-Host
Hostname of the IMAP server
#### X-Imap-Port
Port number for the IMAP server
#### X-Imap-Secure
`true|false`
_optional_, Default: false
Should the connection be established over TLS.
If `false` then connection is upgraded to TLS using STARTTLS
extension before authentication.
#### X-Imap-Servername
_optional_
Servername for SNI (or when host is set to an IP address).
#### X-Imap-Disable-Compression
`true|false`
_optional_, Default: false
If `true` then client does not try to use COMPRESS=DEFLATE extension.
#### X-Imap-User
Username for plain-text authentication.
#### X-Imap-Pass
_optional_
Password for plain-text authentication.
#### X-Imap-Access-Token
_optional_
OAuth2 Access Token, if using OAuth2 authentication.
#### X-Imap-Disable-Auto-Idle
`true|false`
_optional_, Default: false
If `true` then IDLE is not started automatically.
Useful if you only need to perform specific tasks over the connection
#### X-Imap-Tls-Reject-Unauthorized
`true|false`
_optional_, Default: true
If `false` then client accepts self-signed and expired
certificates from the server.
## Usage
### Get all mailboxes
```http
GET https:///api/mailboxes/
X-Imap-Host:
X-Imap-Port:
X-Imap-Secure:
X-Imap-User:
X-Imap-Pass:
```
#### Example
```http request
GET https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/
X-Imap-Host: imap.example.com
X-Imap-Port: 993
X-Imap-Secure: true
X-Imap-User: [email protected]
X-Imap-Pass: examplePassword123
```
```shell
curl --request GET \
--url https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/ \
--header 'X-Imap-Host: imap.example.com' \
--header 'X-Imap-Port: 993' \
--header 'X-Imap-Secure: true' \
--header 'X-Imap-User: [email protected]' \
--header 'X-Imap-Pass: examplePassword123'
```
_Response:_
```json
{
"success": true,
"mailboxes": [
{
"path": "INBOX",
"pathAsListed": "INBOX",
"flags": [
"\\HasNoChildren"
],
"delimiter": "/",
"listed": true,
"parentPath": "",
"parent": [],
"name": "INBOX",
"subscribed": true,
"specialUse": "\\Inbox",
"specialUseSource": "name"
},
{
"path": "Sent",
"pathAsListed": "Sent",
"flags": [
"\\HasNoChildren",
"\\UnMarked",
"\\Sent"
],
"delimiter": "/",
"listed": true,
"parentPath": "",
"parent": [],
"name": "Sent",
"subscribed": true,
"specialUse": "\\Sent",
"specialUseSource": "extension"
}
]
}
```
### Get all message UIDs of one mailbox
```http
GET https:///api/mailboxes/
X-Imap-Host:
X-Imap-Port:
X-Imap-Secure:
X-Imap-User:
X-Imap-Pass:
```
#### Example
```http request
GET https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX
X-Imap-Host: imap.example.com
X-Imap-Port: 993
X-Imap-Secure: true
X-Imap-User: [email protected]
X-Imap-Pass: examplePassword123
```
```shell
curl --request GET \
--url https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX \
--header 'X-Imap-Host: imap.example.com' \
--header 'X-Imap-Port: 993' \
--header 'X-Imap-Secure: true' \
--header 'X-Imap-User: [email protected]' \
--header 'X-Imap-Pass: examplePassword123'
```
_Response:_
```json
{
"success": true,
"uids": [
17563,
17684,
17685,
17686,
17701,
17703,
17704,
17711
],
"total": 8
}
```
### Get parsed message with attachments
```http
GET https:///api/mailboxes//messages/
X-Imap-Host:
X-Imap-Port:
X-Imap-Secure:
X-Imap-User:
X-Imap-Pass:
```
#### Example
```http request
GET https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX/messages/1234
X-Imap-Host: imap.example.com
X-Imap-Port: 993
X-Imap-Secure: true
X-Imap-User: [email protected]
X-Imap-Pass: examplePassword123
```
```shell
curl --request GET \
--url https://gp-imap-rest-api.gerold-penz.at/api/mailboxes/INBOX/messages/1234 \
--header 'X-Imap-Host: imap.example.com' \
--header 'X-Imap-Port: 993' \
--header 'X-Imap-Secure: true' \
--header 'X-Imap-User: [email protected]' \
--header 'X-Imap-Pass: examplePassword123'
```
## Usage inside a N8N workflow
The "Get parsed message" node is the HTML request which
uses the Gp-Imap-Rest-Api to fetch the attachments.