| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- Generated by Apache Maven Doxia at 2016-10-20 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Apache James Server 3.0 - |
| Apache James Server 3 - Mailet API</title> |
| <style type="text/css" media="all"> |
| @import url("./css/james.css"); |
| @import url("./css/maven-base.css"); |
| @import url("./css/maven-theme.css"); |
| @import url("./css/site.css"); |
| @import url("./js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css"); |
| @import url("./js/jquery/css/print.css"); |
| @import url("./js/fancybox/jquery.fancybox-1.3.4.css"); |
| </style> |
| <script type="text/javascript" src="./js/jquery/js/jquery-1.4.2.min.js"></script> |
| <script type="text/javascript" src="./js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script> |
| <script type="text/javascript" src="./js/fancybox/jquery.fancybox-1.3.4.js"></script> |
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> |
| <meta name="Date-Revision-yyyymmdd" content="20161020" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| <link title="DOAP" rel="meta" type="application/rdf+xml" href="http://james.apache.org//doap_james-project.rdf"/> |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-1384591-1']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script').item(0); s.parentNode.insertBefore(ga, s); |
| })(); |
| |
| </script> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="../index.html" id="bannerLeft" title="james-logo.png"> |
| |
| |
| <img src="images/logos/james-logo.png" alt="Apache James Server 3.0" /> |
| </a> |
| <a href="http://www.apache.org/index.html" id="bannerRight"> |
| |
| |
| <img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" /> |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| <div class="xleft"> |
| <span id="publishDate">Last Published: 2016-10-20</span> |
| </div> |
| <div class="xright"> <a href="../../index.html" title="Home">Home</a> |
| | |
| <a href="../index.html" title="Server">Server</a> |
| | |
| <a href="../../hupa/index.html" title="Hupa">Hupa</a> |
| | |
| <a href="../../protocols/index.html" title="Protocols">Protocols</a> |
| | |
| <a href="../../mailet/index.html" title="Mailets">Mailets</a> |
| | |
| <a href="../../mailbox/index.html" title="Mailbox">Mailbox</a> |
| | |
| <a href="../../mime4j/index.html" title="Mime4J">Mime4J</a> |
| | |
| <a href="../../jsieve/index.html" title="jSieve">jSieve</a> |
| | |
| <a href="../../jspf/index.html" title="jSPF">jSPF</a> |
| | |
| <a href="../../jdkim/index.html" title="jDKIM">jDKIM</a> |
| | |
| <a href="../../mpt/index.html" title="MPT">MPT</a> |
| | |
| <a href="../../postage/index.html" title="Postage">Postage</a> |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| <h5>Overview</h5> |
| <ul> |
| <li class="none"> |
| <a href="index.html" title="Introduction">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="release-notes.html" title="Release Notes">Release Notes</a> |
| </li> |
| </ul> |
| <h5>Features</h5> |
| <ul> |
| <li class="none"> |
| <strong>Mailet Container</strong> |
| </li> |
| <li class="none"> |
| <a href="feature-queue-priority.html" title="Queue Priority">Queue Priority</a> |
| </li> |
| <li class="none"> |
| <a href="feature-persistence.html" title="Persistence">Persistence</a> |
| </li> |
| <li class="none"> |
| <a href="feature-protocols.html" title="Protocols">Protocols</a> |
| </li> |
| <li class="none"> |
| <a href="feature-smtp-hooks.html" title="SMTP Hooks">SMTP Hooks</a> |
| </li> |
| <li class="none"> |
| <a href="feature-performance.html" title="Performance">Performance</a> |
| </li> |
| <li class="none"> |
| <a href="feature-security.html" title="Security">Security</a> |
| </li> |
| </ul> |
| <h5>User Manual</h5> |
| <ul> |
| <li class="none"> |
| <a href="quick-start.html" title="1. Quick Start">1. Quick Start</a> |
| </li> |
| <li class="none"> |
| <a href="install.html" title="2. Install James">2. Install James</a> |
| </li> |
| <li class="collapsed"> |
| <a href="config.html" title="3. Configure James">3. Configure James</a> |
| </li> |
| <li class="collapsed"> |
| <a href="manage.html" title="4. Manage">4. Manage</a> |
| </li> |
| <li class="collapsed"> |
| <a href="monitor.html" title="5. Monitor">5. Monitor</a> |
| </li> |
| <li class="collapsed"> |
| <a href="upgrade.html" title="6. Upgrade">6. Upgrade</a> |
| </li> |
| </ul> |
| <h5>Developers Corner</h5> |
| <ul> |
| <li class="none"> |
| <a href="dev.html" title="Architecture">Architecture</a> |
| </li> |
| <li class="none"> |
| <a href="dev-build.html" title="Build from source">Build from source</a> |
| </li> |
| <li class="none"> |
| <a href="dev-database-schema.html" title="Database Schema">Database Schema</a> |
| </li> |
| <li class="collapsed"> |
| <a href="dev-extend.html" title="Develop Extensions">Develop Extensions</a> |
| </li> |
| <li class="collapsed"> |
| <a href="dev-provided.html" title="Provided Extensions">Provided Extensions</a> |
| </li> |
| </ul> |
| <h5>References</h5> |
| <ul> |
| <li class="none"> |
| <a href="apidocs/index.html" title="Javadoc">Javadoc</a> |
| </li> |
| <li class="none"> |
| <a href="https://issues.apache.org/jira/browse/JAMES" title="Issue Tracker">Issue Tracker</a> |
| </li> |
| </ul> |
| <h5>About James</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../index.html" title="Overview">Overview</a> |
| </li> |
| <li class="none"> |
| <a href="../../newsarchive.html" title="News">News</a> |
| </li> |
| <li class="none"> |
| <a href="../../mail.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="../../contribute.html" title="Contributing">Contributing</a> |
| </li> |
| <li class="none"> |
| <a href="../../guidelines.html" title="Guidelines">Guidelines</a> |
| </li> |
| <li class="none"> |
| <a href="http://wiki.apache.org/james" title="Wiki">Wiki</a> |
| </li> |
| <li class="none"> |
| <a href="../../team-list.html" title="Who We Are">Who We Are</a> |
| </li> |
| <li class="none"> |
| <a href="../../license.html" title="License">License</a> |
| </li> |
| <li class="none"> |
| <a href="../../thanks.html" title="Thanks">Thanks</a> |
| </li> |
| <li class="none"> |
| <a href="../../support.html" title="Professional support">Professional support</a> |
| </li> |
| </ul> |
| <h5>Download</h5> |
| <ul> |
| <li class="none"> |
| <a href="../../download.cgi" title="Releases">Releases</a> |
| </li> |
| </ul> |
| <h5>Apache Software Foundation</h5> |
| <ul> |
| <li> |
| <strong> |
| <a title="ASF" href="http://www.apache.org/">ASF</a> |
| </strong> |
| </li> |
| <li> |
| <a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html">Get Involved</a> |
| </li> |
| <li> |
| <a title="FAQ" href="http://www.apache.org/foundation/faq.html">FAQ</a> |
| </li> |
| <li> |
| <a title="License" href="http://www.apache.org/licenses/" >License</a> |
| </li> |
| <li> |
| <a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| </li> |
| <li> |
| <a title="Thanks" href="http://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| <li> |
| <a title="Security" href="http://www.apache.org/security/">Security</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /> |
| </a> |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| <!-- Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. --> |
| |
| |
| |
| <div class="section"> |
| <h2>MailetContainer<a name="MailetContainer"></a></h2> |
| |
| |
| <div class="section"> |
| <h3>Introduction<a name="Introduction"></a></h3> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>More on the configuration of the SpoolManager and the Mailet API can be found <a href="config-mailetcontainer.html">here</a>.</p> |
| |
| </div> |
| |
| |
| <div class="section"> |
| <h3>Matchers and Mailets<a name="Matchers_and_Mailets"></a></h3> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>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.</p> |
| |
| </div> |
| |
| |
| <div class="section"> |
| <h3>Processors<a name="Processors"></a></h3> |
| |
| |
| <p>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.</p> |
| |
| </div> |
| |
| |
| <div class="section"> |
| <h3>SpoolManager<a name="SpoolManager"></a></h3> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>More on configuration of the SpoolManager can be found <a href="config-mailetcontainer.html">here</a>.</p> |
| |
| |
| <p>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.</p> |
| |
| </div> |
| |
| |
| <div class="section"> |
| <h3>Mailet API<a name="Mailet_API"></a></h3> |
| |
| |
| <p>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).</p> |
| |
| |
| <p>As it stands today, the Mailet API defines interfaces for both Matchers and Mailets.</p> |
| |
| |
| <ul> |
| |
| <li>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.</li> |
| |
| <li>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.</li> |
| </ul> |
| |
| |
| <p>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.</p> |
| |
| |
| <p>The Javadoc for the Mailet API can be found <a class="externalLink" href="http://james.apache.org/mailet/api/apidocs/">here</a>.</p> |
| |
| |
| <p>James bundles a number of Matchers and Mailets in its distribution. Descriptions of provided matchers |
| can be found <a href="dev-provided-matchers.html">here</a>, while descriptions of provided mailets can be found |
| <a href="dev-provided-mailets.html">here</a>.</p> |
| |
| |
| <p>You can read more on mailets on following web sites:</p> |
| |
| |
| <ul> |
| |
| <li><a class="externalLink" href="http://james.apache.org/mailet/index.html">Mailet Site</a></li> |
| |
| <li><a class="externalLink" href="http://james.apache.org/mailet/api/index.html">Mailet API</a></li> |
| |
| <li><a class="externalLink" href="http://james.apache.org/mailet/base/index.html">Mailet Toolkit</a></li> |
| |
| <li><a class="externalLink" href="http://james.apache.org/mailet/crypto/index.html">Mailet Crypto</a></li> |
| |
| <li><a class="externalLink" href="http://james.apache.org/mailet/standard/index.html">Mailet Sieve</a></li> |
| |
| <li><a class="externalLink" href="http://james.apache.org/mailet/standard/index.html">Mailet Standard</a></li> |
| |
| <li><a class="externalLink" href="http://james.apache.org/mailet/maven-mailetdocs-plugin/index.html">Mailet Docs</a></li> |
| |
| <li><a href="/james-server-mailets-function/mailet-report.html">Server Mailets</a></li> |
| </ul> |
| |
| </div> |
| |
| </div> |
| |
| |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">Copyright © 2002-2016 |
| <a href="http://www.apache.org/">The Apache Software Foundation</a>. |
| All Rights Reserved. |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |