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.
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.
Note that you can specify per mailet and per matcher specific error handling logic.
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.
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.
More on configuration of the SpoolManager can be found here.
Much of the power of James lies in the SpoolManager component. Custom matchers and custom 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.
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.
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.
The Javadoc for the Mailet API can be found here.
James bundles a number of Matchers and Mailets in its distribution. You can retrieve the full list of mailets and matchers packaged in James here
You can read more on mailets on following web sites: