FetchPOP is controlled by a configuration block in the config.xml. The fetchpop tag defines the boundaries of the configuration block. It encloses all the relevant configuration for the FetchPOP scheduler. The behavior of the POP service is controlled by the attributes and children of this tag.

This tag has an optional boolean attribute - enabled - that defines whether the service is active or not. The value defaults to "false" if not present.

The only permitted children of the fetchpop tag are fetch elements. Each of these fetch tags defines a single FetchPOP task.

The fetch tag has a single required attribute, name. The name of each FetchPOP task must be unique.

In addition to the name attribute, the fetch tag has four children, all of which are required.

• host - The host name or IP address of the POP3 server hosting the mail to be fetched.
• user - The user name of the account whose mail is to be fetched.
• password - The password for the account whose mail is to be fetched.
• interval - A non-negative integer representing the number of milliseconds between fetches.

There are a number of issues which have to be considered when handling fetched mail, such as avoiding circular routing of mail. Some scenarios are described below with suggested configurations.

Handling All Mail for a Domain

This is the intended primary use of FetchPOP. If all mail for a domain being fetched is ultimately being handled by this server then it is enough to add the domain name as a servername to the servernames section described here. This is the simplest solution and is used where James is being used to redistribute all mail from the free catch-all POP accounts provided by many domain registration/hosting companies.

Handling a Subset of a Domain's Mail

If only part of a domain's mail (perhaps only a single user's POP account) is being handled by this instance of James it is important that outgoing mail addressed to this domain that is not intended for James be properly delivered. To enable this filtering the FetchPOP scheduler adds a header, X-fetchedby, to the fetched message. This header can be checked using the provided matcher FetchedFrom. This matcher can be used to direct fetched mail to a processor set up to handle mail fetched from one or more POP3 accounts. The matcher should be used exactly once in the mail pipeline for each FetchPOP task, as the matcher removes a matching header to prevent outgoing replies or redirections from looping. The FetchedFrom matcher is configured with the name of the particular FetchPOP task it is supposed to match. In general, this matcher will be used to direct mail to a custom processor for further processing. A mailet tag such as the following <mailet match="FetchedFrom=fetchtaskname" class="ToProcessor"> <processor>fetchprocessor</processor> </mailet> where fetchtaskname is the name of the FetchPOP task being matched and fetchprocessor is the name of the fetched mail processor can be used to this purpose. The fetched mail processor should contain mailets which will filter and forward mail to real local or remote users. This can be achieved in the usual fashion as described in the SpoolManager configuration section and in the out of the box configuration file.

Catching Undeliverable Mail

It is important to note that this first version of FetchPOP does not access the original intended recipient address of the mail, but instead uses the To: address from the message headers. Since this header may contain an alias for the intended recipient, or may never have contained the intended recipient address (it could have been in the Cc: or Bcc: fields) it is possible that James will be unable to deliver the fetched mail. It is intended that this behaviour be addressed in the next version of James, but in the meantime a catch-all forwarding of locally undeliverable fetched mail is recommended. To handle messages where the intended recipient can be determined but is not present in the To: header, the FetchedFrom matcher can be used. Place a mailet tag with this matcher between the "RecipientIsLocal" and "HostIsLocal" in the Transport processor as defined in the out of the box configuration. The mailet tag should be configured to use the provided ToProcessor mailet to direct fetched mail to a custom processor. Thus all mail fetched by FetchPOP that could not be trivially mapped to a local user account will undergo further processing, allowing more complex delivery handling. For safety the All matcher should be used at the end of your custom fetched mail processor. This can be used to catch all mail not handled by previous mailets in the processor. This will enable you to ensure that your configuration is correct and that any mail not correctly delivered is available for examination by the postmaster.