1 - Introduction

    As the world grows ever more interconnected, access to e-mail is becoming more and more of a necessity. Most web mail services respond to this need with an interface that vaguely imitates what most users are accustomed to. Inside Systems responds to this need with Inside Systems Mail, a web mail system that presents a familiar interface and design while taking advantage of current standards to provide a reasonable speed over traditionally slow connections.

    Inside Systems Mail was designed to leave behind version 4 browsers and take advantage of newer standards that allow for a much better webmail experience. Through the heavy use of JavaScript/DOM, it allows the user to interact with their mail and minimize excess downloading/refreshing. Equally at home in both Internet Explorer and Netscape/Mozilla, the dominant browser platforms, Inside Systems Mail can store user settings in any data store of your choosing. It is currently distributed with an encryptable XML class, and a postgresql-backed class, both of which can be extended to handle any additional information you may wish to track.

2 - Requirements



3 - Installation

     The installation Inside Systems Mail is relatively straightforward once you have all of the prerequisites taken care of. Simply unpack the tarball into its own directory, set up up the ismail.conf file for your local installation, and point a URL at it from your webserver. Specifically you should point the URL at login.php but there is an included index.php that should redirect to login.php as well.

4 - Configuration

    The configuration of Inside Systems Mail has changed dramatically between version 1.6 and 1.7. 1.7 Now includes a standardized configuration file that is no longer written in PHP, various types of meta-configuration (imap flavors, domain sorting, etc.), and full support for visual themes. Most installations will only need to copy over the ismail.conf.sample file in the include directory to ismail.conf and edit the settings to fit with their mail setup. More advanced users may wish to try their hand at creating or customizing visual themes with a set of customized graphics and an istheme.conf file (a sample istheme.conf containing all of the possible theme configuration directives file can be found in the include directory).

4.1 - Configuration File

    Once your Inside Systems Mail distribution is unpacked into the directory you have chosen to install it in you need to create an ismail.conf file in your include directory before it will function. The simplest way to do this is to copy the included ismail.conf.sample file over to ismail.conf. However, your ismail.conf file need not contain every directive listed in the sample file. Any directive you do not wish to override from the defaults listed in the sample file can be left out.

    The configuration file itself is broken up into sections. Each section is started with the name of the section followed by a colon on a line by itself - for instance:
default:
example.net
The default section allows you to set defaults that will, unless overridden, apply to every domain your installation provides a web mail portal for. All other sections are assumed to be domain names you are serving mail for and should contain any overrides to parameters listed under default: that apply to that domain. As noted in the sample file itself:
# This file contains various settings that can be altered on a global or # per domain basis to suit your particular installation. The first # section sets global settings that apply (unless overridden) to all # mail domains hosted on your server. You may then have subsequent # domain specific sections that change those defaults on a per-domain # basis. Lines begining with # characters are ignored as comments. # section names must exist on a line by themselves and must end with a # colon. Whitespace at the beginning and the end of lines is ignored. # Any configuration variable that is not set will be given a default # value. All sections other than default are assumed to be additional # hosted domains on your site and must be listed to appear - even if you define # no additional or alternate parameters for them.
    Once you have a configuration file copied over and ready to edit there are several settings you will need to alter/check to get a basic setup working:
    The final thing you must do is list each domain you are providing webmail for as a section. This must be done even if the section for a particular domain contains no overrides to the default configuration. The sections will be read in and provided as a drop-down list on the login page. Obviously you may include configuration directives under each domain section that override the default configuration as needed or desired.

4.2 - Permissions

     There is a users directory which contains all of the attachment/forward files for each specific user. It must be readable/writeable by the webserver user in order for attachments/forward to function properly. Also, when using either of the xml data stores, the users directory is where the addressbook is written.

4.3 - Advanced Configuration

    There are a number of advanced configuration directives available beyond the basic ones need to get a functioning installation. Some of them enable additonal functionality (like spell checking), while others allow you to tweak the way mail is sent or retrieved in a fine-grained fashion. All of the available directives, along with descriptions, are listed in the sample configuration file (although many are commented out by default). Some require the installation of external helper programs, while others require changes to the workings of your imap or smtp server. Make certain you have a detailed understanding of your system and setup before altering the default values or enabling new features.

4.3.1 - IMAP Specific Settings

     Not sure what some of the settings for your IMAP server are? Check the list below and see if it helps you out. Anyone using one of the included falvors probably only needs this information to satisfy curiosity and does not need to set anything explicitely. (And if you are using one that isn't in the list below, can you tell us so we can add it?)

4.4 - Themes

    As of version 1.7 full support for visual themes has been added to Inside Systems Mail. Themes allow you to easily change the look, and to some extent, the layout of Inside Systems Mail. Included with the base install are 3 themes:     The theme configuration file is, to some degree, ever changing as new portions of Inside Systems Mail are themed and the sample configuration file should be considered the authority when it comes to which parameters are available. That said the theme configuration file follows some basic rules.
  1. Each directive must be placed on its own line.
  2. Lines beginning with # and lines consisting only of whitespace are ignored.
  3. Any directive not listed in your theme file will be replaced by a (hopefully) sensible default.
  4. Whitespace in general is ignored.
  5. If it makes sense for a setting to cascade it probably will (for instance, setting link-color without setting addressbook-link-color will cause addressbook-link-color to take on the same value as link-color).
    Themes are stored in directories in the graphics/themes directory. The directory holding the theme determines the name of the theme and that directory must contain every graphic necessary to render Inside Systems Mail as well as a file based on the istheme.conf.sample file in the include directory named istheme.conf that provides additional (non-graphic) theme information. The theme used is set with the themedir directive in ismail.conf in the include directory and may of course differ for different domains.

5 - Usage

     Inside Systems Mail was modeled after common MUA's like Outlook Express, Mozilla Mail, etc. As such, the usage is pretty straightforward once the system itself is installed. There are unfortunately a few differences that are difficult to overcome because of the limitations of a web browser, but as many familiar shortcuts have been added like arrow-key message navigation, delete shortcuts, multiple selections with shift- and ctrl- modifiers, etc.

5.1 - Viewing



5.2 - Moving



5.3 - Sending



5.4 - Deleting

     Like most MUA's, there are several ways to go about deleting e-mail.

5.5 - Settings

     There are a variety of settings that can be saved on a per-user basis to tailor your webmail experience to your personal preferences.

5.6 - Subscription

     One of the features that IMAP presents is folder subscription. This allows some folders to be archived for later use without cluttering the MUA and sharing folders among many people. To that end, Inside Systems Mail incorporates a reasonably simple subscription front-end. By clicking on the 'subscribe' button, you can just subscribe and unsubscribe from folders at will. When a folder is subscribed, the icon will appear open and the folder name will be in bold. When a folder is not subscribed, the icon will appear closed and the folder name will be non-bold italic. When done choosing which folders to be subscribed to, just click on 'Update Subscription' at the bottom of the page and the folder list pane should refresh with your new settings.

6 - Extending Inside System Mail

     Inside Systems Mail is designed to be as extensible as possible. To that end we've created themes, abstract data stores, and easily extensible option settings.

6.1 - Data Stores

     Part of the power of Inside System Mails lies in the flexibility of it's data stores. A template file (include/addressbooktemplate.class) has been provided to help you create your own data store if you want one. There are three main sections of data to the addressbook. There are entries, identities, and settings. The entries are the actual entries of other people in your addressbook, the identities are the various identities through which you send mail, and the settings are settings that tailor the behavior of Inside Systems Mail.

6.2 - Settings

     The setting abstraction allows an easy way for a developer to add new and exciting options to Inside Systems Mail without too much difficulty. By adding a few lines into the include/globals.php file, your settings automatically get rendered into the generalsettings.php dialog, saved to the addressbook, and reloaded on login. The only part that is left is to make the setting actually do something. This may also become a seperate conf file in the future.

7 - Frequently Asked Questions

Here you'll some of the more frequently asked questions regarding Inside Systems Mail.
  1. After logging in, the screen is blank. What's up with that?
  2. I'm getting some function errors when using the addressbook class. Why?
  3. Why are there slashes in front of all of my quotes?
  4. I want to use this with a POP3 server. Can I?
  1. After logging in, the screen is blank. What's up with that? This generally means that you don't have IMAP support compiled into your PHP. Now, don't be fooled by it being a configure arg, that won't do it on it's own. You also have to have the cclient libraries installed.
  2. I'm getting some function errors when using the addressbook class. Why? There are a variety of reasons this could be the happening. We have been told that upgrading to the latest libxml2 package will solve this, that making sure "DOMXML" is compiled in and not just XML will solve it, and the upgrading to a later version of PHP will help. If all of those things are exhausted and it still doesn't work, time for a bug report.
  3. Why are there slashes in front of all of my quotes? There is a security feature in php which will automatically add slashes to quotes when things are submitted to a page. This automation removes control from the programmer, however, so Inside Systems Mail was written with magic_quotes set to off in the php.ini file. If you are getting slashes everywhere, that's probably because it's set to on. In newer PHP versions, it is set to off by default.
  4. I want to use this with a POP3 server. Can I? Of course you can, we won't stop you. There are a few things you should set in order for your POP3 experience to be as nice as possible, however. You'll need to set the port to 110 (or whatever port you wish to use) and the protocol to pop3 to disable IMAP-specific features which don't apply to POP3. Be aware, however, that the only thing you will see is an inbox, since there is no 'local folder' concept in Inside Systems Mail.


8 - ChangeLog