IMAP is the Internet Message Access Protocol (defined in RFC3501). It is a protocol that provides access to a collection of mail folders over the internet.
It is particularly useful when accessing your email from a remote location as your mail client can download messages, allow you to work with them locally (without the delays common with remote access) and then upload any changes back to the central location.
At CSE, IMAP can be used to gain access to your home directory, and any mail that is stored therein. IMAP has a concept of a primary mail box which it calls INBOX. This primary mail box is mapped to .incoming-mail in your home directory. Whenever the IMAP server tries to access this mail box, it first (conditionally) collects any new mail that has arrived in the postoffice. Thus newly arrived mail should be available promptly.
The conditions associated with collection mail are the same as apply to normal login. i.e. if you have a file called .noautomail in your home directory, then automatic mail collection is completely disabled. If you have a file called .procmailrc, then each mail item collected will be passed to procmail. If neither of these exist, then mail is automatically appended to your .incoming-mail file.
To use IMAP, you must configure your mail client to connect to the IMAP server at imap.cse.unsw.edu.au. Different email clients vary widely in how you specify this so you should consult the documentation for your client. Details for some common mail clients are given below.
Client Configuration
Some client configuration examples are:
mutt
Mutt uses a mailbox name that looks like a URL with a protocol of imaps. So imaps://joeusers@imap.cse.unsw.edu.au/ would be a suitable mailbox name for joeuser. This URL specifies the INBOX mailbox. Adding a filename to the end can specify other mail boxes to access.
pine
Pine uses a hostname in braces before a mailbox name to specify the host name. At its most basic, using {imap.cse.unsw.edu.au}INBOX in your .pinerc file will use the INBOX mail folder on the School's IMAP server. Pine will prompt for a username and password.
To use IMAP to access other folders in your directory, add a line like folder-collections=Main {imap.cse.unsw.edu.au}[] to your .pinerc.
elm
Elm uses a mail box name that looks like a mail address, so something like joeuser@imap.cse.unsw.edu.au would work, except that elm does not appear to support SSL, and so the IMAP server will not accept the connection.
Thunderbird
Go to the "Edit" menu and select "Account Settings...". For "Server Settings" enable "Use secure connection (SSL)" (but NOT "Use secure authentication" - SSL protects the authentication as well). Also click on the Advanced button and make sure the check box for "Server supports folders that contain sub-folders and messages" is not on. The dialog box should look a little like this:
The "Outgoing Server" settings should look like this:
Outlook Express
You will probably use the Wizard to create the initial IMAP connection settings. Outlook will do this when you first run it or you can go to the "Tools" menu and select "Accounts..." then click on "Add".
Once these initial settings are configured you need to modify them. Go to the "Tools" menu and select "Accounts...". Select the CSE IMAP connection and then the "Properties" button. The relevant dialog box tabs should look a little like this:
Outlook Express does not automatically show subfolders. To do this you need to go open the "IMAP folders" dialog box on the "Tools..." menu and click "Show" for the folders you want to see.
Macintosh OS-X Mail Reader
These images give an example of how to configure the OS-X mail reader to use IMAP. This configuration causes the IMAP server to only look at mail folders in the "imap" directory.
Per-User Server Configuration (customising your mailbox type and location)
It is possible to configure your mailbox on the server. You can even merge together several mailboxes to appear under your main one.
These settings are done in your ~/.imaprc file. Note that this file overrides the default location, so you will need to include the default one in the file if you wish to use that also. NOTE: You will need to restart your mail client to reload this configuration.
The format of the .imaprc file is:
path = /path/to/mailbox
type = mailboxtype
inbox = /path/to/inbox
[Name]
path = /path/to/mailbox2
type = mailboxtype
shared = yes|no
...
The mailboxtype can be either mbox or maildir. It defaults to mbox if not specified.
The /path/to/mailbox is simply the path to the mail folder. You should use ~ to refer to your home directory. You must have write access to this directory!
The inbox entry can only (optionally) be specified in the top level. If it is not specified, then it defaults to ~/.incoming-mail for the mbox format.
The [Name] entry defines a special sub-path which is found in a separate location. You can specify multiple sections, but they must have a unique name. You can also use / to make fake hierarchies.
The shared entry says whether a mailbox is shared. If it is shared, then there MUST be a file in that directory called dovecot-shared. The imap server duplicates the permissions on this "shared" file on any other files that it creates.
NOTE: Don't forget that even after adding new mailbox locations, you will still need to subscribe to the mailboxes in your client.
Examples
Here are some sample configurations
Default
The default configuration can be replicated like this:
path = ~/mail
inbox = ~/.incoming-mail
Basic Maildir
This setup will also be the default if you have a folder called Maildir in your home directory.
path = ~/Maildir
type = maildir
Group mailbox
This is an example of reading a group mailbox in addition to your standard one, and a second group in maildir format:
path = ~/mail
inbox = ~/.incoming-mail
# you must be able to write to /home/mygroup/mail/, which has a dovecot-shared file with correct perms
[MyGroup]
path = /home/mygroup/mail
shared = yes
# and also able to write to /home/group2/Maildir/, with dovecot-shared file.
[MyOtherGroup]
path = /home/group2/Maildir
type = maildir
shared = yes
The "Outgoing Server" settings should look like this:
Outlook Express does not automatically show subfolders. To do this you need to go open the "IMAP folders" dialog box on the "Tools..." menu and click "Show" for the folders you want to see.
