search

watchdogpolska / imap-to-webhook

MIT License
21 stars 5 forks source link

readme

imap-to-webhook

Build Status Docker Repository on Quay

A stateless service is designed to build a relay between an IMAP server and any web application in a simple, convenient way, well-known by web-developers, without delving into the format of the mail format.

Using the service requires only writing one HTTP endpoint!

It periodically retrieves IMAP messages from selected IMAP folder, parsers them into a convenient JSON object for use in web applications. Next to send to specified HTTP(S) endpoint. The message can be moved to another IMAP folder or deleted completely. In case of connection errors, the message is moved to another folder.

Send JSON object, among others includes:

Configuration

Configuration takes place via environment variables. The following environment variables are supported:

Name Description
IMAP_URL | URL connection to access mailbox. Example imap+ssl://user:pass@localhost/?inbox=INBOX
IMAP_URL?folder Folder to download messages
IMAP_URL?error | Folder to move messages on error (error)
IMAP_URL?success | Folder to store messages on success (success)
ON_SUCCESS | Action to perform on process messages. Available move, delete
WEBHOOK_URL | URL endpoint to send parsed messages. Example: https://httpbin.org/post
COMPRESSION_EML | Specifies whether the sent .eml file should be compressed or not. Example: true
DELAY | Length of the interval between the next downloading of the message in seconds. Default: 300
SENTRY_DSN Sentry DSN to report application exceptions. Not set to disable Sentry.

Request

Here ie example request which you can expect to receive:

{
    "headers": {
        "auto_reply_type": "vacation-reply",
        "cc": [],
        "date": "2018-07-30T11:33:22",
        "from": [
            "user-a@siecobywatelska.pl"
        ],
        "message_id": "<E1fk6QU-00CPTw-Ey@s50.hekko.net.pl>",
        "subject": "Odpowied\u017a automatyczna: \"Re: Problem z dostarczeniem odp. na fedrowanie\"",
        "to": [
            "user-b@siecobywatelska.pl"
        ],
        "to+": [
            "user-b@siecobywatelska.pl",
            "user-c@siecobywatelska.pl"
        ]
    },
    "text": {
        "content": "W dniach 30.07-17.08.2018 r. przebywam na urlopie.",
        "quote": ""
    },
    "files_count": 1,
    "files": [
        {
            "content": "MTIzNDU=",
            "filename": "my-doc.txt"
        }
    ],
    "eml": {
        "filename": "a9a7b32cdfa34a7f91c826ff9b3831bb.eml.gz",
        "compressed": true,
        "content": "...base64-encoded-gzipped-bytes..."
    }
}

It contains fields:

JSON Path Description
headers.auto_reply_type Indicates whether the message is automatic or send by human. Empty, if no indicators of automatic character were found.
headers.cc | List of e-mail address in CC
headers.date Date available of message. The values can be hijacked by the recipient to include any date
headers.from | List of address available in From header
headers.message_id | Message identifier from the Message-ID header
headers.subject An additional comment is not required
headers.to | List of e-mail address in To header
headers.to+ List of various potential message recipients address, even redirected.
text.content Text content of the message, converted from HTML (if available) or text form and truncated to the new content itself
text.quote Content truncated from a content that is potentially a quote
files_count Number of attachments
files.*.content Base-64 encoded binary content of the attachment
files.*.filename Filename of attachment
eml.filename Random file name with the correct extension
eml.compressed Determines whether the next field contains gzip compressed content or uncompressed.
eml.content | Original .eml message without any modifications, except lossless compresion

The request contains a header:

Content-Type: application/imap-to-webhook-v1+json

Run

$ docker build -t imap-to-webook:latest .
$ docker run -e IMAP_URL=imap://imap.example.com/ -e WEBHOOK_URL="https://example.com" imap-to-webhook:latest

Development

In order to facilitate the development, the docker-compose.yml file is provided.

$ git clone git@github.com:watchdogpolska/imap-to-webhook.git 
$ cd imap-to-webhook
$ cp .env.sample .env
$ docker-compose up

The following services are provided:

Testing

Following commands are required to run tests:

pip install -r requirements.txt
python test.py