| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <html> |
| <head> |
| <title>James Server - |
| James 2.3 - fetchmail Configuration</title> |
| <style type="text/css" media="all"> |
| @import url("./css/maven-base.css"); |
| @import url("./css/maven-theme.css"); |
| @import url("./css/site.css"); |
| </style> |
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" /> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="http://james.apache.org/index.html" id="bannerLeft"> |
| |
| <img src="images/james-server-logo.gif" alt="" /> |
| |
| </a> |
| <a href="http://www.apache.org/index.html" id="bannerRight"> |
| |
| <img src="images/asf-logo-reduced.gif" alt="" /> |
| |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| |
| |
| |
| |
| |
| <div class="xleft"> |
| Last Published: 09/02/2009 |
| </div> |
| <div class="xright"> <a href="../../index.html">JAMES Project</a> |
| | |
| <a href="../../server/index.html">Server</a> |
| | |
| <a href="../../mailet/index.html">Mailets</a> |
| | |
| <a href="../../jspf/index.html">jSPF</a> |
| | |
| <a href="../../mime4j/index.html">Mime4J</a> |
| | |
| <a href="../../jsieve/index.html">JSieve</a> |
| | |
| <a href="../../postage/index.html">Postage</a> |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| |
| |
| |
| |
| |
| <h5>James Server</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="../index.html">Overview</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../design_objectives.html">Objectives</a> |
| </li> |
| |
| |
| |
| |
| |
| <li class="expanded"> |
| <a href="../FAQ.html">James FAQ</a> |
| <ul> |
| |
| <li class="none"> |
| <a href="../james_and_sendmail.html">James and Sendmail</a> |
| </li> |
| </ul> |
| </li> |
| |
| <li class="none"> |
| <a href="http://wiki.apache.org/james">Wiki</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../rfclist.html">Useful RFCs</a> |
| </li> |
| </ul> |
| <h5>Overview</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="index.html">Introduction</a> |
| </li> |
| |
| <li class="none"> |
| <a href="release-notes.html">Release Notes</a> |
| </li> |
| </ul> |
| <h5>Concepts</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="summary.html">Summary</a> |
| </li> |
| |
| <li class="none"> |
| <a href="spoolmanager.html">SpoolManager</a> |
| </li> |
| |
| <li class="none"> |
| <a href="repositories.html">Repositories</a> |
| </li> |
| |
| <li class="none"> |
| <a href="mailet_api.html">The Mailet API</a> |
| </li> |
| </ul> |
| <h5>How to...</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="build_instructions.html">Build James</a> |
| </li> |
| |
| <li class="none"> |
| <a href="installation_instructions.html">Install James</a> |
| </li> |
| </ul> |
| <h5>Configuration</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="dns_configuration.html">DNS Server</a> |
| </li> |
| |
| <li class="none"> |
| <a href="pop3_configuration.html">POP3 Server</a> |
| </li> |
| |
| <li class="none"> |
| <a href="smtp_configuration.html">SMTP Server</a> |
| </li> |
| |
| <li class="none"> |
| <a href="nntp_configuration.html">NNTP Server</a> |
| </li> |
| |
| <li class="none"> |
| <strong>FetchMail</strong> |
| </li> |
| |
| <li class="none"> |
| <a href="remotemanager_configuration.html">RemoteManager</a> |
| </li> |
| |
| <li class="none"> |
| <a href="spoolmanager_configuration.html">SpoolManager</a> |
| </li> |
| |
| <li class="none"> |
| <a href="serverwide_configuration.html">Server-wide</a> |
| </li> |
| |
| <li class="none"> |
| <a href="adding_users.html">Adding Users</a> |
| </li> |
| |
| <li class="none"> |
| <a href="provided_matchers.html">Provided Matchers</a> |
| </li> |
| |
| <li class="none"> |
| <a href="provided_mailets.html">Provided Mailets</a> |
| </li> |
| </ul> |
| <h5>Common Configurations</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="smtp_auth.html">Using SMTP AUTH</a> |
| </li> |
| |
| <li class="none"> |
| <a href="using_database.html">Using a Database with James</a> |
| </li> |
| |
| <li class="none"> |
| <a href="usingTLS.html">Using TLS/SSL</a> |
| </li> |
| |
| <li class="none"> |
| <a href="mailing_lists.html">Creating Mailing Lists</a> |
| </li> |
| </ul> |
| <h5>Customization</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="custom_matcher.html">How to write a custom Matcher</a> |
| </li> |
| |
| <li class="none"> |
| <a href="custom_mailet.html">How to write a custom Mailet</a> |
| </li> |
| </ul> |
| <h5>Project</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="changelog.html">Changelog</a> |
| </li> |
| </ul> |
| <h5>Project Documentation</h5> |
| <ul> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="project-info.html">Project Information</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="collapsed"> |
| <a href="project-reports.html">Project Reports</a> |
| </li> |
| </ul> |
| <h5>Project</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="http://issues.apache.org/jira/browse/JAMES">Bug Database</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://svn.apache.org/viewvc/james/server/">Source Code</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../todo.html">TODO</a> |
| </li> |
| </ul> |
| <h5>Downloads</h5> |
| <ul> |
| |
| <li class="none"> |
| <a href="../../download.cgi">Stable releases</a> |
| </li> |
| |
| <li class="none"> |
| <a href="../../downloadunstable.cgi">Unstable releases</a> |
| </li> |
| |
| <li class="none"> |
| <a href="http://people.apache.org/builds/james/nightly/">Nightly builds</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"> |
| <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img> |
| </a> |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| |
| |
| |
| |
| <a name="fetchmail"></a><div class="section"><h2>fetchmail</h2> |
| <p>fetchmail acts as a gateway between an external message store such as an IMAP |
| or POP3 server and James. Mail is fetched from the external message store and |
| injected into the James input spool.</p> |
| |
| <p>fetchmail is useful when delivery via standard SMTP is not an option, as a |
| means of consolidating mail delivered to several external accounts into a single |
| James account, or to apply the mail processing capabilities of James to mail |
| stored in an external message store.</p> |
| |
| <p>fetchmail has several configuration options that control the fetching and |
| filtering of mail injected into the James input spool. Once there, James' |
| flexible mail processing engine can be used to further process the mail, just as |
| if it had been delivered via standard SMTP.</p> |
| |
| <p> |
| <a href="#How fetchmail Works">How fetchmail Works</a><br></br> |
| <a href="#fetchmail Configuration Parameters">fetchmail Configuration Parameters</a><br></br> |
| <a href="#fetchmail Examples">fetchmail Examples</a><br></br> |
| <a href="#fetchmail Caveats">fetchmail Caveats</a> |
| </p> |
| </div> |
| |
| <a name="How fetchmail Works"></a><div class="section"><h2>How fetchmail Works</h2> |
| <p>Mail is delivered by periodically running fetch tasks that read messages from |
| an external message store and injects them into the James input spool. Fetch |
| tasks run concurrently.</p> |
| |
| <p>A set of filters applies to each fetch task. Each filter provides the ability |
| to reject a message that matches the filter criteria. Rejected messages are not |
| injected into the James input spool; they are either marked as seen or deleted. |
| When a filter is configured to accept a message that matches its criteria, |
| messages are marked with a MailAttribute. This MailAttribute can be detected |
| within the James matcher/mailet chain, allowing further processing as |
| required.</p> |
| |
| <p>Each fetch task is associated with a single host server. Accounts are defined |
| to the fetch task for each mailbox on the server from which mail is to be |
| fetched. Accounts run consecutively.</p> |
| |
| <p>Optionally, the fetch task can be configured with an <alllocal> Account that |
| generates an Account entry for each user defined in the James user repository. |
| This removes the requirement to manually add or remove Account entries to the |
| fetchmail configuration each time a James user is added or removed. Currently |
| this is only useful if the server supports virtual mailboxes that allow the same |
| password to apply to all users within a domain.</p> |
| |
| <p>Accounts can be configured to deliver all mail for an Account to a specified |
| recipient or to deduce the intended recipient from the mail headers.</p> |
| |
| <p>Accounts are normally configured to deliver all mail for an Account to a |
| specified recipient, ignoring the recipient in the mail headers. This works well |
| in the majority of cases where a mailbox is guaranteed to contain mail for a sole |
| mailbox recipient.</p> |
| |
| <p>Accounts are configured to deduce the intended recipient from the mail headers |
| when a mailbox contains mail for several users, typically all users in a domain. |
| Used alone, this is not foolproof as there are circumstances when a single unique |
| recipient cannot be deduced from the mail headers alone. Used in conjunction with |
| an appropriately configured <alllocal> account, it is always possible to deduce |
| the intended recipient when the recipient is a James user.</p> |
| </div> |
| |
| <a name="fetchmail Configuration Parameters"></a><div class="section"><h2>fetchmail Configuration Parameters</h2> |
| <p>The fetchmail configuration parameters are part of the James configuration, |
| whose base file is <code>config.xml</code>. For clarity and flexibility, the |
| fetchmail configuration parameters are stored in the file |
| <code>james-fetchmail.xml</code>, which is referenced within |
| <code>config.xml</code>.</p> |
| |
| <p>The configuration parameters are described below.</p> |
| |
| <a name="fetchmail"></a><div class="section"><h3>fetchmail</h3> |
| <p>The configuration block delimited by the <strong>fetchmail</strong> tag |
| controls fetchmail.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>enabled</strong></dt> |
| <dd>A boolean. If "true", the fetch tasks will be run periodically. If "false", |
| no fetch tasks will be run. The default is "false".</dd> |
| </dl> |
| </p> |
| |
| <p>The tag has these child tags (minimum cardinality, maximum cardinality): |
| <ul> |
| <li><strong><a href="#fetch">fetch</a></strong> (0, *)</li> |
| </ul> |
| |
| |
| <p> |
| <div class="source"><pre> |
| <fetchmail enabled="true"> |
| ... |
| </fetchmail> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="fetch"></a><div class="section"><h3>fetch</h3> |
| <p>The <strong>fetch</strong> tag defines a fetch task to be run |
| periodically. Fetch tasks run concurrently.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>name</strong></dt> |
| <dd>A string uniquely identifying the fetch task.</dd> |
| </dl> |
| </p> |
| |
| <p>The tag has these child tags (minimum cardinality, maximum cardinality): |
| <ul> |
| <li><strong><a href="#accounts">accounts</a></strong> (1, 1)</li> |
| <li><strong><a href="#blacklist">blacklist</a></strong> (1, 1)</li> |
| <li><strong><a href="#defaultdomain">defaultdomain</a></strong> (0, 1)</li> |
| <li><strong><a href="#fetchall">fetchall</a></strong> (1, 1)</li> |
| <li><strong><a href="#fetched">fetched</a></strong> (1, 1)</li> |
| <li><strong><a href="#host">host</a></strong> (1, 1)</li> |
| <li><strong><a href="#interval">interval</a></strong> (1, 1)</li> |
| <li><strong><a href="#javaMailFolderName">javaMailFolderName</a></strong> (1, 1)</li> |
| <li><strong><a href="#javaMailProperties">javaMailProperties</a></strong> (0, 1)</li> |
| <li><strong><a href="#javaMailProviderName">javaMailProviderName</a></strong> (1, 1)</li> |
| <li><strong><a href="#maxmessagesize">maxmessagesize</a></strong> (0, 1)</li> |
| <li><strong><a href="#recipientnotfound">recipientnotfound</a></strong> (1, 1)</li> |
| <li><strong><a href="#recursesubfolders">recursesubfolders</a></strong> (1, 1)</li> |
| <li><strong><a href="#remoteReceivedHeader">remoteReceivedHeader</a></strong> (0, 1)</li> |
| <li><strong><a href="#remoterecipient">remoterecipient</a></strong> (1, 1)</li> |
| <li><strong><a href="#undeliverable">undeliverable</a></strong> (1, 1)</li> |
| <li><strong><a href="#userundefined">userundefined</a></strong> (1, 1)</li> |
| </ul> |
| |
| |
| |
| <div class="source"><pre> |
| <fetch name="mydomain.com"> |
| ... |
| </fetch> |
| </pre></div> |
| |
| </div> |
| |
| <a name="accounts"></a><div class="section"><h3>accounts</h3> |
| The <strong>accounts</strong> tag declares the accounts from which mail will |
| be fetched by the fetch task. Accounts run concurrently. |
| |
| The tag has these child tags (minimum cardinality, maximum cardinality): |
| <ul> |
| <li><strong><a href="#account">account</a></strong> (0, *)</li> |
| <li><strong><a href="#alllocal">alllocal</a></strong> (0, 1)</li> |
| </ul> |
| |
| |
| |
| <div class="source"><pre> |
| <accounts> |
| ... |
| </accounts> |
| </pre></div> |
| |
| </div> |
| |
| <a name="blacklist"></a><div class="section"><h3>blacklist</h3> |
| The <strong>blacklist</strong> tag declares a list of recipient addresses |
| for whom mail will be rejected and what happens to the rejected mail. |
| |
| The tag value is a tab, comma or space delimited list of recipient |
| addresses, eg: <code>wibble@mydomain.com, flobble@mydomain.com</code>. |
| |
| The tag has these attributes: |
| <dl> |
| <dt><strong>reject</strong></dt> |
| <dd>A boolean. If "true", mail for recipients in the blacklist will |
| not be injected into the James input spool. If "false", mail for |
| recipients in the blacklist will be injected into the James input spool with the |
| Mail Attribute <code>org.apache.james.fetchmail.isBlacklistedRecipient</code> |
| added to the mail.</dd> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail for recipients in the blacklist will be |
| left on the server. If "false", mail for recipients in the blacklist |
| will be marked for deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail for recipients in the blacklist will be |
| marked as seen on the server. If "false", mail for recipients in the blacklist |
| will not be marked as seen.</dd> |
| </dl> |
| |
| |
| |
| <div class="source"><pre> |
| <blacklist |
| reject="true" |
| leaveonserver="true" |
| markseen="true"> |
| wibble@mydomain.com, flobble@mydomain.com |
| </blacklist> |
| </pre></div> |
| |
| </div> |
| |
| <a name="defaultdomain"></a><div class="section"><h3>defaultdomain</h3> |
| The <strong>defaultdomain</strong> tag declares the domain name to be |
| appended to the <code>From:</code> header of a mail that has a valid user part |
| but is missing the domain part. |
| |
| If not specified, the default behaviour is to append the canonical host name |
| of the James server. |
| |
| The tag value is the name of the server to append. The name must be a server |
| declared in the <strong>servernames</strong> tag of the <strong>James</strong> |
| block in the configuration or the name <code>localhost</code>. |
| |
| |
| <div class="source"><pre> |
| <defaultdomain> |
| mydomain.com |
| </defaultdomain> |
| </pre></div> |
| |
| </div> |
| |
| <a name="fetchall"></a><div class="section"><h3>fetchall</h3> |
| The <strong>fetchall</strong> tag declares if all mail should be fetched from |
| the server, or just unseen mail. |
| |
| The tag value is a boolean. If true, all mail is fetched. If false, only |
| unseen mail is fetched. |
| |
| |
| <div class="source"><pre> |
| <fetchall>false</fetchall> |
| </pre></div> |
| |
| </div> |
| |
| <a name="fetched"></a><div class="section"><h3>fetched</h3> |
| The <strong>fetched</strong> tag declares what will happen to mail on the |
| external server that is successfully injected into the James input spool. |
| |
| The tag has these attributes: |
| <dl> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail injected into the James input spool |
| will be left on the server. If "false", mail injected into the James |
| input spool will be marked for deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail injected into the James input spool |
| will be marked as seen on the server. If "false", mail injected into |
| the James input spool will not be marked as seen.</dd> |
| </dl> |
| |
| |
| |
| <div class="source"><pre> |
| <fetched leaveonserver="true" markseen="true"/> |
| </pre></div> |
| |
| </div> |
| |
| <a name="host"></a><div class="section"><h3>host</h3> |
| <p>The <strong>host</strong> tag declares the IP address of the external |
| server from which mail is fetched.</p> |
| |
| <p>The tag value is the DNS name or IP address literal of the external |
| server.</p> |
| |
| <p> |
| <div class="source"><pre> |
| <host>pop3.server.com</host> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="interval"></a><div class="section"><h3>interval</h3> |
| <p>The <strong>interval</strong> tag declares the period between invocations of |
| the fetch tasks. If a fetch task is still active from a previous invocation |
| when the period expires, the new invocation is skipped over.</p> |
| |
| <p>The tag value is an integer representing the number of milliseconds to elapse |
| between invocations of the fetch tasks.</p> |
| |
| <p> |
| <div class="source"><pre> |
| <interval>60000</interval> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="javaMailFolderName"></a><div class="section"><h3>javaMailFolderName</h3> |
| <p>The <strong>javaMailFolderName</strong> tag declares the name of the root |
| folder on the external server from which mail is fetched.</p> |
| |
| <p>The tag value is the cAsE-sEnSiTiVe name of the root folder on the external |
| server from which mail is fetched. For POP3 servers this is always |
| <code>INBOX</code>.</p> |
| |
| <p> |
| <div class="source"><pre> |
| <javaMailFolderName>INBOX</javaMailFolderName> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="javaMailProperties"></a><div class="section"><h3>javaMailProperties</h3> |
| <p>The <strong>javaMailProperties</strong> tag declares the properties to be |
| applied to the JavaMail Session used by the fetch task. These override the |
| properties answered by <code>System.getProperties()</code>. Many JavaMail |
| properties are specific to the JavaMail Provider selected by the |
| <a href="#javaMailProviderName">javaMailProviderName</a> tag.</p> |
| |
| <p><strong>Relying on the default values selected by the Provider can be |
| inappropriate.</strong> For instance, the default connection and I/O timeout |
| values of infinite for the default IMAP and POP3 Providers is rarely what is |
| required. Consult the documentation of the Provider for details and options.</p> |
| |
| <p>Documentation for the default Provider for IMAP is located |
| <a href="http://java.sun.com/products/javamail/javadocs/com/sun/mail/imap/package-summary.html"> |
| here</a>.</p> |
| |
| <p>Documentation for the default Provider for POP3 is located |
| <a href="http://java.sun.com/products/javamail/javadocs/com/sun/mail/pop3/package-summary.html"> |
| here</a>.</p> |
| |
| <p>Details of how to change a Provider are located |
| <a href="http://java.sun.com/products/javamail/javadocs/javax/mail/Session.html"> |
| here</a>.</p> |
| |
| <p>The tag has these child tags (minimum cardinality, maximum cardinality): |
| <ul> |
| <li><strong><a href="#property">property</a></strong> (0, *)</li> |
| </ul> |
| |
| |
| <p> |
| <div class="source"><pre> |
| <javaMailProperties> |
| ... |
| </javaMailProperties> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="javaMailProviderName"></a><div class="section"><h3>javaMailProviderName</h3> |
| <p>The <strong>javaMailProviderName</strong> tag selects the JavaMail protocol |
| Provider used to interact with the external server.</p> |
| |
| <p>The tag value is the name of a JavaMail supported protocol, such as |
| <code>pop3</code> or <code>imap</code>. The name is used to select the default |
| Provider for the protocol.</p> |
| |
| <p> |
| <div class="source"><pre> |
| <javaMailProviderName>pop3</javaMailProviderName> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="maxmessagesize"></a><div class="section"><h3>maxmessagesize</h3> |
| <p>The <strong>maxmessagesize</strong> tag declares the maximum permitted message |
| size for messages injected into the James input spool and what happens to fetched |
| messages that exceed this size.</p> |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>limit</strong></dt> |
| <dd>An integer. The maximum message size expressed in Kilobytes. If 0, there is |
| no limit.</dd> |
| <dt><strong>reject</strong></dt> |
| <dd>A boolean. If "true", mail whose message size exceeds the maximum |
| permitted size will not be injected into the James input spool. If |
| "false", mail whose message size exceeds the maximum permitted size will |
| have its contents removed, an explanatory error message and the Mail Attribute |
| <code>org.apache.james.fetchmail.isMaxMessageSizeExceeded</code> added prior to |
| injection into the James input spool, (see below for the location of an example).</dd> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail whose message size exceeds the maximum |
| permitted size will be left on the server. If "false", mail whose message |
| size exceeds the maximum permitted size will be marked for deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail whose message size exceeds the maximum |
| permitted size will be marked as seen on the server. If "false", |
| mail whose message size exceeds the maximum permitted size will not be marked as |
| seen.</dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <maxmessagesize |
| limit="4096" |
| reject="false" |
| leaveonserver="false" |
| markseen="false"/> |
| </pre></div> |
| </p> |
| |
| <p>An example configuration using James mailet processing to bounce fetched |
| messages that exceed the maximum permitted size can be found in the file |
| <code>$PHOENIX_HOME/apps/james/conf/samples/fetchmail/maxMessageSize.xml</code>. |
| </p> |
| </div> |
| |
| <a name="recipientnotfound"></a><div class="section"><h3>recipientnotfound</h3> |
| <p>The <strong>recipientnotfound</strong> tag declares what happens to mail for |
| which a sole intended recipient cannot be found when attempting to determine |
| the recipient from the mail headers.</p> |
| |
| <p>In configurations with more than one account per fetch task, processing of |
| matched mail can be deferred to the next run of the fetch task. This gives |
| other accounts that may be able to determine a sole intended recipient an |
| opportunity to do so before recipientnotfound processing is invoked.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>defer</strong></dt> |
| <dd>A boolean. If "true", mail for which a sole intended recipient |
| cannot be determined is left unprocessed until the next run of the fetch task. |
| If "false", mail for which a sole intended recipient cannot be |
| determined is processed immediately.</dd> |
| <dt><strong>reject</strong></dt> |
| <dd>A boolean. If "true", mail for which a sole intended recipient |
| cannot be determined will not be injected into the James input spool. If |
| "false", mail for which a sole intended recipient cannot be |
| determined will be injected into the James input spool using the recipient |
| attribute of the current account and with the Mail Attribute |
| <code>org.apache.james.fetchmail.isRecipientNotFound</code> added to the |
| mail.</dd> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail for which a sole intended recipient |
| cannot be determined will be left on the server. If "false", mail for |
| which a sole intended recipient cannot be determined will be marked for |
| deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail for which a sole intended recipient |
| cannot be determined will be marked as seen on the server. If "false", |
| mail for which a sole intended recipient cannot be determined will not be marked |
| as seen.</dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <recipientnotfound |
| defer="true" |
| reject="true" |
| leaveonserver="true" |
| markseen="true"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="recursesubfolders"></a><div class="section"><h3>recursesubfolders</h3> |
| <p>The <strong>recursesubfolders</strong> tag declares if mail should be fetched |
| from sub-folders of the root folder, or just the root folder.</p> |
| |
| <p>The tag value is a boolean. If true, mail is fetched from the root folder and |
| its subfolders. If false, mail is fetched from just the root folder.</p> |
| |
| <p> |
| <div class="source"><pre> |
| <recursesubfolders>false</recursesubfolders> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="remoteReceivedHeader"></a><div class="section"><h3>remoteReceivedHeader</h3> |
| <p>The <strong>remoteReceivedHeader</strong> tag declares the zero based |
| index of the RFC2822 compliant RECEIVED header used to determine the address and |
| host name of the remote MTA that sent a fetched message and what happens to |
| messages when the specified header is invalid.</p> |
| |
| <p>Typically, the first (index = 0) RECEIVED header is for the local MTA that |
| delivered the message to the message store and the second (index = 1) RECEIVED |
| header is for the remote MTA that delivered the message to the local MTA. When |
| this configuration applies, the <strong>remoteReceivedHeaderIndex</strong> should |
| be set to <strong>1</strong>. |
| </p> |
| |
| <p>To verify the correct setting, examine the RECEIVED headers for messages |
| delivered to the configured message store and locate the first one containing a |
| remote domain in the'from' field. Remembering that zero based indexing is used, |
| if this the second header, use an index of 1, if this is the third header, use an |
| index of 2, and so forth.</p> |
| |
| <p>Matchers such as InSpammerBlacklist use the remote address and/or remote host |
| name to identify illegitimate remote MTAs. If you do not use such matchers, the |
| <strong>remoteReceivedHeaderIndex</strong> tag may be omitted or the default |
| index value of -1 can be specified. This causes the remote address to be set to |
| <code>127.0.0.1</code> and the remote host name to be set to |
| <code>localhost</code>. Matchers almost always considered these values to be |
| legitimate.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>index</strong></dt> |
| <dd>An integer whose meaning is described above. |
| </dd> |
| <dt><strong>reject</strong></dt> |
| <dd>A boolean. If "true", mail whose specified recieved header is invalid |
| will not be injected into the James input spool. If "false", mail whose |
| specified recieved header is invalid will be injected into the James input spool with |
| the Mail Attribute <code>org.apache.james.fetchmail.isInvalidReceivedHeader</code> |
| added to the mail, the remote address set to <code>127.0.0.1</code> and the remote |
| host name set to <code>localhost</code>. |
| </dd> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail whose specified recieved header is invalid |
| will be left on the server. If "false", mail whose specified recieved header |
| is invalid will be marked for deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail whose specified recieved header is invalid |
| will be marked as seen on the server. If "false", mail whose specified |
| recieved header is invalid will not be marked as seen.</dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <remoteReceivedHeader |
| index="1" |
| reject="true" |
| leaveonserver="true" |
| markseen="true"/> |
| </pre></div> |
| </p> |
| |
| <p>An example configuration using James mailet processing to notify the postmaster |
| of fetched messages that contain an invalid Received header can be found in the file |
| <code>$PHOENIX_HOME/apps/james/conf/samples/fetchmail/remoteReceivedHeader.xml</code>. |
| </p> |
| </div> |
| |
| <a name="remoterecipient"></a><div class="section"><h3>remoterecipient</h3> |
| <p>The <strong>remoterecipient</strong> tag declares what happens to mail for |
| which the domain part of the recipient is remote. A domain is remote if it is |
| not a server declared in the <strong>servernames</strong> tag of the |
| <strong>James</strong> block in the configuration.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>reject</strong></dt> |
| <dd>A boolean. If "true", mail for remote recipients will not be |
| injected into the James input spool. If "false", mail for remote |
| recipients will be injected into the James input spool with the Mail Attribute |
| <code>org.apache.james.fetchmail.isRemoteRecipient</code> added to the mail. |
| </dd> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail for remote recipients will be left on |
| the server. If "false", mail for remote recipients will be marked for |
| deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail for remote recipients will be marked as |
| seen on the server. If "false", mail for remote recipients will not be |
| marked as seen.</dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <remoterecipient |
| reject="true" |
| leaveonserver="true" |
| markseen="true"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="undeliverable"></a><div class="section"><h3>undeliverable</h3> |
| <p>The <strong>undeliverable</strong> tag declares what happens to mail that |
| cannot be delivered.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail that cannot be delivered will be left |
| on the server. If "false", mail that cannot be delivered will be |
| marked for deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail for that cannot be delivered will be |
| marked as seen on the server. If "false", mail that cannot be |
| delivered will not be marked as seen.</dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <undeliverable |
| leaveonserver="true" |
| markseen="true"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="userundefined"></a><div class="section"><h3>userundefined</h3> |
| <p>The <strong>userundefined</strong> tag declares what happens to mail for |
| which the recipient is not defined as a James user.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>reject</strong></dt> |
| <dd>A boolean. If "true", mail for recipients who are not defined as |
| James users will not be injected into the James input spool. If |
| "false", mail for recipients who are not defined as James users will |
| be injected into the James input spool with the Mail Attribute |
| <code>org.apache.james.fetchmail.isUserUndefined</code> added to the mail. |
| </dd> |
| <dt><strong>leaveonserver</strong></dt> |
| <dd>A boolean. If "true", mail for recipients who are not defined as |
| James users will be left on the server. If "false", mail for |
| recipients who are not defined as James users will be marked for deletion.</dd> |
| <dt><strong>markseen</strong></dt> |
| <dd>A boolean. If "true", mail for recipients who are not defined as |
| James users will be marked as seen on the server. If "false", mail |
| for recipients who are not defined as James users will not be marked as seen. |
| </dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <userundefined |
| reject="true" |
| leaveonserver="true" |
| markseen="true"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="account"></a><div class="section"><h3>account</h3> |
| <p>The <strong>account</strong> tag declares an account on the external server |
| from which mail should be fetched.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>user</strong></dt> |
| <dd>The string to be passed as the user when connecting to the external server. |
| </dd> |
| <dt><strong>password</strong></dt> |
| <dd>The string to be passed as the password when connecting to the external |
| server.</dd> |
| <dt><strong>recipient</strong></dt> |
| <dd>The recipient to whom messages will be delivered when the intended recipient |
| cannot be determined or when the intended recipient is to be ignored.</dd> |
| <dt><strong>ignorercpt-header</strong></dt> |
| <dd>A boolean. If "true", mail is always delivered to the recipient |
| declared in the <strong>recipient</strong> attribute above. If |
| "false", the intended recipient is determined from the mail headers or |
| the process declared by the <strong>recipientnotfound</strong> tag. |
| </dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <account |
| user="myaccount" |
| password="mypassword" |
| recipient="user@localhost" |
| ignorercpt-header="true"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="alllocal"></a><div class="section"><h3>alllocal</h3> |
| <p>The <strong>alllocal</strong> tag declares the parameters to be applied to |
| dynamic accounts. The set of dynamic accounts is refreshed each time the fetch |
| task runs by combining the <strong>alllocal</strong> tag attributes with each of |
| the currently defined James users to create an account for every James user.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>userprefix</strong></dt> |
| <dd>The string to be added before the James user when constructing the string |
| passed as the user when connecting to the external server. |
| </dd> |
| <dt><strong>usersuffix</strong></dt> |
| <dd>The string to be added after the James user when constructing the string |
| passed as the user when connecting to the external server. |
| </dd> |
| <dt><strong>password</strong></dt> |
| <dd>The string to be passed as the password when connecting to the external |
| server.</dd> |
| <dt><strong>recipientprefix</strong></dt> |
| <dd>The string to be added before the James user when constructing the recipient |
| to whom messages will be delivered when the intended recipient cannot be |
| determined or when the intended recipient is to be ignored.</dd> |
| <dt><strong>recipientsuffix</strong></dt> |
| <dd>The string to be added after the James user when constructing the recipient |
| to whom messages will be delivered when the intended recipient cannot be |
| determined or when the intended recipient is to be ignored.</dd> |
| <dt><strong>ignorercpt-header</strong></dt> |
| <dd>A boolean. If "true", mail is always delivered to the recipient |
| constructed from the <strong>recipientprefix</strong> and |
| <strong>recipientsuffix</strong> attributes above and the James user. If |
| "false", the intended recipient is determined from the mail headers or |
| the process declared by the <strong>recipientnotfound</strong> tag. |
| </dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <alllocal |
| userprefix="" |
| usersuffix="@external.domain.com" |
| password="mypassword" |
| recipientprefix="" |
| recipientsuffix="@mydomain.com" |
| ignorercpt-header="true"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="property"></a><div class="section"><h3>property</h3> |
| <p>The <strong>property</strong> tag declares a name/value pair.</p> |
| |
| <p>The tag has these attributes: |
| <dl> |
| <dt><strong>name</strong></dt> |
| <dd>The name of the property. |
| </dd> |
| <dt><strong>value</strong></dt> |
| <dd>The value of the property.</dd> |
| </dl> |
| </p> |
| |
| <p> |
| <div class="source"><pre> |
| <property |
| name="mail.pop3.connectiontimeout" |
| value="180000"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| </div> |
| |
| <a name="fetchmail Examples"></a><div class="section"><h2>fetchmail Examples</h2> |
| <p>Full sources to the examples discussed below can be found in the directory |
| <code>$PHOENIX_HOME/apps/james/conf/samples/fetchmail</code>.</p> |
| |
| <a name="One Account, One User"></a><div class="section"><h3>One Account, One User</h3> |
| <p>When all mail for an account is to be delivered to a single user, |
| configure each account to ignore the recipient in the mail headers and deliver |
| to the specified recipient. The <strong>accounts</strong> block looks like |
| this:</p> |
| |
| <p> |
| <div class="source"><pre> |
| <accounts> |
| <account |
| user="user1@external.domain.com" |
| password="password1" |
| recipient="user1@localhost" |
| ignorercpt-header="true"/> |
| |
| <account |
| user="user2@external.domain.com" |
| password="password2" |
| recipient="user2@localhost" |
| ignorercpt-header="true"/> |
| |
| <account |
| user="user3@external.domain.com" |
| password="password3" |
| recipient="user3@localhost" |
| ignorercpt-header="true"/> |
| </accounts> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="One Account, Many Users"></a><div class="section"><h3>One Account, Many Users</h3> |
| <p>When an account contains mail to be delivered to many users, configure each |
| account to determine the recipient from the mail headers and deliver to that |
| user. The <strong>accounts</strong> block looks like this:</p> |
| |
| <p> |
| <div class="source"><pre> |
| <accounts> |
| <account |
| user="global@external.domain.com" |
| password="password" |
| recipient="fetchmail@localhost" |
| ignorercpt-header="false"/> |
| </accounts> |
| </pre></div> |
| </p> |
| |
| <p>The <strong>recipientnotfound</strong> tag is used to declare what happens |
| when the recipient cannot be determined from the mail headers. In the example |
| below, mail is injected into the spool using the recipient declared in the |
| <strong>account</strong> tag:</p> |
| |
| <p> |
| <div class="source"><pre> |
| <recipientnotfound |
| defer="false" |
| reject="false" |
| leaveonserver="false" |
| markseen="false"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="One Account, One User - Dynamic"></a><div class="section"><h3>One Account, One User - Dynamic</h3> |
| <p>When an external server supports virtual mailboxes, fetchmail's dynamic |
| account facility can be used. This greatly simplifies user configuration as |
| the fetchmail accounts for users are automatically synchronized with those |
| defined in the James user repository. This guarantees that mail for all local |
| users will be fetched and delivered.</p> |
| |
| <p>Currently, there is a limitation that all virtual accounts and the global |
| account must share the same password.</p> |
| |
| <p>The <strong>alllocal</strong> tag declares the parameters for the dynamic |
| accounts. The <strong>accounts</strong> block below will deliver mail for |
| <code>user1@external.domain.com</code> to <code>user1@localhost</code>, |
| <code>user2@external.domain.com</code> to <code>user2@localhost</code>, |
| <code>userZ@external.domain.com</code> to <code>userZ@localhost</code> etc.:</p> |
| |
| <p> |
| <div class="source"><pre> |
| <accounts> |
| <alllocal |
| userprefix="" |
| usersuffix="@external.domain.com" |
| password="mypassword" |
| recipientprefix="" |
| recipientsuffix="@localhost" |
| ignorercpt-header="true"/> |
| </accounts> |
| </pre></div> |
| </p> |
| </div> |
| |
| <a name="One Account, Many Users - Dynamic"></a><div class="section"><h3>One Account, Many Users - Dynamic</h3> |
| <p>The |
| <a href="#One Account, One User - Dynamic">One Account, One User - Dynamic</a> |
| example guarantees delivery of mail for all local users, but leaves other mail |
| on the external server unprocessed. The |
| <a href="#One Account, Many Users">One Account, Many Users</a> example |
| processes all mail on the external server, but cannot guarantee delivery to the |
| intended recipient. By combining the two, it is possible to guarantee the |
| delivery of mail for all local users and process all mail.</p> |
| |
| <p>In the snippet below, the <strong>alllocal</strong> tag declares dynamic |
| accounts for all local users and the <strong>account</strong> tag configures an |
| account to fetch all mail.</p> |
| |
| <p>The <strong>recipientnotfound</strong> tag rejects mail for which a recipient |
| cannot be determined. By the time this processing is activated, the dynamic |
| accounts will have processed mail for all local users, so the mail can |
| only be mail for non-local users or newly arrived mail for local users. It is |
| not possible to know which, but we want to leave mail for local users to be |
| dealt with by the dynamic accounts. The next time the dynamic accounts run any |
| newly arrived mail for local users will be processed. The remainder will be for |
| non-local users and can now be safely dealt with.</p> |
| |
| <p>The <code><recipientnotfound defer="true"</code> attribute |
| enables deferal of the processing of messages for which the recipient cannot be |
| determined to the next iteration of the fetch task, and is used here. The |
| relevant tags are:</p> |
| |
| <p> |
| <div class="source"><pre> |
| <accounts> |
| <alllocal |
| userprefix="" |
| usersuffix="@external.domain.com" |
| password="mypassword" |
| recipientprefix="" |
| recipientsuffix="@localhost" |
| ignorercpt-header="true"/> |
| |
| <account |
| user="global@external.domain.com" |
| password="password" |
| recipient="fetchmail@localhost" |
| ignorercpt-header="false"/> |
| </accounts> |
| |
| <recipientnotfound |
| defer="true" |
| reject="true" |
| leaveonserver="true" |
| markseen="true"/> |
| </pre></div> |
| </p> |
| </div> |
| |
| </div> |
| |
| <a name="fetchmail Caveats"></a><div class="section"><h2>fetchmail Caveats</h2> |
| <p>These are some things to be aware of when using fetchmail: |
| <ul> |
| <li>As noted in the |
| <a href="#One Account, One User - Dynamic">One Account, One User - Dynamic</a> |
| example, all virtual accounts and the global account must share the same |
| password. A future version might associate each James user to a set of account |
| credentials. |
| </li> |
| |
| <li>When using dynamic accounts, an account is generated and an attempt made to |
| fetch mail for all James users defined to James even if there is no such mailbox |
| on the server. This is inefficient but not fatal. The solution is the same as |
| described above. |
| </li> |
| |
| <li>When using dynamic accounts, as described in the |
| <a href="#One Account, Many Users - Dynamic">One Account, Many Users - Dynamic</a> |
| example, the user name used to fetch the mail for all accounts must not be |
| defined as a James user. If it is, a dynamic account will be generated for it |
| and fetch all the mail before the account declared to process mail for all users |
| has an opportunity to run! |
| </li> |
| |
| <li>The now deprecated fetchPOP interacted with the <code>FetchedFrom</code> |
| matcher to detect mail injected by fetchPOP. This will not work with fetchmail. |
| Compared to fetchPOP, there are far fewer occasions when mail injected by |
| fetchmail requires special processing. When it does, use the HasMailAttribute |
| matcher to match the attribute named |
| <code>org.apache.james.fetchmail.taskName</code> to detect all mail injected by |
| fetchmail. To detect mail injected by a specific fetch task, use one of the |
| HasMailAttributeWithValue matchers to match on the attribute name and the |
| attribute value. The attribute value is the name of the fetch task that |
| injected the mail. |
| </li> |
| |
| <li>The POP3 protocol does not enforce support of any of the Flags associated |
| with messages other than DELETED. This means that |
| <code>markseen="true"</code> will most likely have no effect and |
| therefore, the <strong>fetchall</strong> tag will be inoperative. In this |
| situation, the only way to avoid repeatedly fetching the same mail is to delete |
| it from the server using <code>leaveonserver="false"/></code>. |
| </li> |
| |
| <li>If using a Exchange 2000 or Exchange 2003 server get sure you fix the CLRF bug. |
| See <a href="http://support.microsoft.com/kb/816896/en-us"> Bug description and fix</a> |
| </li> |
| </ul> |
| |
| </div> |
| |
| |
| |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">© |
| 2002-2009 |
| |
| The Apache Software Foundation |
| |
| |
| |
| |
| |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"> |
| </script> |
| <script type="text/javascript"> |
| _uacct = "UA-1384591-1"; |
| urchinTracker(); |
| </script> |
| </body> |
| </html> |