Mailhandler 2.0

### What's different in Mailhandler 2.x

Mailhandler 2.x is a redesign and rewrite of the architecture of Mailhander 
1.x.  
Mailhandler 2.x aims to be more extensible with how a message can be handled.  
Mailhandler 2.x also leans on other frameworks where possible in order to 
reduce 
the amount of code that lives in Mailhandler itself when that code consists 
of patterns better provided by other library or framework modules.

In hard terms, here's what's new in Mailhandler 2.x:

* Uses Ctools Plugins and Export UI plugins to handle mailbox management, 
including creating, editing, deleting, cloning, exporting, and importing 
mailbox configurations.
* Integration with the Feeds module to handle fetching, parsing, and processing 
messages in IMAP and POP mailboxes.  Feeds integration also helps with 
scheduling processing times.  You can write your own message fetcher, parser, or
processor if you'd like to handle messages in a custom way.
* Ctools Plugin system is also used to allow custom command and authentication 
plugins to be written.  For example, if you want to write a command parser to 
handle parsing commands in messages which will be used to then map to CCK 
fields, this is now possible to do using the Mailhandler 2.x API.  However, 
this exact type of plugin itself (cck parsing) has yet to be written.
* New sub module "mailhandler_node" now holds all the node-related 
assumptions.  This sub module implements a custom feeds processor to handle 
creating nodes and comments from incoming messages.  A default mailbox fetcher 
and parser lives in the main mailhandler module which are not node centric, but 
able to be used by the node processor.
* Some business logic remains the same, such as the main mailhandler mailbox 
retrieval library in mailhandler.retrieve.inc

### How to install and use Mailhandler 2.x

* Create mailbox configurations at admin/build/mailhandler.  When creating a 
new mailbox, if you want that mailbox to be used to create nodes/comments, then 
you must fill out both the "Basic mailbox" and "Node mailbox" settings, and 
set the "Node mailbox" as the active mailbox type.  You can set the active 
mailbox type by clicking on the "Set active" link in the left sidebar of the 
mailbox editing screen.
* Then, go to admin/build/feeds and choose to create a new importer 
(admin/build/feeds/create).  Enter a name and description for the new importer 
and click 'next'.
* In the next page, you must at least edit the fetcher, parser, and processor, 
and choose the "Mailhandler fetcher", "Mailhandler IMAP stream parser", and 
"Mailhandler node processor" respectively.  You may also edit the 
"Basic settings" and choose those settings as desired.
* You must configure the "mapping" for the Mailhandler Node Processor.  The 
mapping allows you to choose which mail parts map to which Drupal targets.  In 
order for commands to be parsed from the message, you must map "commands" 
source to "Commands" target.  In order for message authentication to work 
correctly, including assignment of the correct author, you must map 
"authenticate" source to "Authenticate" target.
* Now, if you did not attach your importer to a specific content type, you can 
go to /import, choose from the drop down the mailbox you've just setup to 
import from, and select "Import" which should import your messages.  If you 
attached your importer to a content type, you'll need to create a new node of 
the corresponding type, choosing from the node form which mailbox to tie to 
that node, save the node, and then you'll be able to import from the node view 
of that node.

Additional details:

* You'll notice when creating a new mailbox from admin/build/mailhandler that 
you can choose a command and authentication plugin.  The default selections 
behave like the default behavior in Mailhandler 1.x.


### Todos

This is in an alpha state with several todos noted in the code.  Larger todos 
include:

* Upgrade script for 1.x to 2.x
* Get working with Mail Comment
* Compatibility with other dependent modules

### More documentation

More documentation is located here at:
http://drupal.org/handbook/modules/mailhandler which discusses topics such as
how to configure mailboxes for specific email providers.