Restrict Senders plugin for SquirrelMail
========================================
Ver 1.2, 2007/03/12

Original author: Paul Lesniewski <paul@squirrelmail.org>


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

This plugin allows you to place restrictions on the destination
addresses of all outgoing email and/or the amount of mail sent
by any one user with a certain time period (ONLY email that is 
sent using SquirrelMail is monitored).  

Destination addresses can be restricted such that you may limit
the total number of recipients for all outgoing emails (an anti-
spam tactic) or you may limit the addresses/domains to which your 
users are allowed or disallowed to send mail to.  Recipient  
address restrictions may be defined on a per-user or per-domain 
basis, or for all of your users.

Email alerts can also be sent to the system administrator when
a user has attempted to send too many emails in a day or one email
with too many recipients, and users who continue to send out too
many "mass emails" in a short period of time may be banned from 
sending any more messages whatsoever.  Each of these restrictions
may be defined on a per-user or per-domain basis by using the 
Login Manager (vlogin) plugin to override the corresponding settings.

Please note that this plugin is a poor replacement for real SMTP
filtering, which provides the same functionality no matter what
email client your users are using (it will also be much faster).
This plugin will work ONLY for email sent using SquirrelMail.
For just one good example of how to do this kind of filtering with
your SMTP server (Postfix), see:

http://www.stahl.bau.tu-bs.de/~hildeb/postfix/postfix_restriction_classes2.shtml

Note that for better performance, recipient address restrictions
are cached in the user's session.  Thus, if you are adjusting 
and testing your restriction rules, you'll need to log out and
back in again to see each change take effect.

If you want your users to have a visual indication of what 
recipient addresses were allowed/blocked when they send email,
you should download and install the sent_confirmation plugin,
which, as of version 1.2, is compatible with this plugin.



License
=======

This plugin is released under the GNU General Public
License (see the file 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.1 or above
  * Compatibility plugin version 2.0.7 or above



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

  data/config.php
  ===============

  $restrictNumberOfRecipients
  ---------------------------
  can be set to the total number of outgoing addresses 
  (including CC: and BCC: addresses) that are allowed for 
  any one email.  Set this to zero to turn off this 
  functionality (allows unlimited number of recipients).

  Note that you may specify override values for the 
  $restrictNumberOfRecipients setting in the "Login Manager"
  (vlogin) plugin if you are using that by specifying 
  the "vlogin_restrictNumberOfRecipients" setting in the 
  vlogin configuration.

  $restrictNumberOfEmailsPerDay
  -----------------------------
  can be set to the maximum number of outgoing emails that 
  may be sent by any one user in any one day.  Set this to 
  zero to allow unlimited number of emails to be sent.  Any 
  user caught by this restriction will not be allowed to 
  send any messages for the rest of the day unless an 
  administrator manually removes the following setting from 
  the user's preferences:
     todays_email_count
 
  Note that you may specify override values for this in the
  "Login Manager" (vlogin) plugin if you are using that
  by specifying the "vlogin_restrictNumberOfEmailsPerDay" setting
  in the vlogin configuration.
 

  $restrictSubsequentMassEmails
  -----------------------------
  allows control over accounts that send too many "mass emails"
  within a fixed amount of time.   This setting allows you to 
  effectively turn off all sends for any user who blasts out too 
  many mass-recipient emails in a fixed amount of time.  Once 
  caught, an alert email is sent to $rs_report_addresses (make 
  sure you have not turned this off!) and that account will no 
  longer be able to send any more email (through SquirrelMail 
  only) until an administrator manually removes this preference 
  from the user's preferences:
     USER_IS_POSSIBLE_SPAMMER
 
  This setting consists of three values separated by a colon.  
  The first is the number of recipients that comprise the minimum 
  threshold of a "mass email", the second is the number of emails 
  that should trigger this functionality, and the third is the 
  number of minutes within which the emails must be sent.
 
  For example, with a setting of 20:4:5, if a user sends 4 or 
  more emails to 20 or more people within a 5 minute time span,
  the user will be blocked from sending any more emails until 
  manually unlocked as described above.

  Set as an empty value to disable this functionality.
 
  Note that you may specify override values for this in the
  "Login Manager" (vlogin) plugin if you are using that
  by specifying the "vlogin_restrictSubsequentMassEmails" setting
  in the vlogin configuration.


  $restrictSubsequentMassEmailsWhitelist
  --------------------------------------
  gives you a way to exempt certain users from being banned per 
  the $restrictSubsequentMassEmails setting.  Enter the full user
  name of any users who should never be banned for sending out
  "mass mails" that violate the rate limit set above.
 
  Note that you may specify override values for this in the
  "Login Manager" (vlogin) plugin if you are using that
  by specifying the "vlogin_restrictSubsequentMassEmailsWhitelist" 
  setting in the vlogin configuration.


  $whitelisted_addresses
  $rs_delimiter 
  ----------------------
  allows you to define a list of one or more addresses to which 
  users may still send messages even when they are prevented from 
  doing so because of the other settings in this plugin (too many 
  messages in a day or too many "mass emails").  This can be 
  helpful to allow (im)properly banned users still contact a help/
  support staff.  The addresses in this list will also be exempted 
  from the rules defined in the send_restrictions.php file.  The 
  delimiter defined here should correspond to the mailbox/host part 
  separator for parsing the white-listed addresses (usually "@").


  $restrictDomains
  ----------------
  is the on/off switch for the functionality that checks your 
  custom recipient address (full address - not just the domain
  thereof, despite the name of this setting) restrictions 
  (defined as indicated below).  Set to zero if you are only 
  restricting the total number of email recipients.  Set to 1 to
  use the rules defined in data/send_restrictions.php.

  Also note that you may specify a different set of rules for 
  different users, domains, or user groupings by using the 
  "Login Manager" (vlogin) plugin and specifying the 
  "vlogin_restrict_senders_rules_file" setting in the vlogin 
  configuration, which must contain the full path to the desired
  rules file.


  $rs_report_addresses
  --------------------
  is a list of one or more comma-separated email addresses to 
  which alert emails will be sent.  To disable alert emails,
  make sure this setting is empty.


  $report_abuse_too_many_today_message
  $report_abuse_too_many_recipients_message
  -----------------------------------------
  are templates for creating your own administrative alert emails
  for events triggered by $restrictNumberOfEmailsPerDay and 
  $restrictNumberOfRecipients respectively.  You may include several
  replacement keys that will be swapped with information about the
  user in question and the email that triggered the event (such as
  the username and to whom the message was sent -- see the sample
  configuration file for exact details), but PLEASE make sure you
  have an appropriate privacy policy and terms of service agreement
  in place before allowing yourself to see any parts of your users'
  messages.  Leave these settings blank to use the default messages
  that come with this plugin.


  $account_disabled_message
  -------------------------
  allows you to specify your own message which the user will see
  when they have been banned from sending emails per the 
  $restrictSubsequentMassEmails setting.  Leave blank to use the
  default message provided by this plugin.


  $rs_use_Vadmin_delete_link
  --------------------------
  lets administrators who also run the Vadmin plugin include a link
  in all administrative alerts that links to a page that allows you
  to delete the account in question.


  $rs_debug
  ---------
  helps diagnose problems when the plugin does not appear to be 
  working as expected.  Enable this and include the output it 
  generates in any help requests.  Make sure this is turned off 
  in a production environment.


  data/send_restrictions.php
  ==========================

  Detailed instructions for configuring this file are included 
  in the send_restrictions.sample.php file, but here is an
  overview and some things to keep in mind:

  You may define addresses that are allowable or disallowable 
  for outgoing email in a very flexible manner.  You may 
  define these rules for just some or all of your users,
  for just some or all of the domains you may host, or for
  everyone who uses SquirrelMail to send email.

  Note that you can specify the users and domains these rules
  apply to explicitly, or in groups by using wildcards.  Also
  note that every set of rules can be made up of multiple
  allowable AND/OR disallowable addresses, as well as a default
  ("allow" or "deny") for any addresses that didn't match.  There
  is also a default allow/deny directive at the end of the file
  that catches all email sent by users and domains for which 
  you have not defined any rules.  Finally, it is important to
  understand that the first matching rule always wins, and any
  rules after that are ignored.



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

Help requests are welcome at my personal email address, but I
request that you first post to the SquirrelMail Plugins mailing
list, where you'll get faster help from more people and other
people with the same problem will be able to see how your issue
was resolved.  If you don't get good answers that way, you may
try emailing me directly.

Info about the SquirrelMail Plugins mailing list can be found
on the SquirrelMail web site.  It is currently located at:

http://lists.sourceforge.net/mailman/listinfo/squirrelmail-plugins
squirrelmail-plugins@lists.sourceforge.net



Future Work
===========

   *  Email alerts use current login domain for Vadmin links,
      which may not be correct when admin is logged in and reading
      those emails.
   *  Instead of just print_r for message object in email
      alerts, send prettified version thereof
   *  Ideas?



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

  1.2 - 2007/03/12 - Paul Lesniewski <paul@squirrelmail.org>
   * Added ability to send email alerts to system administrator 
   * Added ability to effectively turn off accounts of users who
     send out too many "mass emails" in a fixed time period.
   * Added compatibility with mass_mailing plugin
   * Added configuration check (for use with src/configtest.php)
   * Allow destination addresses to be restricted by mailbox as
     well as domain
   * Updated for use with SquirrelMail 1.5.2+
   * Miscellaneous updates for new plugin specifications
   * Added ability to override rules file per user/group/domain
     by using Login Manager (vlogin)

  1.1 - 2005/04/16 - Paul Lesniewski <paul@squirrelmail.org>
   * Added ability to use vlogin to override $restrictNumberOfRecipients
     setting (use "vlogin_restrictNumberOfRecipients" in vlogin).
     This may only work if vlogin is listed before restrict_senders in 
     your plugin order.
   * Added ability to restrict number of emails sent per day (also
     can be overridden by vlogin with "vlogin_restrictNumberOfEmailsPerDay")
   * Internationalization updates (correct bind calls; locale is
     in SquirrelMail locale directory)

  1.0 -  Paul Lesniewski <paul@squirrelmail.org>
   * Initial release



