CONTENTS OF THIS FILE --------------------- * Requirements * Quick setup * Overview * Importer configuration * Source configuration * More information REQUIREMENTS ------------ You will need to have access to a dedicated mailbox (IMAP or POP3) to receive posts via email. You must also have the PHP IMAP library installed- see the documentation at https://drupal.org/node/300794. Dependencies: - ctools >= 6.x-1.9 - feeds >= 6.x-1.0-beta11 - autoload >= 6.x-2.0 QUICK SETUP ----------- The goal of this tutorial is to show you how to quickly import messages from any mailbox using cron. After you've got this working, refer to the sections below for a deeper understanding of Mailhandler's architecture. There are three basic items that need to get set up: - Mailhandler Mailboxes store connection settings for an IMAP/POP3 mailbox - Feeds Importers import messages from those mailboxes - Feeds Source nodes link a specific importer to a specific mailbox to allow automatic imports on cron runs Note that all of these components can be reused in various ways. For instance, you could have one Importer retrieve messages from multiple Mailboxes by creating a Source node for each Mailbox. Or, multiple Importers could run on one mailbox (with one Importer looking for nodes and the other looking for comment replies). Before you get started, you'll need to have a working Drupal installation and the required modules (dependencies) listed above. No configuration of those modules should be necessary. The quick-start module provides a test Mailbox and message, a default Importer, and a Source content type. Try to import this test message now: - Go to $base_url/admin/build/modules - Enable the "Mailhandler quick-start" module. - Go to $base_url/node/add/mailhandler-source - Give the node a title (such as 'Test source'). - For "Feed"->"Mailbox", select the mailbox to import from. - Save the node. You should see the message 'created 1 story node'. Congrats, you just imported your first node with Mailhandler 2.x! - If you go to $base_url/admin/content/node, you should see the 'Test source' node and the imported test message (which should be unpublished). Now that you've verified that the basic features are working, it's time to customize them to suit your own needs: - Send a test email to an IMAP or POP3 mailbox. If you are using the default authentication options, you must send the email from the same address as your Drupal user account. - Go to $base_url/admin/build/mailhandler/add - Fill in the details for your IMAP/POP3 mailbox. Mailhandler will report how many messages are in the mailbox if it is able to connect. Click "Save". - Follow the steps for 'Import a test message' (above) to import messages from the mailbox. Note that only unread messages will be imported. Note that new emails will be imported on cron runs. If you'd prefer that new messages NOT be imported automatically, you will need to edit the default importer ($base_url/admin/build/feeds/edit/mailhandler_nodes/settings) and for 'Attach to content type' select 'Use standalone form'. Messages can then be manually imported at $base_url/import/mailhandler_nodes. OVERVIEW -------- Mailhandler fetches content from IMAP or POP mailboxes, which are represented by the mailhandler_mailbox_ui class. Feeds Importers configured to use the Mailhandler Fetcher can use these mailboxes as Feeds Sources, in the same way that Importers using the HTTP Fetcher would use URLs as sources. Thus, at the bare minimum you must configure at least one mailbox and at least one Feeds Importer, as described in the section above. A Feeds Importer is made up of a Fetcher, Parser, and Processor. Mailhandler provides only a Fetcher and Parser, and requires the use of an existing processor (typically, the Node Processor or Comment Processor). Additionally, Mailhandler defines two types of plugins that extend the Mailhandler Parser: 'authentication plugins' match the sender of the email to a Drupal user account, while 'commmand plugins' extract various parts of a message (such as files and IMAP headers) and allow users to 'command' attributes of created content using key: value pairs. You can either manually run an importer, or you can attach an importer to a content type. Then 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, or import on cron. Finally, Mailhandler provides some input filters that can strip common garbage from imported messages (such as signatures). IMPORTER CONFIGURATION ---------------------- -- Fetcher -- Using the 'filter' setting, choose which types of messages to retrieve (nodes, comments, or all). Note: if this importer fetches a type of message that the processor (below) does not support, that message will be marked as read or deleted! Thus, it's important to set this filter appropriately. -- Parser -- Choose plugins to handle commands and authentication, as well as set available commands. The commands plugins generate mapping sources that will appear in the processor mapping form in the next step. -- Processor -- You will most likely want to use the Node Processor or Comment Processor. For Nodes Processor settings, choose (among other things) whether authorization should be performed- in other words, whether the post author has permissions to actually post content (by default Feeds doesn't check this). For Nodes Processor mappings, you'll need to map "sources", provided by the Mailhandler Parser and its command plugins, to node "targets". Note that if you don't map things correctly here, certain features that you configured earlier (such as authorization and commands processing) will not work. To prevent re-importation of duplicate messages, you will want to map the "Message ID" source to a field and mark it as unique. For more information, see http://drupal.org/node/1329218 If you would like to import comments by email, you can download Mailcomment and Feeds Comment Processor and select the Feeds Comment Processor instead. SOURCE CONFIGURATION -------------------- Source nodes are what link your Importer to a specific mailbox and allow messages to be imported on cron runs. Here you can also set "default commands" that will be applied to all messages imported by this source node. For instance, if you set available commands (in the parser configuration) to "status", mapped "status" to "Published status" (in the processor configuration), and set default commands (in the source configuration) to "status: 1", all imported posts will be published by default. Users can override this by placing the command "status: 0" at the top an email's body. MORE INFORMATION ---------------- More documentation is located at http://drupal.org/handbook/modules/mailhandler which discusses topics such as how to configure mailboxes for specific email providers.