References

About James

Download

Apache Software Foundation

MailetContainer

Introduction

James separates the services that deliver mail to James (i.e. SMTP, FetchMail)
from the engine that processes mail after it is received by James. The
SpoolManager component is James' mail processing engine. James' SpoolManager component
is also called the Mailet container. It is these mailets and matchers that actually carry out mail processing.

More on the configuration of the SpoolManager and the Mailet API can be found here.

Matchers and Mailets

Core to the SpoolManager operation are Matchers and Mailets. A Matcher is a
simple object that checks whether a mail message matches a particular condition.
A mailet is another type object that processes an email message in some way. Some
typical tasks appropriate for a mailet would be adding a header, delivering the message
to a local repository, or handling remote delivery. Both the Matcher and Mailet APIs are
public, allowing James users to write their own custom matchers and mailets. James
comes with a large set of pre-built matchers and mailets.

Matchers and mailets are used in pairs. At each stage in processing a message is checked
against a matcher. The matcher will attempt to match the mail message. The match is not simply
a yes or no issue. Instead, the match method returns a collection of matched recipients. If the
this collection of matched recipients is empty, the mailet is not invoked. If the collection of
matched recipients is the entire set of original recipients, the mail is then processed by the
associated mailet. Finally, if the matcher only matches a proper subset of the original recipients,
the original mail is duplicated. The recipients for one message are set to the matched recipients,
and that message is processed by the mailet. The recipients for the other mail are set to the
non-matching recipients, and that message is not processed by the mailet.

Processors

One level up from the matchers and mailets are the processors. Each processor
is a list of matcher/mailet pairs. During mail processing, mail messages will be
processed by each pair, in order. In most cases, the message will be processed by
all the pairs in the processor. However, it is possible for a mailet to change the
state of the mail message so it is immediately directed to another processor, and no
additional processing occurs in the current processor. Typically this occurs when the mailet
wants to prevent future processing of this message (i.e. the mail message has been delivered locally,
and hence requires no further processing) or when the mail message has been identified
as a candidate for special processing (i.e. the message is spam and thus should be
routed to the spam processor). Because of this redirection, the processors in the
SpoolManager form a tree. The root processor, which must be present, is the root of
this tree.

SpoolManager

The SpoolManager continually checks for mail in the spool repository. When
mail is first found in the repository, it is delivered to the root processor.
Mail can be placed on this spool from a number of sources (SMTP, FetchPOP, a
custom component). This spool repository is also used for storage of mail that is
being redirected from one processor to another. Mail messages are driven through
the processor tree until they reach the end of a processor or are marked completed
by a mailet.

Much of the power of James lies in the SpoolManager component. Custom matchers and
mailets can be easily developed to address an administrator's particular needs. The
processor tree can easily be configured to sort, filter, and deliver mail based on any
number of criteria. Mail administrators new to James should spend some time learning how
to configure the SpoolManager to meet their needs.

Mailet API

The Mailet API is a simple API used to build mail processing applications. James is a Mailet
container, allowing administrators to deploy Mailets (both custom and pre-made) to carry out a
variety of complex mail processing tasks. In the default configuration James uses Mailets to carry
out a number of tasks that are carried out deep in the source code of other mail servers (i.e. list
processing, remote and local delivery).

As it stands today, the Mailet API defines interfaces for both Matchers and Mailets.

Matchers, as their name would suggest, match mail messages against certain conditions. They
return some subset (possibly the entire set) of the original recipients of the message if there
is a match. An inherent part of the Matcher contract is that a Matcher should not induce any changes
in a message under evaluation.

Mailets are responsible for actually processing the message. They may alter the message in any fashion,
or pass the message to an external API or component. This can include delivering a message to its destination
repository or SMTP server.

The Mailet API is currently in its second revision. Although, the Mailet API is expected to undergo substantial changes in the near future, it is our aim that existing Mailets that abided purely by the prior Mailet API interfaces will continue to run with the revised specification.