Issue #2099845 by Dane Powell: Suggest secure mailbox settings.
[project/mailhandler.git] / INSTALL.txt
1 CONTENTS OF THIS FILE
2 ---------------------
3
4  * Requirements
5  * Quick setup
6  * Overview
7  * Importer configuration
8  * Source configuration
9  * More information
10
11 REQUIREMENTS
12 ------------
13
14 You will need to have access to a dedicated mailbox (IMAP or POP3) to receive
15 posts via email. You must also have the PHP IMAP library installed- see the
16 documentation at https://drupal.org/node/300794.
17
18 Dependencies:
19 - ctools >= 6.x-1.9
20 - feeds >= 6.x-1.0-beta11
21 - autoload >= 6.x-2.0
22
23 QUICK SETUP
24 -----------
25
26 The goal of this tutorial is to show you how to quickly import messages from
27 any mailbox using cron. After you've got this working, refer to the sections
28 below for a deeper understanding of Mailhandler's architecture.
29
30 There are three basic items that need to get set up:
31 - Mailhandler Mailboxes store connection settings for an IMAP/POP3 mailbox
32 - Feeds Importers import messages from those mailboxes
33 - Feeds Source nodes link a specific importer to a specific mailbox to allow
34   automatic imports on cron runs
35
36 Note that all of these components can be reused in various ways. For instance,
37 you could have one Importer retrieve messages from multiple Mailboxes by
38 creating a Source node for each Mailbox. Or, multiple Importers could run on
39 one mailbox (with one Importer looking for nodes and the other looking for
40 comment replies).
41
42 Before you get started, you'll need to have a working Drupal installation and
43 the required modules (dependencies) listed above. No configuration of those
44 modules should be necessary.
45
46 The quick-start module provides a test Mailbox and message, a default Importer,
47 and a Source content type. Try to import this test message now:
48 - Go to $base_url/admin/build/modules
49 - Enable the "Mailhandler quick-start" module.
50 - Go to $base_url/node/add/mailhandler-source
51 - Give the node a title (such as 'Test source').
52 - For "Feed"->"Mailbox", select the mailbox to import from.
53 - Save the node. You should see the message 'created 1 story node'. Congrats,
54   you just imported your first node with Mailhandler 2.x!
55 - If you go to $base_url/admin/content/node, you should see the 'Test source'
56   node and the imported test message (which should be unpublished).
57
58 Now that you've verified that the basic features are working, it's time to
59 customize them to suit your own needs:
60 - Send a test email to an IMAP or POP3 mailbox. If you are using the default
61   authentication options, you must send the email from the same address
62   as your Drupal user account.
63 - Go to $base_url/admin/build/mailhandler/add
64 - Fill in the details for your IMAP/POP3 mailbox. Mailhandler will report how
65   many messages are in the mailbox if it is able to connect. Click "Save".
66 - Follow the steps for 'Import a test message' (above) to import messages from
67   the mailbox. Note that only unread messages will be imported.
68
69 Note that new emails will be imported on cron runs. If you'd prefer that new
70 messages NOT be imported automatically, you will need to edit the default
71 importer ($base_url/admin/build/feeds/edit/mailhandler_nodes/settings) and for
72 'Attach to content type' select 'Use standalone form'. Messages can then be
73 manually imported at $base_url/import/mailhandler_nodes.
74
75 OVERVIEW
76 --------
77
78 Mailhandler fetches content from IMAP or POP mailboxes, which are represented by
79 the mailhandler_mailbox_ui class. Feeds Importers configured to use the
80 Mailhandler Fetcher can use these mailboxes as Feeds Sources, in the same way
81 that Importers using the HTTP Fetcher would use URLs as sources.
82
83 Thus, at the bare minimum you must configure at least one mailbox and at least
84 one Feeds Importer, as described in the section above.
85
86 A Feeds Importer is made up of a Fetcher, Parser, and Processor. Mailhandler
87 provides only a Fetcher and Parser, and requires the use of an existing
88 processor (typically, the Node Processor or Comment Processor). Additionally,
89 Mailhandler defines two types of plugins that extend the Mailhandler Parser:
90 'authentication plugins' match the sender of the email to a Drupal user account,
91 while 'commmand plugins' extract various parts of a message (such as files and
92 IMAP headers) and allow users to 'command' attributes of created content using
93 key: value pairs.
94
95 You can either manually run an importer, or you can attach an importer to a
96 content type. Then you'll need to create a new node of the corresponding type,
97 choosing from the node form which mailbox to tie to that node, save the node,
98 and then you'll be able to import from the node view of that node, or import on
99 cron.
100
101 Finally, Mailhandler provides some input filters that can strip common garbage
102 from imported messages (such as signatures).
103   
104 IMPORTER CONFIGURATION
105 ----------------------
106 -- Fetcher --
107 Using the 'filter' setting, choose which types of messages to retrieve (nodes,
108 comments, or all). Note: if this importer fetches a type of message that the
109 processor (below) does not support, that message will be marked as read or
110 deleted! Thus, it's important to set this filter appropriately.
111
112 -- Parser --
113 Choose plugins to handle commands and authentication, as well as set available
114 commands. The commands plugins generate mapping sources that will appear in the
115 processor mapping form in the next step.
116
117 -- Processor --
118 You will most likely want to use the Node Processor or Comment Processor.
119
120 For Nodes Processor settings, choose (among other things) whether authorization
121 should be performed- in other words, whether the post author has permissions to
122 actually post content (by default Feeds doesn't check this).
123
124 For Nodes Processor mappings, you'll need to map "sources", provided by the
125 Mailhandler Parser and its command plugins, to node "targets". Note that if you
126 don't map things correctly here, certain features that you configured earlier
127 (such as authorization and commands processing) will not work.
128
129 To prevent re-importation of duplicate messages, you will want to map the
130 "Message ID" source to a field and mark it as unique. For more information, see
131 http://drupal.org/node/1329218
132
133 If you would like to import comments by email, you can download Mailcomment and
134 Feeds Comment Processor and select the Feeds Comment Processor instead.
135
136 SOURCE CONFIGURATION
137 --------------------
138 Source nodes are what link your Importer to a specific mailbox and allow
139 messages to be imported on cron runs. Here you can also set "default commands"
140 that will be applied to all messages imported by this source node.
141
142 For instance, if you set available commands (in the parser configuration) to
143 "status", mapped "status" to "Published status" (in the processor
144 configuration), and set default commands (in the source configuration) to
145 "status: 1", all imported posts will be published by default. Users can
146 override this by placing the command "status: 0" at the top an email's body.
147
148 MORE INFORMATION
149 ----------------
150   
151 More documentation is located at http://drupal.org/handbook/modules/mailhandler
152 which discusses topics such as how to configure mailboxes for specific email
153 providers.