Network.POP3.Client

This module contains function to connect to a POP3 server and retrieve messages and other information from it.

This library is designed to be safe to use: connections are guaranteed to be closed after the POP3 commands have been executed.

Example:

       main :: IO ()
       main = do
           result <- withPOP3 "pop3.example.org" defaultPort $ do
               r <- authenticate "user at host.com" "my_pass"
               case r of
                   Left s  -> liftIO $ putStrLn ("Error: " ++ s)
                   Right _ -> liftIO $ putStrLn ("Authentication OK")
               r <- getMailboxBytes
               case r of
                   Left s  -> liftIO $ putStrLn ("Error: " ++ s)
                   Right n -> liftIO $ putStrLn ("Size of mailbox:    " ++ show n)
               r <- getNumberOfMessages
               case r of
                   Left s    -> do
                       liftIO $ putStrLn ("Error: " ++ s)
                       return $ Left s -- withPOP3 will return this error message
                   Right num -> do
                       liftIO $ putStrLn ("Number of messages: " ++ show num)
                       -- read the most recently received message and return it
                       getMessage num
           -- result is the message which was read above (or an error message)
           putStrLn $ show result

Documentation

defaultPort :: Int

Default POP3 port (110)

Connecting and authenticating

withPOP3 :: String -> Int -> POP3 a -> IO a

Connects to the given host and port, executes the given POP3 action(s), closes the connection, and finally returns the result op the (last) POP3 action. The connection is guaranteed to be closed before returning from this function, even when an exception occurs during the session.

authenticate :: String -> String -> POP3 Response

Send the given username and password. This has to be the first command sent to the POP3 server. Other POP3 actions can only be executed after a successful authentication.

Retrieving mailbox statistics

getMailboxBytes :: POP3 (Either String Integer)

Returns the size of the POP3 mailbox in bytes.

getNumberOfMessages :: POP3 (Either String Integer)

Returns the number of messages stored in the POP3 mailbox.

Retrieving messages

getUniqueID :: MessageID -> POP3 (Either String String)

Returns the unique ID (UIDL) of a message on the server. The message ID should be in the range [1..getNumberOfMessages].

getSize :: MessageID -> POP3 (Either String Integer)

Returns the size of a message on the server in bytes. Note that this may not correspond exactly to the size of the message as it is downloaded, because of newline and escape values. The message ID should be in the range [1..getNumberOfMessages].

getMessage :: MessageID -> POP3 Response

Retrieves a POP3 message from the server and returns it parsed as a Message. The message ID should be in the range [1..getNumberOfMessages].

getFirstNLines :: MessageID -> Integer -> POP3 Response

Retrieves a the headers and the first n lines of a message from the server and returns it parsed as a Message. The message ID should be in the range [1..getNumberOfMessages].

getHeaders :: MessageID -> POP3 Response

Retrieves a the headers of a message from the server and returns it parsed as a Message. The message ID should be in the range [1..getNumberOfMessages].