jwma version2

preamble

As with older versions, it provides access to an imap email store. Multiple users can authenticate, read, send and manipulate email and store a list of contacts and email identities. Currently, the assumption is that it will be running locally on the same machine as the mail exchanger. It would be simple to extend it's use to allow interaction with non-local servers (see to do).

The system administrator configures basic options by editing a simple config file. Here are set protocol (imap or imaps), ports and the default language that's offered to users. Individual users can separately choose the language of the interface and select from a few other options.

Jwma depends on a java webapp server (tested with tomcat7), imap server (tested with dovecot) and smtp server (tested with exim4). It was developed on a Gnu/Debian/Linux machine, but it should run on Windows with no more than minimal changes, although we did not yet find a suitable imap server to authenticate against. In addition to the stripes framework, jquery is used for javascript and javamail for interaction with the mail exchanger.

Getting Started

This assumes a machine running a supported imap server (only dovecot so far!), a smtp server and java webapp server. Download from sourceforge and copy the webmail.war file into the appropriate place for your webapp server (webapps for tomcat) and it will start up and load the login page.



If you have an account on the imap server and it's offering an imap service on port 143, you will be able to login and access your email. If you tick the Remember box a cookie is written to your browser. Depending on the browser's configuration, the Username field may be pre-filled next time you access the page.

System Administration

The first time it starts the .jwma (jwma on Windows) directory is written and a default config file jwma.config. The location of this directory will likely be in the base of the webapp server installation, but it's logs should have an indication where this is. If you make changes to the config file, you need to reload the webmail app or restart the app server, to have the changes picked up.

No per user configuration is necessary, jwma passes login details through to the imap server and an account is automatically created for each user the first time they log in. Preferences and contacts for each user are stored in separate files (one or probably two for each user), inside the .jwma/data directory

Main Page

This is where you land after a successful login and where you can quickly return to from the left most link on the navigation bar.



From top working down, you see that the INBOX has 5 messages, all of which have already been read. The already mentioned navigation bar takes you to the other parts of the app as well as returning you here. Next the pre-exisiting folders and mailboxes are displayed. Folders, which can contain mailboxes are shown on the left and Mailboxes which contain messages on the right. Below here are options to delete selected folders or mailboxes, move mailboxes from their logical position inside the INBOX to another folder and create new folders or mailboxes. Finally the icon at bottom right shows that the Trash folder is not empty.

In this state (not empty), the icon is a link that will take you to a list of messages in the Trash folder. The INBOX icon is also a link as are the folders and mailboxes in their respective lists. Be aware that deleting mailboxes and folders removes all messages and sub folders; unlike deleting a message, which actually moves it to the trash folder (see Message lists), there is no warning or second chance.

User Configuration

Select Settings in the navigation bar and you'll be taken to this screen, which initially displays the default settings for each user.



You'll want to replace the Mail identity with one or more of your own email addresses. Note that you cannot delete the default until at least one alternative is in place. This is because it's not possible to send email without this setting.

If you select a different language all the screens (except the login page) will be translated accordingly. Note that by default Trash messages are automatically deleted when you logout; if you stick with this, although deleting messages from other mailboxes actually moves them to Trash, on logging out, they really will be gone.

By default, sent mail is not archived to an Outbox and there is no Draft folder for saving messages (even if there is a mailbox of that name); you'll probably want to select mailboxes for these roles, possibly creating them first back in the app's main view. You must press the Update button to make changes stick

Message lists

Here's an mailbox with 2 messages; looking directly below the navigation bar, you see this is the INBOX, but listings of the mail boxes will appear the same.



You can Select all messages for a mass Delete or Move to; that can also be done on an individual basis by checking boxes on the left as appropriate. Delete is actually a move to Trash except for messages already there, when it really is a delete. Looking at the two individual messages, you see that both have been read R and the second has been answered A. Neither message has an attachment, which would be indicated with *.

Both are sent from the address mail@dmatthews.org, so there's little point (even if there were more messages!) in changing the sorted by setting to list messages by from address. The setting shown is not the default (rather Date oldest first), when this is changed the selection sticks automatically for all mailboxes and is remembered even if you logout.

Search allows you to create a list of messages from the current mailbox which contains your search term in the body of the message. Clicking on the subject of a message displays it (see Reading messages) and to the right, delivery date and message size are displayed.

Reading messages





Not a very interesting message, although it does show the result of the setting Automatically sign in User Configuration. This is the first #1 message in the INBOX which means it's the oldest message, chosen sort order has no bearing on this. The screen will be the same for messages in all other mailboxes, except in a mailbox you designated to be Draft, when a compose window will be opened with the saved message already in place.

Top and bottom to the far right are widgets for cycling through the messages in the current mail box and presenting this message in a screen suitable for printing. If clicked, the head and shoulders icon, far right from the subject will reveal (or conceal) the message headers.



If you enabled Automatically quote in User Configuration, the Toggle auto-quote is useful for turning this off if you want to reply without reference to the original mail.

More interesting messages are treated as follows; plain text single part messages are displayed as is. Html messages are also displayed as such, except that image sources are rewritten to localhost, so are not loaded from the remote server and displayed. Links to attachments are created to enable them to be downloaded, but no attempt is made to display inline images, although their presence is indicated.

If you tick the With Attachments box, Forward to sends messages on mostly unaltered, leaving the recipients email client to decide how to display them. More on this in the next section.

Sending Messages

Let's state upfront that at the moment jwma sends plain text email only unless you wish to hand code html markup and that it is limited to adding a single attachment. This may change (as an option) in the future (see the to do section).





Save Draft does nothing except display a warning unless you've configured a mailbox to be the Draft folder.

No attempt is made to display forwarded messages before they are sent on; you see that the subject and recipient have been rewritten and a preamble stating that this is a forwarded message. You can edit this preamble before sending, but apart from removing any attachments (unless you ticked the box as described above) the original message is included unaltered.





Contacts





This simply allows you to store a list of contacts with email addresses. Clicking on the email address takes you to the compose window, with the To field pre-entered.

I18n

Version 2 of jwma is a genuinely internationalized app; the system administrator can configure the default language and all users make their own selection which is recorded in their config settings for future access. They do this entirely independently of other users and the default language, although that is always presented in the login screen.

To add another language copy a StripesResources properties file in /webmail/web/WEB-INF/classes to StripesResources_xx.properties (where xx is something suitably representative), translating the right hand side of = on each line of the file. Add the appropriate xx to the languages list in jwma.config and reload or restart the app server. Please submit a copy of your file for inclusion in the next release.

Security

Mostly this is not a jwma issue (famous last words?); authentication is managed by the imap server with jwma merely passing details through to it. When it's running locally, I don't believe that passing these in plain text is an issue. The user name, but not the password is stored in the session object. All stored user input is checked to sanitize any malicious input, although at present without a database backend this is less of an issue than it might be in the future.

However, Jwma writes logs files; with tomcat or another app server that explodes the .war file, these will be in the .jwma (or jwma) folder. If the app server runs from the war file without exploding it, it's not possible for the code to manipulate the log4j.properties file. Bets are off, but try looking in the folder from where the app server runs. If you're responsible for a system with a lot of users, it's worth looking out for WARN and ERROR entries. All login attempts are recorded, together with the source ip address if authentication fails.

If you see something like this

ERROR JwmaExceptionHandler - net.sourceforge.stripes.exception.ActionBeanNotFoundException: Could not locate an ActionBean that is bound to the URL [/Admin.jwma].
I'd recommend having a word with the user in question (there is no Admin.jwma page).

To do

If you'd like to contribute in any way please get in touch; especially if you want to do something major that you would like included in future releases. This list is not necessarily exhaustive, all patches that add or improve functionality or squash bugs will be considered and you'll be credited for your work. Please see the development section for help getting started. David Matthews<mail@dmatthews.org>

Development

You'll need a java development environment, a java webapp server and a locally running mail exchanger, which includes an imap server. The imap server needs to be configured with a username and password and needs to accept authentication from webmail in plain text.

At the moment the program has only been tested with the linux imap server, dovecot. If you are serious about helping and are unable to get a suitable mail exchanger set up on your development machine, I may be able to help with an account on another server.

Here's how to get started in two major development environments.

Netbeans

  1. File/New Project/Java Web/Web Application
  2. name the project to be webmail
  3. choose the server and java version, leave context path unaltered as /webmail
  4. don't select a framework
  5. delete all auto created files and folders from the new webmail directory
  6. replace them with the src and web directories from the source archive and the nbproject directory and build.xml file from the netbeans archive.

Eclipse

  1. import the code into the Eclipse Workspace
  2. add following jar and libraries into Build path the three jar files are included in the source code (web/WEB-INF/lib)

Not implemented

The purpose here is to avoid I need this feature from 0.9x / 1.0x type disappointment. There's some overlap with to do here, but it was not my intention to include every last feature. If it's missing and you want it enough to code it, I'd be interested in including it in a future release even if it was not mentioned in the to do section.

Credits

Not necessarily in order of merit:-

License

Earlier versions of jwma (from 0.9x to 1.x) were covered by a BSD style license, which still applies to those files that the program has retained - for instance the files in the images directory. A copy of this file is included in the license directory in the file LICENSE.

Starting with version 2.0, the java source code files were completely rewritten and these are now covered by the GPL3 license a copy of which is included in the same directory in the file GPL.

The licenses of all bundled software including stripes, javamail and jquery are acknowledged. There is an explanatory note in the file license/README.

Old documentation

The documentation for the orginal versions (99.x to 1.0) is still available here.