README.txt in Mailhandler 6

# $Id$

Summary
-------

The Mailhandler module allows registered users to create or edit content (nodes
and comments) via email. Authentication is usually based on email addres of the
'From:' e-mail header, but can be extended to use additional security tokens.

E-mail submissions accept additional attributes for the submitted content, like
promote, unpublish, set sticky, or include taxonomy terms, teasers and almost
any other parameters using the Commands capability.

See the 'more help' page located at 'admin/help/mailhandler' within this module
for more information, or read the complete documentation page at drupal.org:
http://drupal.org/handbook/modules/mailhandler


Requirements
------------

For Mailhandler to work, the IMAP dynamic PHP extension must be enabled. On
Windows PHP installations, this is as easy as uncommenting the line containing
"extension=php_imap.dll" in php.ini. For other OS, you may need to recompile PHP
if you don't have this extension already.

Beware that IMAP PHP extension has some issues when runing in Microsoft Windows
systems, preventing the extension to read local file mailboxes.


Installation
------------

Download and enable the module as usual. Go to the status report page (located
at /admin/reports/status) and verify that the IMAP extension is working.

Go to the module Mailboxes administration page (/admin/content/mailhandler) and
add a mailbox. You'll need a corresponding Folder, POP, or IMAP mailbox (email
account) dedicated to inbound Drupal mail. Additional mailboxes may be useful
for specialized situations.


Admin Usage
------------

1. Send a few emails to a Mailhandler email address from an email address which is registered on your site.
Then visit cron.php to kickoff a pull from your mail server and processing of pending email. Alternatively,
follow the 'retrieve' link for your newly created mailbox. You should see new nodes on
your site (go to admin/content/node) or receive error message replies via email.


Other modules integration
-------------------------

Mailhandler is known to integrate with other modules that might extend their
functionality. Consider installing any of this modules to make Mailhandler work
the way to require to do:

 - marksmarty: provides special input format filters that might be used to
   improve the presentation of plain text email for the Web.
 - mailaias: module provides additional email addresses for your users. this
   module is currently, deprecated in favor of multiple_email module, but the
   integration between mailhandler and multiple_email has not been finished yet.
 - mailcomment:
 - listhandler:

Developer Usage
---------------

If you are a developer and want to integrate mailhander or parts of it into your
specific configuration or create a helper module, please realize that you can't
freely rely on any function or element that exists in the module, as this might
be changed inadvertently. However, there are a set of functions that are granted
as being public interface for other modules to interact with mailhandler.

Among the module hooks described in mailhandler.api.inc, the following mentions
are part of the functions that can be safely referenced from outside of this
module:

 Mailbox database interaction
 - mailhandler_mailbox_load
 - mailhandler_mailbox_load_multiple
 - mailhandler_mailbox_validate
 - mailhandler_mailbox_test
 - mailhandler_mailbox_save

 Mailbox processing


Credits
----------
 First implementation from Julian Bond's excellent Blogmail module for Drupal 3.
 IMAP folder support contributed by Gerhard.