mail2xmppmailet

Introduction
Installation
Configuration
Download
Source


Introduction
-----------------------------------------------------
Mail2XMPPMailet is an Apache James Mailet that enables users to receive an instant message that can contain a configurable amount of information about the email received via an XMPP compatible IM account (ie: Google Talk) using the Smack client library. Possible usage scenarios might include:
  • users who have an email account they don't check very often and would instead like to receive an instant message should they receive an email. To use the Mail2XMPPMailet in this scenario, you would add a mailet entry like this:

    <mailet match="RecipientIs=joe@abc.com" class="Mail2XMPPMailet">
    ...
    </mailet>
  • systems administrators who don't want to configure their email clients to check for email every 30 seconds to see if a system is down. To use the Mail2XMPPMailet in this scenario, ou would add a mailet entry like this:

    <mailet match="SubjectStartsWith=server down" class="Mail2XMPPMailet">
    ...
    </mailet>
  • field service representatives who don't carry a push-email device but who need to have up to date information and may carry a MIDP / J2ME device that can receive XMPP messages. A custom matcher could be written that matches the recipient email address against a database or file that contains all the field service representatives.

    <mailet match="FieldServiceRepMatcher" class="Mail2XMPPMailet">
    ...
    </mailet>
By default messages are transformed by the SimpleSummarizer, which sends the from name, the from email address and the subject. The mailet can be configured to use a different summarizer by specifying the fully qualified name of a class that implements the MailSummarizer interface in the configuration of the mailet by using a summarizer element. If there are errors locating and / or creating an instance of the class specified by summarizer element, the Mail2XMPPMailet will a) write a message to the mailet log file and b) continue to function but will use the SimpleSummarizer. Other probably useful summarizers:
  • MessageFormatSummarizer which could allow an administrator to supply a resource bundle instead of having to use a Java class for formatting
  • FileAttachmentSummarizer which could attempt to read the contents of standard email attachments
  • BodySummarizer which could use (for example) Classifier4J to attempt to summarize the body content of an email.



Installation
-----------------------------------------------------
This document assumes that you have a recent version of Apache James configured and functioning. To install the Mail2XMPPMailet, you must place the following files in your $JAMES\apps\james\SAR-INF\lib\ directory:
  • mail-1.3.1.jar
  • smack.jar
  • smackx.jar



Configuration
-----------------------------------------------------
After dropping the required jar files into the appropriate James directory, you need to tell James where to look for the Mail2XMPPMailet class and then you need to tell James what to do with it. All configuration entries should be made in the following file:

$JAMES\apps\james\SAR-INF\config.xml.

Step 1) Add:

<mailetpackage>net.cephas.james.mailets</mailetpackage>

to the <mailetpackages> element of config.xml.

Step 2) Configure a mailet / matcher combination (see Apache James documentation for more information). For example, here is a Mail2XMPPMailet configured with a standard RecipientIs matcher to match any emails where the recipient is ajohnson@cephas.net

<mailet match="RecipientIs=ajohnson@cephas.net" class="Mail2XMPPMailet">

For a list of all the standard matchers, see the configuration URL for James mentioned below.

Step 3) The Mail2XMPPMailet requires the following mailet configuration entries:

xmppserver: which should be in the form of hostname:port:servicename. Both this entry and the next refer to the XMPP account that forwards the messages. This account most likely should be an account associated with a computer / system and not a person.

xmpplogin: which should be in the form of username:password. For testing purposes only, I created an XMPP account at jabber.org:
* username: mail2xmppmailet * password: password If you use this application in a production environment, please create your own system XMPP account.

recipients: a comma delimited list of recipients, each of which is an equal sign (=) delimited list of email addresses and matching XMPP usernames. For example, to have an XMPP message sent to aaron.s.johnson@gmail.com if an email is received to ajohnson@cephas.net, you'd have:

ajohnson@cephas.net=aaron.s.johnson@gmail.com

Putting steps 2 and 3 together would give you something like this:v
<mailet match="RecipientIs=ajohnson@cephas.net" class="Mail2XMPPMailet">
<xmppserver>jabber.org:5222:jabber.org</xmppserver>
<xmpplogin>mail2xmppmailet:password</xmpplogin>
<recipients>ajohnson@cephas.net=aaron.s.johnson@gmail.com</recipients>
</mailet>

Step 4) The Mail2XMPPMailet can be optionally configured with a summarizer configuration entry. If a different summarizer class is used, the class must exist in either $JAMES\apps\james\SAR-INF\lib\ or in $JAMES\apps\james\SAR-INF\classes. As an example, let's pretend that someone from the Apache POI project created a summarizer that parses and summarizers MS Word documents, you would add the following element to your mailet configuration:

<summarizer>org.apache.poi.mailets.MSWordSummarizer</summarizer>

Putting steps 3 and 4 together, you'd end up with this:

<mailet match="RecipientIs=ajohnson@cephas.net" class="Mail2XMPPMailet">
<xmppserver>jabber.org:5222:jabber.org</xmppserver>
<xmpplogin>mail2xmppmailet:password</xmpplogin>
<recipients>ajohnson@cephas.net=aaron.s.johnson@gmail.com</recipients>
<summarizer>org.apache.james.mailets.MSWordSummarizer</summarizer>
</mailet>



Download
-----------------------------------------------------



Source
-----------------------------------------------------
To build Mail2XMPPMailet from source, you need to have Apache Ant the Java 2 SDK and a Subversion client, which are all available for free here:

Ant: http://ant.apache.org/
Java 2 SDK: http://java.sun.com/downloads/
Subversion: http://subversion.tigris.org/


Once you have downloaded and installed Subversion, you can check out the source code:

svn://svn.cephas.net/mail2xmppmailet/trunk .

Once you have Ant properly installed, you can run a build.