mailproc-fetch

Home > Books > NetKernel API and Services Reference > Accessor Listing > SMTP Email Service > mailproc-fetch

Module

The mailproc-fetch accessor is exported by the urn:org:ten60:netkernel:mod:smtp module. Import this module to gain access to the accessor.

Syntax

URI

active:mailproc-fetch

Argument	Rules	Description
config	Mandatory	A mailprocessor configuration

Example Usage

DPML

<instr>
  <type>mailproc-fetch</type>
  <config>config.xml</config>
</instr>

NetKernel Foundation API

req=context.createSubRequest("active:mailproc-fetch");
req.addArgument("config", [resource representation, aspect, or URI] );
result=context.issueSubRequest(req);

Purpose

The mailproc-fetch accessor retrieves an individual unread email message from a POP or IMAP mailbox. It uses the MailTransport but allows for pull-processing of mailbox messages rather than the polled event model typically used by the MailTransport.

The mailbox which is polled does not need to be registered with the MailTransport. Each request to mailproc-fetch must provide a mailprocessor config specifying the mailbox to retrieve messages from.

The MailTransport which handles the fetch request is located dynamically and is discovered from the first instance of ffcpl:/etc/MailTransportConfig.xml in the current module address space.

For more information on the operation of the MailTransport see the MailTransport guide.

Configuration

A mailprocessor has the following configuration...

<mailProcessor>
  <type>pop | imap</type>
  <host>hostname of mailserver</host>
  <username />
  <password />
  <processURI>the URI which will be invoked with each processed message</processURI>
  <pollInterval>time interval in ms at which mailbox will be polled</pollInterval>
  <filters>
    <rule>
      <field>to | cc | subject | body</field>
      <match>a regex pattern to match the field against</match>
    </rule>
                    ...Any number of filter rules may be added here...
                
  </filters>
  <options>
    <maxRetries />
    <deleteProcessed />
    <preserveFiltered />
  </options>
</mailProcessor>

Any number of filters may be applied to the messages in the mailbox. Only messages which match the filters will be processed. If no filters are specified all messages are processed.

The default behaviour of a mailprocessor is to retry a mailbox 3 times, to mark processed messages as read and to delete messages which fail the filter criteria. The defaults may be modified with the following options...

mailFolder the name of the mailfolder to use to locate messages (note: only valid with IMAP mailservers, defaults to INBOX).
maxRetries the number of times to attempt to process a mailbox before shutting down the mailprocessor. A value of -1 means never shutdown.
deleteProcessed after processing delete the message. Generally pop mailboxes should set this option to avoid processing loops.
preserveFiltered by default messages which do not successfully pass the filtering stage are deleted. This option preserves these messages but marks them as read.

Returned Message Structure

mailproc-fetch returns a representation containing an IAspectMultiPart. A multipart aspect contains multiple sub-representations accessed from a java.util.List.

The first item in the list is always the mail header which has an Aspect of MessageHeaderAspect. Subsequent entries are the message body parts in email order, each of these has an Aspect of MessageBodyAspect which implements IAspectReadableBinaryStream.