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 a Mailet container. It is these mailets and matchers that actually carry out mail processing.
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.
More on matchers and mailets can be found here.
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 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.