For some free, but limited support
JWMA uses the jakarta mail api (the latest angus implementation) to provide access to an imap email store. Multiple users can authenticate, read, and manipulate email storage and persist a list of contacts, email identities and their own individual preferences. Email can be sent and read as either plain text or html. Attachments can be added to outgoing mail and downloaded from incoming. This version fully supports sending email with images (inline and remote as well as attachments) and displaying them if configured to do so.
JWMA has been developed and tested on Devuan and Debian system with dovecot as imap server and exim4 as mail exchanger. Setting up such a server is fully documented here. Both mbox and maildir storage have been used in the testing phase. No distro java based packages are used so the provided information on java, tomcat and jetty is valid for any linux based server. Those links explain how to get JWMA running with both an apache2/tomcat v10 setup, a stand alone jetty v11 container and also for creating a lean java runtime (v21 or v17} from Oracle's jdks. JWMA is now a fully compliant JakartaEE application.
Although I doubt anyone wants to run JWMA on a windows OS it ought to be possible. Athough it's no longer tested, earlier versions of JWMA ran with apache james replacing dovecot and exim4, so on a windows system James with derby database email storage could be used. There is some very out of date documentation for setting up james which may still be helpful.
For the server administrator
If upgrading from a version of JWMA before 4.5, and if serialized storage of user settings and contacts was used, sorry, but all existing files in the JWMA home data directory must be deleted. There's no option to retain contact lists other than to copy them off while the older version is running and re enter them. Derby storage is unaffected.
The server administrator configures basic options by editing a simple config file which jWMA generates on first run; it should allow you to make a start though without any changes. Here are set protocol (imap or imaps), ports, mailbox format (mbox or maildir) 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. By default these user settings are persisted as serialized objects, but the administrator's config file also has options for database storage (postgresql, mysql or embedded derby). It's a very long time since the first two of those were tested, but derby support is built in, solid and fully documented in the source download zip archive.
Installation
This assumes a machine running a suitable imap server, mail exchanger and java webapp container. As noted above, all this is documented elsewhere.
You can download JWMA as a ready to go binary and source code (still supplied in a zip archive in case a windows user wants to try it) from sourceforge, Build files to compile the source code make this a quick (few seconds) and simple process. Simply move a build script from the build_scripts directory up to the base webmail directory. There are three for use either with ant, the linux shell or windows powershell (this has not been tested).
The webmail.war binary (either downloaded or compiled from source) is moved to the appropriate place for your webapp server (note additional step recommended for jetty) and it will start up and load the login page. If you have a system user account on the imap server and it's offering an imap service on port 143, you should be able to login and access your email. I know of one unusual situation where this will not work - see my dovecot writeup for details (the note on fscrypt).
This version of JWMA queries a dovecot install to determine mbox or maildir storage and defaults to maildir if that fails. This can be altered by restarting JWMA after editing the config file if necessary. From this point on you can jump to the user guide section before coming back to look at a few additional tweaks.
Configuring
On first run under either tomcat or jetty, JWMA creates a jwma home directory and a confid file.
############ #jwma.config ############ #access_protocol - the mailbox access, either imap or imaps access_protocol = imap #access port, probably either 143 for imap or 993 for imaps port = 143 #available interface languages languages = de,en,es,fr,it #the login screen language and the default choice for users language = en #users config & contacts persistence - one of serialize, postgres, mysql or derby persistence = serialize #1 - session is kept alive or 0 - it times out after 30mins unless compose message page is open keep_alive = 1 #log level one of ALL < DEBUG < INFO < WARN < ERROR < FATAL < OFF log_level = DEBUG #mailbox format, either mbox or maildir mailbox_format = maildir
If you make changes to the config file, you need to reload the webmail app or restart tomcat/jetty, to have the changes picked up.
- access_protocol - this can be changed to from imap to imaps, if you do this you will need to insert a certificate into the jvm's store; see Security.
- access port - this will probably need to be changed from 143 to 993 if you switch to imaps.
- languages - currently there are five European languages available. You could add to these (see Internationalization) or even remove from the comma separated list if you don't want to support them.
- language - the default language, one of those that appears in languages. This will be used at the login screen, but individual users are able to select a different languages once they are logged in.
- persistence - this must be set to serialize (the default), postgres, mysql or derby.
- keep_alive - if this is set to 1 the session never times out, changing this to 0 allows time out after 30 mins of inactivity on the server, except when the compose message window is open.
- log_level - default setting is DEBUG, you can reduce log verbosity by changing this to a lower setting. This only works where the web server explodes the war file (as does tomcat) and settings below WARN are not recommended.
- mailbox_format - defaults to maildir the underlying system used by imapa server and mail exchanger cannot be determined. mbox is the alterantive. maildir is the correct setting if you're running james with it's embedded derby database. All systems (imap server, smtp server and jwma) must use the same mailbox format.
Data storage
This is an alternative to the default serialization of individual users preference choices and contact lists. I'm only going to deal with the derby option here as I've not tested either postgresql or mysql recently. The source archive retains the notes on using these two databases with JWMA as well as information on seting up a derby database from scratch using it's ij tool.
derby
A suitable embedded derby jar (containing the jbdc driver) is supplied in the zip archive. Refer to tomcat / jetty instruction for where to put this and necessary config changes.On the JWMA side, unzip the prepared jwmaDB file from the database directory in the source archive, ensure ownership of its files are the same as the user that runs tomcat and move it to .jwma/derby/jwmaDB. With persistence = derby configured in .jwma/jwma.config. Remember that JWMA, or the web app container must be restarted for changes to take effect. You will of course have to re-enter any user configuration changes you made and contacts that you already stored.
Internationalization
JWMA is a genuinely internationalized app; the system administrator can configure the default language, but please note that supplied translations from English are almost certainly flawed - see to do. All users can make their own selection which is recorded in their preference settings, see User Configuration. They do this entirely independently of other users and the default language, although this is always presented at 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.
Security
Authentication is managed by the imap server with JWMA merely passing details through to it. Since it's running on the same machine as the imap server, I don't believe that passing these in plain text is an issue. Nevertheless, there are features built into jwma that have security in mind and also configuration changes that can be made with the same objective.
The user name, but not the password, is stored in the session object. Databases are protected from malicious input, by checking and sanitizing user input for storage.
Logs
JWMA writes and rotates logs files which will include evidence of any nefarious activity; all login attempts are recorded, together with the source ip address if authentication fails. Log files are stored in the .jwma (or jwma on Windows) directory.
As with any web-based service on a public network, it is good practise to monitor these logs; I suggest logwitch for help with this. If you're responsible for a system with a lot of users, it's worth looking out for WARN and ERROR entries such as these:-
ERROR JwmaExceptionHandler - net.sourceforge.stripes.exception.ActionBeanNotFoundException: Could not locate an ActionBean that is bound to the URL [/Admin.jwma]. 2016-08-05 18:09:07,215 WARN JwmaAuthenticator - login FAILED for david 2016-08-05 18:09:07,216 WARN LoginAction - FAILED login from 94.2.235.163
You may wish to make use of the ability to set logging levels in the config file; once you are satisfied that jwma is running smoothly, you could reduce log verbosity. I'd suggest not going any lower than the WARN setting.
https and imaps
Presenting the login screen over https avoids the risk of passwords being sniffed. There are a number of ways to set this up, some being dealt with in the tomcat and jetty writeups.
Moving from imap access to imaps is another config change that should be considered from the standpoint of security. The java environment must have knowledge of a certificate supplied by the server, this being described in the java writeup and also specifics for dovecot. Unlike Debian/Devuan, the Fedora distro is imaps ready on install, with the dovecot certificate at /etc/pki/dovecot/certs/dovecot.pem. From the JWMA side:-
#access_protocol - the mailbox access, either imap or imaps access_protocol = imaps #access port, probably either 143 for imap or 993 for imaps port = 993
the Session
The default web.xml file specifies a session length of 30 minutes, but with the standard keep_alive = 1 in jwma.config this is overriden by javascript pokes from client browser to server. A session is created when a user logs in and we rely on a logout for it to be closed.
This situation is probably fine where there are only a few, educated users and it is also a nice feature to have the INBOX update automatically and indeed pretty essential that the session does not time out while a user is writing a lengthy email. If this is unlikely to scale too well on your install, you can change the setting to keep_alive = 0. The session is still kept open if the user is composing a message (despite typing on the client not registering on the server!), but if other screens are left inactive the session will be closed after 30 minutes.
Miscellaneous
file system access
If users find that operations such as deleting messages and creating mailboxes fail silently, without a warning in red coloured text, this is probably due to insufficiently permissive access controls to parts of the system involved in mail handling.
It's important to remember that with a system using mbox mail storage, the users INBOX may actually be a file under /var/mail or /var/spool/mail rather than being located in the home directory. On a recent Debian install deleting messages from the INBOX fails:-
root@raylor # ls -l /var/ /\/\/\/\/\ drwxrwsr-x 2 root mail 4096 Oct 6 06:25 mail \/\/\/\/\/
root@raylor # chmod o+w /var/mail/ root@raylor # ls -l /var/ /\/\/\/\/\ drwxrwsrwx 2 root mail 4096 Oct 6 06:25 mail \/\/\/\/\/
Similar problems with message and folder manipulation outside of the inbox will probably be fixed by attending to permission in the mail or Maildir directory in the user's home directory. Additionally SELinux issues may be encountered, particularly with an mbox system. If you use this (it runs by default on fedora). I suggest initially turning it off with echo 0 > /sys/fs/selinux/enforce, checking everything works and then fixing any issues that arise after turning it back on
Dovecot and exim4 setups are dealt with here.
For the user
Sending mail with images | Contacts | Managing folders and mailboxes | The small screen interface
Log in
On a desktop machine if you browse to the address given you by the administrator, you'll get the login
screen where you can authenticate with your system username and password to 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. The link on the top left is there in case you
arrived here using a small screen device; it will take you to the mobile interface, although hopefully that should have
happened automatically. JWMA makes the assumption that you will mainly use a large screen device to manage your email with the mobile interface there to access the main features whilst you are away from home or office.
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. What you see, to some extent depends on the underlying system used for email storage. First, here's JWMA
running on a mbox system:-
From top working down, you see that the INBOX has 3 messages, one of which has not been read. The already
mentioned navigation bar takes you to the other parts of the app as well as returning you here. Below that, on the black bar
next to the small folder image there is a forward slash (/) character. This is the folder separator for the
particular system that your email is stored on. It's helpful to know this if you want to create nested mailboxes ie mailboxes
hidden from the main view.
Next the pre-exisiting folders and mailboxes are displayed. Folders, which can contain mailboxes are shown on the left and mailboxes which contain individual messages on the right. Although they can't be seen, it's likely that the archive folder contains some nested mailboxes. These would be revealed by clicking the folder name and the layout would remain similar to the one shown, but just listing mailboxes inside the folder rather than those logically directly inside the INBOX. If instead of clicking a folder, you click a mailbox, which includes the INBOX you are taken to a Message list for the particular mailbox.
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 the icon is a link that takes you to a list of deleted messages.
Be aware that deleting a mailboxes moves all its messages to Trash and if you delete a folder all mailboxes nested in it will also be removed. As with deleting an individual message (see Message lists), the Trash mailbox represents a second chance, but if you delete messages from this mailbox, they really are gone. The same applies when you logout, unless you deselect Automatically empty Trash in the Settings menu.If instead the administrator has set up a maildir system, what you see will look more like this:-
There is no Folder as opposed to Mailbox distinction as all folders can contain both messages and other folders nested
within them. In both systems, jwma limits nesting to 2 levels, ie messages are logically stored directly in the INBOX
or either one or two levels beneath it. Note that on this system the folder separator is a period/dot/fullstop (.) and
that when the screen shot was taken although the INBOX and Trash were empty, the sent folder contains a
single message.
Clicking the nested Folders link reveals the whole mail storage layout, not just the Mailboxes nested within a single folder
as in the mbox system.
Finally, since this type of system does not distinguish mailboxes from folders, the Create new button does not need to
offer that choice. It is only in this first main window that there is any visual difference apparent to the jWMA user between the two systems it supports.
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 page.
Message display options:-
- 1. geek - plain text only display including the structure of the message
- 2. plain text - the default, a standard plain text display
- 3. block images - html messages displayed, but style sheets and images blocked
- 4. in line images only - as above, but with in line images displayed
- 5. allow all images - html messages as sender intended less any javascript.
You must press the Update button to make changes stick. Don't forget to do this after changing mail identities. As will be shown in the Reading messages section, there is a quick switch from display option 1 and 2 to view html messages as such for individual messages
Message lists
IMPORTANT! - any problem with deleting messages failing silently (no warning in red text) is probably due to this issue. The same applies to an attempt to create a mailbox or folder failing without warning.
Here's an mailbox with 3 messages; looking directly below the navigation bar you see this is the INBOX, but listings of all 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 three individual messages, you see that two have been read (R) and the second has been answered (A). The third message has an attachment, which is indicated with *.
All are sent from different address, so there's no clarity to be gained in changing the sorted by setting to list messages by from address. The setting shown is not the default (rather Date oldest first), if 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
The appearance of messages depends on the display style chosen in Settings.
This mail (not shown full length) is in the INBOX folder, that being a link which would take you back to its message list. As it's #3 in the folder of three messages it's the most recent, as chosen sort order has no bearing on this. To the right there are widgets for cycling through the messages in a folder and for presenting the message in a screen suitable for printing . Also a head and shoulders icon which will reveal and conceal the email headers. The current message display setting is option 1. geek so there is information about the structure of the message as well as its content.
With that same setting (option 4), here's a different message that has remote images:-
This message has rather more innocent looking remote images, shown here with setting 5. allow all images:-
Sending Messages
As standard JWMA creates and sends messages as plain text.
The rich text link replaces the text area with an embedded html editor to allow the creation of html messages. There's discussion of this option, particularly regarding sending mail with inline, rather than attached images below. Incidentally, JWMA has now settled on a new html editor, it's an even more minimal version of the excellent jQuery extension Minimal Rich Text Editor.
If you use the Browse button to add a file attachment, two further file selectors will appear automatically, giving the option to attach up to three files. If an attachment is an image file many email clients (including jwma if Setting 4 or 5 are used for reading messages) will display the image as well as creating a download link for it.
Save Draft allows you to save a partially complete message into the folder you configured as described in the User configuration section. If you have not done this a warning is displayed. It is not functional if rich text was selected. A work around is to write and save a plain text message; when you reopen it from the draft folder you can copy the content before switching to rich text and paste into the code (</>) dropdown box.
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 if you are forwarding a message with an html part, there's no guarantee the recipient will see this. Reason being that any preamble goes into a plain text part which may not be displayed.
Sending mail with images
You can of course send images without including any html markup by attaching an image file to a plain text message. If sent to a JWMA user, who reads mail with the option 4 style, an attached image file is displayed at the end of the message. So what follows is for a use case where you want an image to appear at a particular point of an email. There are three alternatives (four if you include the method mentioned in the developer sectioon. Some small knowledge of html markup is helpful.
It shoud be born in mind that the sender of an email cannot guarantee the configuration or capabilities of the recipient's email client. Your best effort to place and image in an email may not appear as you would hope when the recipient reads it. In fact some major providers (Hotmail, Outlook ie Microsoft owned domains) do not allow users to view images sent inline. Apart from attachments, there seems to be better support out there for remote images compared to inline images added with Content-ID or simply as base64 encoded data.
linking to a remote image
The Add image button is the third from right; you enter the url (ie https://server/path_to/file) of the image resource here. All content incidentally, be it paragraphs of text, images or links should be enclosed in a div tag. You can use the code view (</>) to check this, but generally if the email to be sent looks ok, it probably meets this requirement.Here's how this email appears went sent to JWMA user with 5. allow all images selected:
And here it is at gmail; the account used here is in the standard configuration. I believe gmail allows some configuration changes, including blocking of images, as does JWMA of course. I believe the same applies at Microsoft owned providers such as Hotmail and Outlook, where accounts with the standard configuration will display the image.
Using Content-ID
This is known to be problematical. JWMA now supports it as does gmail and yahoo, but the Microsoft domains do not. As with remote images, even if the provider or the recipients email client accept images, a configuration change may block them. I've not tested what JWMA produces on any of the various desktop email clients and we probably don't know what our recipient uses! In short, there is no way to guarantee inline images, however supplied, will be displayed when the email is read.
The image is added simply by a drag and drop into JWMA's rich text editing area from your graphical file manager. You could also encode the image using the supplied utility (util folder) and add the base64 code into the code view (</>) window. Behind the scenes a Content-ID tag is generated automtically. Only one image can be added, if you add a second image in this way, the result will not be what you expected.
It's probably best to leave the Don't add Content-ID checkbox unchecked. This only has effect if an email has been created that includes a drag and dropped image. If you do check it (this is the third method), no Content-ID tag will be added, but the email will have a rather different structure and this might, in some circumstances, improve the chance that the recipient will see your image. As an example, I know that protonmail users can create email in a similar way, but further research is needed before I can say how useful this option is. JWMA itself will display email with inline images whether or not they were created with a Content-ID tag
Here'sthe email ready to send:
And here it is at gmail. JWMA would display such an email more or less identically if setting 4. in line images only is in place.
Contacts
This 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. Selecting a checkbox and pressing the Email contacts button has similar effect, but this has the additional function of placing a list of recipients in the To field if more than a single checkbox is selected.
The list can be filtered by surname using the selector, which will initially be labeled * to indicate that the full list of contacts is displayed.
Delete contacts operates on entries whose checkbox has been selected. Create contact does its work when the firstname, lastname and email fields have been completed.
Managing folders and mailboxes
To create a new top level mailbox type a name such as test in the input field adjacent to the drop down list and press the Create new button. As explained in the Main page section above, some of the following is underlying system specific.
On both mbox and maildir systems you can use the mailbox store separator character, shown on the black bar of the Main page to create a nested mailbox or folder. On a mbox based system test/test in the input field, will create both a new folder and a new mailbox within it, or just a new nested mailbox if the folder already exists. You can create an empty folder without creating a mailbox at the same time by selecting Folder from the drop down list. On a maildir system test.test will only work if there is already a folder test.
On both systems that already have test/test or test.test, after pressing Create new with test/another | test.another in the input field, the single test folder will now contain two mailboxes or folders. You must always use the correct file separator of the underlying system or the result will not be what you expect.
Folders and mailboxes are deleted by checking the appropriate box and pressing the Delete button. Care is needed as without warning all mailboxes / folders nested within a folder are removed As described here, all messages within all deleted folders / mailboxes will be moved to Trash.
Mailboxes and maildir folders with all the messages they contain can be moved around the hierarchy by checking the appropriate box, selecting the folder from the drop down list and pressing the Move to button.
The small screen interface
If you access Jwma using your smart phone, you should be automatically directed to an alternative interface, but as a fall back the login screen of each interface allows you to switch manually. Compared to the desktop interface there are optimizations both in layout and in a reduction of the feature set.
These screenshots where taken from a galaxy 2 running cyanogenmod; the mobile interface looks pretty much the same on the iphone.
A successful login takes you directly to the INBOX rather than a folder listing. The mailbox list is accessible in the same way as on the desktop interface (the first left navigation icon) a major difference being that folders and any mailboxes nested within them (mbox system) and nested folders (maildir) are not accessible. Other differences include the absence of a save draft option, no option to create html mail, message lists are displayed in recent first order and message display being set to plain text (option 2).
There is no contradiction between the two interfaces in that their settings do not clash. Any folders, nested mailboxes (mbox) and nested folders (maildir) you created via desktop access remain untouched by small screen access and if you normally read messages using some setting other than plain text, that setting will remain in place for desktop access.
For the developer
- Tidy up the language files. 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 rebuild as above.
- There is a second way to enter images by Content-ID, not recommended because the image is not displayed as the email is written and you have to guess at it's height to avoid gmail displaying text that should be below it correctly. You attach the image as you would a normal attachment, but add a cid:xxxx as the image source, with xxxx matching the filename of the image without its extension. You can add up to three images this way. Giving the patchy support for Content-ID it's doubtful if it is worth much effort to make this method more user friendly.
- There is an non minimized version of the rich text editor in the util folder. Unlike the rest of the user interface the rich text editor tool tips are presently resolutely English only.
- As noted in the installation section, building JWMA from source is quick and simple. I can help anyone who wishes to contribute with getting up to speed with stripes (the web framework) and with IntelliJ IDEA integration
Other stuff
Credits
Not necessarily in order of merit:-- the original jwma team, who produced a stylish webmail app with appropriate functionality
- but excluding David Matthews, who merely tinkered around the edges, although he did go on to do the stripes rewrite
- Afreen Khan, who back in the day did some testing on Windows and Eclipse
- Louis Caudwell for his readiness to help out with anything icon or powershell related
- Rick Grashel who has repeatedly provided helpful advice regarding stripes, java and tomcat versions and for being the current curator of the not_as_well_known_as_deserved stripes framework. He has recently single handedly produced a jakartaEE ready version of this software gem, without which this release of JWMA would not have been possible.
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 and desktop directories. 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, jakarta mail, jQuery, jericho-html, log4j, the jQuery editor extension and Font Awesome which it uses are acknowledged and copies are included in the license folder.
Old documentation
The documentation for the orginal versions (99.x to 1.0) is still available for historical purposes.