This is an IMAP library for Haskell that aims to be efficient, easy to use, transparent when it comes to underlying libraries and support results streaming. To this end it employs ListT, so you can use it with any concurrency management library of your choosing.

It tries to implement RFC-3501 as faithfully as possible, diverging from it where we noticed that servers have different ideas. If you want to understand this library, it's highly recommended to skim through that RFC first.

Usage

For a description of types used in this tutorial or an in-depth description of functions presented, please check the documentation or the source code.

All of the commands will output their results in ListT and MonadIO. Results consist of a list of UntaggedResults followed by a single TaggedResult that describes the command state (if it succeeded or failed).

We provide a helper function that simplifies the output types for the cases when you don't care about the streaming and just want a list of UntaggedResults or an error message. Depending on your needs you will probably use it for all the commands that are not FETCH.

Also, remember that you probably have to keep the connection alive so that the server doesn't disconnect you. Send a noop from time to time to achieve that.

Simple, no streaming

You need a connection object first, so that you can execute commands on it. It's produced by connectServer, which accepts parameters from Network.Connection. Say you want to connect to gmail:

From now on you can run commands on this connection. The second parameter to connectServer is `Maybe IMAPSettings`. If settings are not provided, sane defaults will be used. We will use the simpleFormat helper function to convert from ListT to IO. Let's log in:

That's where streaming comes in handy - if these were message bodies you would probably like to do something with them before all are downloaded.

Replies we didn't expect

IMAP protocol allows for messages pushed to the client at any time, even when they're not requested. This is used to notify the client that a new message had arrived, or as status of a message had changed as it was read by another client. These server messages wait for you in a bounded message queue and you can read them like: