Getting IMAP.pm up and running

This page is intended to give people willing to use the IMAP module an idea of how to get the module running, how to configure it, and what to expect from it.

What IMAP.pm does (or tries to do)

IMAP.pm, unlike POPFile's POP3 module, is not a proxy therefore no changes need to be made to your mail client configuration when you use IMAP.pm.

This module connects to your IMAP server and then tries to stay connected as long as POPFile is running. At regular (adjustable) intervals, it will check your IMAP server for new messages. New messages are classified and then moved to other folders on the server based on the bucket the messages were assigned to.

IMAP.pm not only checks for new incoming mail, it also scans its output folders for mail that you moved there. For example, if you have created IMAP folders “spam” and “ham”, corresponding to your spam and ham buckets, POPFile will look into the ham folder for mail it incorrectly classified as spam and vice versa.

To summarize:

  • IMAP.pm will try to classify new messages and move them accordingly
  • and it will also try to reclassify erroneously classified messages without you using the POPFile UI.

What IMAP.pm (currently?) can not do

  • It cannot talk to multiple IMAP servers.
  • It will not modify the subject (according to classification) or add any of the X-POPFile-Link or X-Text-Classification headers to messages.
  • The module will not fork itself or the rest of POPFile. Thus you will not be able to access the POPFile UI while the IMAP module is busy checking the server, classifying, or reclassifying messages, etc.

What you need to run IMAP.pm

All you need is a mail client with IMAP capabilities and an IMAP account at your ISP. The rest of the functionality is distributed along with POPFile. If you are using the Windows installer to install POPFile, make sure that you check the IMAP module when you are asked what optional parts of POPFile should be installed.

How to get it running

IMAP.pm is disabled by default. To enable it,

  • start POPFile,
  • go to the Advanced Tab in the POPFile UI,
  • search for the variable IMAP_enabled in the right table and set it to 1.
  • Click the “Update” button at the bottom of the page,
  • shut-down POPFile,
  • and start it again.
You do not have to make any changes to your mail client configuration to work with POPFile's IMAP module.

Configuring IMAP.pm

To configure the module, go to the Configuration tab in the POPFile UI. Before you do that, however, you might want to use your mail client to create folders on your IMAP server that will receive the classified messages. For example, you might want to create a folder named “spam”, a folder named “work”, and a folder named “personal”, depending on the buckets you have setup. Folder names and bucket names do not have to be identical, though. Don't forget to create a folder in which mails can be moved that POPFile was not able to classify, e.g. create a folder named “unclassified”.

First, enter the connection details for your IMAP server, i.e. the server's hostname or IP address, the port on which the server listens for incoming connections (default: 143), your user name (login), your password and the information whether to connect using SSL or not. If you want to connect via SSL, don't forget to change the port (IMAP servers usually listen on port 993 for SSL connections). When you're done, click the “Apply” button.

In the next configuration step, you need to tell the module about the IMAP folder that receives incoming messages (usually the INBOX folder), and the output folders where the classified messages should go. You need to use your mail client to create new folders on the server that correspond to your buckets. Click the “Refresh list of folders” button, and the module will try to connect to your IMAP server and retrieve a list of folders.

Now select a watched folder (default: INBOX) and click the “Apply” button below the drop-down menu. You can add another watched folder by clicking the corresponding “Add” button (but usually there is not need to do that). You can remove a watched folder, by simply pointing it's drop-down to a folder that you have already selected in another watched folder's drop-down. To put it differently, duplicated watched folders will be removed.

For each of your buckets, the UI should show a drop-down menu that lets you select an output IMAP server for that bucket. You can redirect the output of one bucket back to your INBOX, so that ham messages will simply stay there, while spam messages get moved to another folder, e.g. Click “Apply” to save the selected folders.

Options

? Expunge deleted messages ! Check this box if you want IMAP.pm to issue an EXPUNGE command to the IMAP server after it has moved messages out of a folder. Beware – this will also EXPUNGE messages that you have marked for deletion within your client, but the setting is needed for some IMAP clients that will otherwise simply show you the deleted, but not yet expunged, messages. ? Update interval ! Enter the number of seconds between status updates. How often should IMAP.pm check your mailbox? Five minutes is a good place to start. Enter '300' (without the quotes) in the box and click 'Apply'. Enter '600' or '900' or more if you don't need POPFile to check for new messages that often.

Clicking on “Apply” will save the options and they will be in effect immediately.

Reporting bugs

If you find any bugs (or have any questions), go to the Bleeding Edge - Source code forum, look for the latest thread about IMAP (or start a new one) and provide as many details as you can. However, this is not to say that you should post megabytes worth of log files.

We have started a wiki page about different IMAP-capable mail clients and how they cooperate with the POPFile IMAP module. Information about additional/missing clients is highly appreciated.

If you would like to know about the proposed future of the POPFile IMAP module, checkout the IMAP roadmap page.

 
experimentalmodules/imapinstructions.txt · Last modified: 2016/10/02 14:03 by 127.0.0.1

Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License