Introduction

IMAP-Observer is a library for processing incoming emails in a more functional way. For that it uses com.sun.mail.imap.IdleManager for listening to one or more folders.

Under the imap_observer.extras namespace you'll find helper functions for aiding you further.

Overview

The most important functions are com.markusaschl.imap-observer/make-observer and com.markusaschl.imap-observer.extras/get-message. The first one is for listening for incoming emails on the specified folder(s), the second one is for parsing the email into a more readable format. That format consists of a map exposing some headers and all bodyparts.

make-observer

Usually you'll want to make an observer. You do that like this:

(def +observer+ (observer/make-observer
                 {:host "example.com",
                  :username "user@example.com",
                  :password "password",
                  :imap-protocol "imaps"}
                 [{:name "INBOX"
                   :mode (:read-write extras/folder-modes)
                   :on-messages-added #(prn %)}])

It's better if you put your credentials into a edn-file under your resources folder though. Then, you'll be able to do this:

(def observer (imap-observer/make-observer
               (->> (clojure.java.io/resource "mail-properties.edn")
                    slurp
                    clojure.edn/read-string)
               [{:name "INBOX"
                 :mode (:read-write imap-observer.extras/folder-modes)
                 :on-messages-added #(prn %)}]))

The first argument for make-observer is a map consisting of attributes required for establishing a connection to the imap-server. The second argument consists of an array containing a series of folders you'll want to subscribe to.

For the first argument, these are the available properties:

• :imap-protocol
• :host
• :username
• :password
• and :session-properties

':session-properties' is also a map, which is then converted into a java.util.Property object, which in turn is passed to jakarta.mail.Session/getInstance.

For a list of all the properties you can use, see the com.sun.mail.imap documentation.

The second argument for make-observer consists of an array containing the folders you want to subscribe to. The available properties are:

• :name
• :mode
• :on-messages-added
• :on-messages-removed
• :on-folder-opened

Notes

1. Posible :mode(s) are jakarta.mail.Folder/READ_ONLY or jakarta.mail.Folder/READ_WRITE. For convenience reasons, those two are exported as a map in imap-observer.extras/folder-modes
2. :name is the name of an existing mailbox folder
3. The functions :on-messages-added and :on-messages-removed are called with an array of jakarta.mail.Message. See also jakarta.mail.Message
4. The function :on-folder-openend is called with the appropriate jakarta.mail.Folder object. See also jakarta.mail.Folder

get-message

This function parses the email into its most commonly used properties (:from, :recipients, :subject, :bodyparts, :in-reply-to, :message-id). The complete message is saved in the :original property.