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 and 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:

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

Example:

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

GET https://<Server URL>/api/mailboxes/
X-Imap-Host: <IMAP_HOST>
X-Imap-Port: <IMAP_PORT>
X-Imap-Secure: <IMAP_SECURE>
X-Imap-User: <IMAP_USER>
X-Imap-Pass: <IMAP_PASS>

Example

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

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:

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

GET https://<Server URL>/api/mailboxes/<Mailbox Path>
X-Imap-Host: <IMAP_HOST>
X-Imap-Port: <IMAP_PORT>
X-Imap-Secure: <IMAP_SECURE>
X-Imap-User: <IMAP_USER>
X-Imap-Pass: <IMAP_PASS>

Example

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

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:

{
  "success": true,
  "uids": [
    17563,
    17684,
    17685,
    17686,
    17701,
    17703,
    17704,
    17711
  ],
  "total": 8
}

Get parsed message with attachments

GET https://<Server URL>/api/mailboxes/<Mailbox Path>/messages/<Message UID>
X-Imap-Host: <IMAP_HOST>
X-Imap-Port: <IMAP_PORT>
X-Imap-Secure: <IMAP_SECURE>
X-Imap-User: <IMAP_USER>
X-Imap-Pass: <IMAP_PASS>

Example

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

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.