
                                    README
                                       
   This is an IMAP server for maildir mailboxes. This IMAP server does
   NOT handle traditional mailbox files, it was written for the exclusive
   purpose of supporting maildir access via IMAP.
   
   Courier-IMAP can provide access to your INBOX. It also implements
   folders. Its folder implementation is compatible with the folder
   implementation in SqWebmail - see http://www.inter7.com/sqwebmail/,
   and maildrop - see http://www.flounder.net/~mrsam/maildrop/.
   Courier-IMAP clients will be able to share folders with SqWebmail.
   Courier-IMAP also supports the maildir voluntary quota extension used
   by both maildrop and sqwebmail. See README.maildirquota.(txt|html)
   elsewhere in this tarball.
   
IMAP client notes

   Configuring IMAP clients can be tricky for any server. You have to
   know a little bit about how the IMAP server works. Recommended
   Courier-IMAP configuration for popular IMAP client software follows.
   
  Pine (version tested: 4.10)
  
   To configure Pine to use Courier-IMAP for the main INBOX, go to Pine's
   main menu, select S)etup, then C)onfigure. Go down to "inbox-path"
   setting, set it as follows:
   
   {hostname}INBOX
   
   "hostname" is the name of the server that's running Courier-IMAP. Exit
   and restart Pine.
   
    Folder configuration
    
   Pine can also create and use folders with Courier-IMAP, instead of
   creating mailbox files in $HOME/mail. Go to Pine's main menu, select
   S)etup, then choose collectionL)ist.
   
   Choose A)ddcollection. Pick a name for this folder collection. Enter
   the hostname of the Courier-IMAP server. For "Path", enter INBOX. Do
   not enter anything for "View". Press ^X to save and exit.
   
   Now, when you select a folder listing from Pine's main menu, instead
   of a folder list, you will see two "folder collections" in a menu. The
   first one will be "Mail - Local folders in mail/". Open that folder
   collection, and you will see your familiar Pine folders (note, you may
   also see INBOX there, that's a bit misleading because your INBOX
   really comes from Courier-IMAP, it's just that Pine always sticks
   INBOX into the first folder collection). The second menu entry will be
   your Courier-IMAP folders. If you open it, you'll see just one folder
   - "Trash". This folder is not really used by Pine, so it can be
   ignored. You can now create your Courier-IMAP folders by pressing A.
   
    Shared folder access
    
   If your Maildir INBOX has been previously linked, by maildirmake, with
   one or more sharable maildirs, you can access shared folders by
   repeating the previous procedure, but entering "shared" into the
   "Path" field, instead of "INBOX" (of course, you'll have to pick
   another name for this shared folder collection).
   
   Unfortunately, Pine lists *ALL* of your sharable folders by default.
   There is, apparently, no individual subscribe/unsubscribe mechanism,
   by which you get to choose which sharable folders you want to be
   listed.
   
   For the FAQ: In a shared folder, "expunge" does not remove some
   deleted messages, why?. ANSWER: You can only delete your own messages
   in a shared folder (owners of sharable maildirs can delete anyone's
   messages, though). You may be able to mark the message as deleted, but
   you won't be able to actually remove it.
   
   Also, when you delete your own messages, others will still see them
   until you expunge.
   
    Creating folders
    
   The names of Courier-IMAP folders may not contain periods or slashes.
   Periods are used as hierarchy delimiters - Courier-IMAP and Pine can
   create folders within other folders.
   
   Choose A)dd folder, then enter "Work.Important". Instead of a new
   folder being created, Pine will display a new entry "Work.". This is a
   subdirectory of folders. Move the cursor and press Enter, and Pine
   will open the contents of "Work", which will contain an empty folder
   "Important". Choose A)dd folder, and create a folder named "Not
   Important". You now have two folders shown, "Important" and "Not
   Important". You can go back to the root folder collection by pressing
   '<'.
   
   When saving messages to folders in Pine, you can manually type in the
   complete folder name, "Work.Not Important", or press Ctrl-T, then
   navigate your folder hierarchy.
   
   You can only delete folders after you've deleted all messages from the
   folder. If you display the folder collection listing, go to the
   "Work." subdirectory and then delete both Important and Not Important
   folders, when you return to the root folder collection, the Work.
   subdirectory will automatically disappear. Subdirectories disappear
   automatically when all folders in the subdirectory are deleted.
   
    Folders containing both messages and subfolders.
    
   It's possible to have both a folder named "Work", and a subdirectory
   named "Work." that contains other folders, however Pine doesn't
   implement it very well. You can go to the folder collections list,
   then add a folder named "Work", then add a folder named "Work.Slacking
   Off".
   
   Pine will display one entry: "Work[.]". Pressing the '>' key will
   display all subfolders in the Work subdirectory, and pressing Enter
   will open the Work folder.
   
   There will be a minor problem navigating the folder collection when
   you're saving messages in Pine. When Pine prompts you for a folder to
   save a message, you can bring up the folder collection list by
   pressing Ctrl-T, however there is no way to select the Work folder
   from the menu. The '>' key will not work, and pressing Enter will
   always display all subfolders in the Work subdirectory. To save the
   message in the Work folder you will have to type in its name manually.
   
    Displaying all folders
    
   If your folder hierarchy has gotten too confusing, and you don't know
   where a particular folder is, you can display all folders at the same
   time. You will have to create a different folder collection for this
   view. Go to Pine's main menu, choose S)etup then collectionL)ist, then
   A)dd CollectionList. Select a name for this collection, enter the name
   of the Courier-IMAP server. Enter the following for the "Path":
   
   #allfolders.INBOX.
   
   The trailing period is required. Leave "View" empty. If you open this
   folder collection, you will now see every folder in your Courier-IMAP
   mailbox.
   
    Removing the local mail folder collection
    
   You may find it cumbersome to have two folder collections in Pine -
   the default folder collection of mailbox files in $HOME/mail and the
   Courier-IMAP folder collection.
   
   From Pine's main menu, choose S)etup then collectionL)ist. You can
   simply delete your local mail folder collections. Pine will now create
   its usual "postponed-msgs" and "sent-mail" folders in Courier-IMAP,
   instead of creating mailbox files in $HOME/mail.
   
   Note - you will lose all your messages saved in local mail folders
   when you do that, so make sure to back up any messages you want by
   copying them into a Courier-IMAP folder. Also, even if you remove the
   local mail folder collection, Pine will not remove $HOME/mail, and it
   will take up space until you manually delete it.
   
   NOTE - if you use SqWebmail, resist the urge to go into Pine setup and
   rename "postponed-msgs" to "Drafts". SqWebmail will have a problem
   with Pine creating and deleting the Drafts folder at will.
   
  Netscape Messenger (version tested: 4.7)
  
   Go to Edit|Preferences. Click on Mail & Newsgroups, choose "Mail
   Servers".
   
   Enter the name of the Courier-IMAP server, for server type choose
   "IMAP", and make sure to enter your login name.
   
   Click on the "Advanced" tab, and UNCHECK the option "Show only
   subscribed folders". Make sure that "server supports folders that
   contain subfolders and messages" is checked.
   
   Under "Personal Namespace", enter "INBOX.", and don't forget the
   trailing period. Under "Public (shared)", enter "shared.". You may not
   actually need to do this, if you use a recent version of Messenger (I
   believe that Messenger 4.5 and later support the NAMESPACE server
   extension which automatically configures these values).
   
   There are several known bugs in Netscape Messenger's IMAP client. See
   BUGS for additional information.
   
   For the FAQ: Clicking on "Get new messages" results in an error
   message "Error in IMAP command received by server", or nothing happens
   at all when I know there are new messages in a shared folder. ANSWER:
   this is a known bug in Messenger's IMAP client. Complain to Netscape.
   You can try reinstalling Courier-IMAP with the
   --enable-workarounds-for-imap-client-bugs option, to see if it helps.
   
  Microsoft Outlook Express (version tested: 4.72)
  
   Open the "Tools" menu, choose "Accounts". This is done for you
   automatically the first time you run Outlook Express. If you already
   use Outlook Express, select this option manually.
   
   Press the "Add" button, select "Mail".
   
   Enter your personal information - name, E-mail address - when
   prompted.
   
   Choose 'IMAP' server type, of course.
   
   Specify the name of the server that's running Courier-IMAP, in the
   "Incoming Mail Server" field.
   
   Specify your usual SMTP server for outgoing mail.
   
   On the next screen, enter your Courier-IMAP logon name and password.
   
   Finish the rest of the set up by giving a name to this mail account.
   Specify your appropriate connection settings.
   
   You will receive the following prompt:
   
     Would you like to download folder list for the IMAP account you've
     just created?
     
   Click on "NO".
   
   You will be returned to the "Internet Accounts" dialog. If you are not
   returned to this screen, choose "Accounts" from the "Tools" menu
   account.
   
   There will be an entry there for the new IMAP server account that you
   just entered. Click on it, then choose "Properties". Click on
   "Advanced".
   
   If you don't need to access any shared folders, enter "INBOX" (without
   the quotes) in the "Root folder path" field, and make sure that "Only
   show subscribed folders" is NOT checked.
   
   If you need to access shared folders, leave the "Root folder path"
   field blank. If you don't have a lot of shared folders, then leaving
   "Only show subscribed folders" also unchecked would probably be
   easier. Otherwise, after you download your folder list "see below",
   shared folders will not immediately show up. You will have to
   right-click on the folder list and select "Subscribe to all folders".
   Then, after all shared folders are downloaded and shown, you can
   right-click and select "unsubscribe" in order to remove any folders
   that you are not interested in.
   
   Save your changes, and go back to the main Outlook Express window. You
   will see a new entry in the left navigation tab for the new IMAP
   server you've just entered.
   
   Click on the new entry. You will be asked again whether or not you
   would like to download the folder list. This time, answer "Yes".
   
   If you did not configure access to shared folders, all your folders on
   the Courier-IMAP server will be shown as a single hierarchy. If you
   enabled access to shared folders, there will be two separate folder
   hierarchies shown: "INBOX" - your private folders, and "shared" - all
   your shared folders.
   
   When shared folder access is enabled, you can only create or delete
   folders by making them subfolders of INBOX. That's your private
   personal folder space. You cannot create any "shared" subfolders,
   because that has to be configured on the server side, either by you
   logging into your shell account, or by the system administrator.
     _________________________________________________________________
   
   Pine is a trademark of the University Of Washington
   
   Netscape Communicator is a trademark of the Netscape Communications
   Corporation
   
   Outlook Express is a trademark of the Microsoft Corporation
     _________________________________________________________________
