Spam Buttons plugin for SquirrelMail
====================================
Ver 2.1, 2008/01/01


Copyright (c) 2005-2008 Paul Lesniewski <paul@squirrelmail.org>



Description
===========

This plugin will place "Spam" and/or "Not Spam" buttons on the 
mailbox message list page as well as on a single message view
page.  The action associated with the buttons (as well as the
button text) can be configured to suit most any spam reporting
system.  Reporting by email, reporting by executing a command 
on the server and reporting by moving (or copying) the message 
to a designated folder are all supported.  

One implementation of a mechanism for accepting spam reports 
sent as message attachments using Postfix can be found here:

   http://gtmp.org/publications/sa-postfix-en
   http://gtmp.org/doku.php/publications/sa-wrapper

A copy of these pages are also saved herein - see: 

   contrib/sa-postfix-en.html
   contrib/sa-wrapper.html



License
=======

This plugin is released under the GNU General Public
License (see COPYING for details).



Donations
=========

If you or your company make regular use of this software, please
consider supporting Open Source development by donating to the authors
or inquire about hiring them to consult on other projects.  Donation
links for the author(s) are as follows:

Paul Lesniewski: https://sourceforge.net/donate/index.php?user_id=508228



Requirements
============

  * SquirrelMail version 1.4.0 or above (although please note
    that report-by-email options may create problems in very
    early versions of SquirrelMail 1.4.x)

  * Compatibility plugin version 2.0.7 or above

  * Working preconfigured spam filtering system - this plugin
    is ONLY a front-end for YOUR spam filtering system!



Configuration
=============

Be sure to configure the plugin to use reporting by email, by 
moving to a folder OR reporting by shell command, but NOT more
than one!

Note that when configuring defaults for your users, where a
"Spam" button should be shown in all folders except the actual 
spam folder (where a "Not Spam" button should be shown instead),
you can define a value for $sb_suppress_spam_button_folder
and $sb_show_not_spam_button_folder, both being the name of the
spam folder.

If you are uncertain how to specify folder names for any of the 
report-by-move or move-after-report or other settings that 
require exact IMAP style folder naming, you can look in the main
SquirrelMail configuration file and as a guide, folders are 
usually named such as by putting together $default_folder_prefix
and $trash_folder.  The other way to find correct folder names
is to visit the SquirrelMail Folders or Folder Options page in
your browser, then view the HTML page source and see how the
folders are named in the value attributes of the folder select
drop-down widgets.

Please see the plugin's configuration file for more details
about the various plugin configuration settings.



Troubleshooting
===============

  * If you have problems getting reporting to work, please
    first verify that you have correctly installed and configured
    your anti-spam system to correctly accept spam reports using
    the mechanism you configured in this plugin.  This plugin IS 
    NOT RESPONSIBLE for providing the actual reporting functionality 
    in your mail server.  You MUST first have a *fully functioning* 
    spam reporting system on your mail server BEFORE you attempt 
    to use this plugin.

  * Make sure the plugin is configured correctly by browsing to
    http://your-squirrelmail-location/src/configtest.php

  * In order to help debug any problems, please use the $sb_debug
    flag in the configuration file and include any output it 
    generates (along with the configuration settings you are using)
    in any help requests.

  * If you do not find that the user-configurable options for 
    deleting or moving messages after report are showing up on
    Options->Display Preferences, please ensure that your reporting
    method is NOT report-by-move-to-folder.
    
  * When using the report-by-move-to-folder functionality, the 
    spam buttons/links will not show when viewing message 
    attachments, since attachments cannot be moved.  Likewise,
    delete-after-report and move-after-report will be ignored
    when reporting message attachments.

  * When the user or administrator has enabled BOTH delete-after-
    report and move-after-report, move-after-report will take
    precedence, and delete-after-report will be ignored.
    
  * Reporting message attachments may not work reliably unless
    using SquirrelMail 1.4.11+ or 1.5.2+.
    
  * It has been reported that when using Sendmail to send messages
    in the main SquirrelMail configuration ($useSendmail) along
    with the report-by-email method (bounce only), reported messages
    do not appear to reach their destination.  The problem may lie
    with how Sendmail treats what looks like a duplicated message.
    If you experience this issue, it is recommended that you choose
    a different reporting method.

  * When using SpamAssassin and you want to make sure the spam/ham 
    counts are correctly increasing when a report is submitted, run 
    sa-learn on the command line with the --dump option and it will 
    show you the total spam and ham for the specified user.  Those 
    totals will change when you click the spam/ham buttons (unless 
    your plugin configuration is incorrect).  For example:

       sa-learn --username=jose@example.org --dump | head

  * If you are using the report-by-shell-commmand method, you can 
    see more debugging output from the command by adding 

       2> /tmp/spam_buttons.log

    to the end of your shell command (note that you may also need 
    to increase the verbosity of the command, usually by using the 
    -D option with the SpamAssassin family of commands).



Help Requests
=============

Before looking for help elsewhere, please try to help yourself:

  * Read the Troubleshooting section herein.

  * Look to see if others have already asked about the same issue.
    There are tips and links for the best places to do this in 
    the SquirrelMail mailing list posting guidelines:
    http://squirrelmail.org/wiki/MailingListPostingGuidelines
    You should also try Google or some other search engine.

  * If you cannot find any information about your issue, please
    first mail your help request to the squirrelmail-plugins
    mailing list.  Information about it can be found here:
    http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
    You MUST read the mailing list posting guidelines (see above)
    and include as much information about your issue (and your
    system) as possible.  Including configtest output, any debug
    output, the plugin configuration settings you've made and
    anything else you can think of to make it easier to diagnose
    your problem will get you the most useful responses.  Inquiries
    that do not comply with the posting guidelines are liable to
    be ignored.
    
  * If you don't get any replies on the mailing list, you are
    welcome to send a help request to the authors' personal 
    address(es), but please be patient with the mailing list.



TODO
====

 * It is possible that use with UW (or dovecot?) will cause 
   "connection dropped" IMAP errors when reporting from the
   message view screen -- IMAP server reports "* BYE Lost mailbox lock"
   which is probably due to other IMAP commands within this
   plugin that "corrupt" the IMAP connection state as far as
   UW is concerned... (only if report by email?  have to do with
   putting mail in the sent folder?) -- this needs more research
   and may be related only to old versions of SM

 * Implement "dont_wait" functionality (see functions.php, search
   for "dont_wait")?  Fork a new process and don't block the user
   experience waiting for slow spam reporting process to do its
   work.  Questions come up: should this feature be considered 
   incompatible with the "reselect" or "report/delete" or "report/move"
   functionalities?  Those (as well as innocent user actions) might
   introduce race conditions.
   Update: one idea is to first make a copy of the target message(s)
   into, say, the attachment dir, from whence the child process can
   then, free of concerns of a race condition, do the learn task and
   then delete the message.  This is similar to how the report-by-shell
   code already does it, saving off a temporary copy of the message in
   the attachment dir, so much of the needed code is already written.

 * If more than one message is being reported and the method is report-
   by-shell-command, it can be faster, at least for some applications,
   to have the target messages in a certain directory and just run 
   the command once on the dir (not the files inside it).  This is 
   specific to that reporting type, so not a high priority at this time.

 * Offer an option that allows admins to indicate that multiple message
   reports should be done in one fell swoop: for report-by-shell-command,
   dump all messages to a single file and report it once... for report-by-
   email, all messages are attached to the same spam report (although for
   bounce functionality, I don't think there is any way to accomodate 
   this.



Change Log
==========

  v2.1 2008/01/01
    * Fixed issue where buttons would not appear upon initial login
    * Added button "inclusion" options (in contrast to the other
      button "suppression" options)
    * Both "inclusion" and "suppression" options can contain lists
      of more than one folder
    * Fix for report-by-email-attachment functionality so it remains
      compatible with 1.4.14+ and 1.5.2+
    * Translators note some new strings have been added
    * Fixed report-by-move functionality in 1.5.0+
    * Completed some internal code reorganization
    * Added ability to move to previous/next message from message view 
      after report-by-move or delete/move after report (instead of 
      returning to message list page)
    * Made move-after-report functionality work correctly when
      report-by-copy is enabled (Thanks to Herman van Rink)
    * Added auto-creation of non-existing folders (Thanks to Herman 
      van Rink)
    * Added patch for 1.5.1, although 1.5.1 is still not officially
      supported - please upgrade to 1.5.2!

  v2.0 2007/09/05
    * Added tag-and-delete functionality (user or admin-configurable)
    * Added tag-and-move functionality (user or admin-configurable)
    * Added report-by-move-to-folder functionality
    * All move functionalities can be changed to copy instead
    * Added email address, username and domain substitutions for the
      report-by-email method
    * Suppress spam/ham buttons when in certain (configurable) folders
    * Suppress spam/ham buttons depending on if a message was tagged
      as spam by an anti-spam scanner (scans message headers)
    * Updated to comply with newest SquirrelMail plugin requirements
    * Added compatibility with SquirrelMail 1.5.2
    * May no longer be compatible with SquirrelMail 1.5.0 or 1.5.1 (untested);
      please upgrade if you are using SquirrelMail development code

  v1.0.1 2005/03/11
    * Fixed some cut n paste typos
    * Fixed internationalization issues
    * Fixed support for IMAP servers without UID support
    * Help people who enter "false" instead of false when overriding $useSendmail

  v1.0 08/03/2005
    * Initial release

