Implementing a custom mailet is generally a simple task, most of whose complexity lies in coding the actual work to be done by the mailet. This is largely due to the simplicity of the Mailet interface and the fact that a GenericMailet class is provided as part of the Mailet package.
In this discussion we will assume that any mailet being implemented is a subclass of GenericMailet. The GenericMailet class serves to abstract away of the configuration and logging details. While it provides a noop implementation of the init() and destroy() methods, these can be easily overridden to provide useful functionality.
In general, the only four methods that you should need to implement are init(), destroy(), getMailetInfo(), and service(Mail). And only the last is required in all cases.
As described in the SpoolManager configuration section, mailets are configured with a set of String (name, value) pairs. These values are passed into the Mailet upon initialization (although the details of this process are hidden by the GenericMailet implementation). GenericMailet provides access to this configuration information through use of the getInitParameter(String) method. Passing in the name of the requested configuration value will yield the value if set, and null otherwise. Configuration values are available inside the init(), destroy(), and service(Mail) methods.
There is a simple logging mechanism provided by the Mailet API. It does not support logging levels, so any log filtering will have to be implemented in the Mailet code. Logging is done by calling one of the two logging methods on GenericMailet - log(String) or log(String,Throwable). Logging is available inside the init(), destroy(), and service(Mail) methods.
Please note that the log() method logs with DEBUG level. You will need to define that DEBUG level in the log4j.properties.
The value of getMailetInfo() for the Mailet is prepended to the log entries for that Mailet. So it may be desirable for you to override this method so you can distinguish mailet log entries by Mailet.
Alternatively, you can instantiate your own logger and log with different level, as show in the following snippet (don't forget to update the log4j.properties so you log are taken into account).
package com.test;
import jakarta.mail.MessagingException;
import org.apache.mailet.Mail;
import org.apache.mailet.base.GenericMailet;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class MyMailet extends GenericMailet{
private static final Logger logger = LoggerFactory.getLogger(MyMailet.class);
@Override
public void service(Mail mail) throws MessagingException {
log("log via mailet logger with INFO level");
logger.info("Log via slf4j with INFO level !!! Add log4j.logger.com.test=INFO, CONS, FILE in the log4j.properties");
logger.debug("Log via slf4j with DEBUG level !!! Add log4j.logger.com.test=DEBUG, CONS, FILE in the log4j.properties");
}
}
As part of the Mailet lifecycle, a Mailet is guaranteed to be initialized immediately after being instantiated. This happens once and only once for each Mailet instance. The Initialization phase is where configuration parsing and per-Mailet resource creation generally take place. Depending on your Mailet, it may or may not be necessary to do any initialization of the mailet. Initialization logic is implemented by overriding the init() method of GenericMailet.
The bulk of the Mailet logic is expected to be invoked from the service(Mail) method. This method is invoked each time a mail message is to be processed by the mailet. The message is passed in as an instance of the Mail interface, which is part of the Mailet API.
The Mail interface is essentially a light wrapper around JavaMail's MimeMessage class with a few important differences. See the Javadoc for the interface for a description of the additional methods available on this wrapper.
As part of the Mailet lifecycle, a Mailet is guaranteed to be destroyed when the container cleans up the Mailet. This happens once and only once for each Mailet instance. The Destruction phase is where per-Mailet resource release generally takes place. Depending on your Mailet, it may or may not be necessary to do any destruction of the mailet. Destruction logic is implemented by overriding the destroy() method of GenericMailet.
Once a Mailet has been successfully implemented there are only a couple of additional steps necessary to actually deploy the Mailet.
The Mailet must be added to James' classpath so that the Mailet can be loaded by James. There are two ways to add a custom Mailet to the classpath so that James will be able to load the Mailet. These are:
1a. Download the source distribution, add a jar file containing the custom files to the lib directory of the unpacked source distribution, and build a new .tar.gz/zip file by following the directions here. This new tar.gz/zip file will now include your custom classes.
or
1b. Place a jar file containing the custom class files in /path/to/james/conf/lib/ subdirectory with JAMES-Spring or /path/to/james/conf/extensions-jars/ subdirectory with JAMES-Guice.
2. The mailetpackages entity is no longer required, the class attribute of mailets and matchers now takes a fully qualified class name e.g.
<mailet match="All" class="com.your.company.MyMailet"/>
Upon injections, the user can reference additional guice modules, that are going to be used only upon extensions instantiation. In order to do that:
1. Place the jar containing the guice module that should be used to instantiate your extensions within the /extensions-jars folder
2. Register your module fully qualified class name within
extensions.properties under the guice.extension.module key.
Configuration of the processor chain is discussed elsewhere in this documentation. The details of configuring mailet deployment is discussed at length. Here we will only comment that it is important to add the appropriate mailet package for your custom mailet to the <mailetpackages> list and that the name of your mailet should not conflict with any of the mailets described here.