Qpsmtpd:handler

Qpsmtpd#Plugins

NAME

handler - generic email handler/redirector

DESCRIPTION

Generic plugin to reject, drop, redirect, or munge an email based on a numeric score passed as a transaction note e.g. by spam or virus filters. The intention is for this plugin to be able to implement most handling 'policies' in one place, allowing filtering plugins (e.g. spam/virus/etc.) to be simpler, pluggable, and cumulative.

handler should appear in the qpsmtpd config/plugins file after the filter plugins it is assocated with, but before any QUEUE plugins.

Note: redirection requires a recipients() mutator that is not available in stock Qpsmtpd. The one-line patch should be available from wherever you sourced this plugin.

Note: if you want to invoke 'handler' multiple times (e.g. for both spam handling and virus handling), you can create symlinked versions and use the symlink names in the config/plugins file e.g.

  spamhandler note spam_score redirect_threshold 7 redirect_recipient spam
  vhandler note virus_score redirect_threshold 1 redirect_recipient virus

CONFIG

handler accepts the following parameters either via the config/plugins line or via a 'handler' (or your symlinked name, if applicable) config file (one parameter per line, name and value space-separated).

note <name>

The name of the transaction note containing the numeric score to be used to determine how we handle the mail. Default: spam_score.

reject_threshold <threshold>[-<max_threshold>]

The score at which the mail will be rejected outright (or a range within which the score must fall if max_threshold is specified). This should probably be pretty large e.g. for spamassassin, 15 or 20. Rejection is a terminal state, so rejected mail is never redirected or munged. Default: never reject.

reject_note <name>

A transaction note containing the message to be issued with a rejection. The escape sequences %n and %v can be used as placeholders for the score transaction note and its value, respectively. The default message is: "%n too high - message denied." Default reject_note: none.

drop_threshold <threshold>[-<max_threshold>]

The score at which the mail will be dropped i.e. accepted, and then fed to /dev/null (or a range within which the score must fall if max_threshold is specified). Dropping the mail is a terminal state, so rejected mail is never redirected or munged. Default: never drop.

redirect_threshold <threshold>[-<max_threshold>]

The score above which the mail will be redirected instead of delivered to the specified recipients (or a range within which the score must fall if max_threshold is specified). Requires the 'redirect_recipient' parameter below. Default: none.

redirect_recipient <recipient_addr>

Email address to which mail scoring above the redirect_threshold (or within the reject_threshold range) is redirected (currently requires a one-line patch to Qpsmtpd::Transaction).

If the address is a standard email address it replaces the current recipient list completely. Otherwise, if the redirect address is a bare username with no domain component then existing recipient domains are retained, and the username is munged as follows:

• if the address is a bare username ending in a hyphen (e.g. 'spam-'), it is prefixed to existing recipient usernames (allowing per-user mailboxes within a spam account and a spam-default catchall)
• if the address is a bare username beginning with a hyphen (e.g. '-spam'), it is suffixed to existing recipient usernames (allowing per-user spam mailboxes)
• otherwise the bare username (e.g. 'spam' replaces existing recipient usernames (allowing per-domain spam mailboxes)

Examples, spam to recipient gavin@openfusion.com.au:

  redirect_recipient spam@my.domain.com     # -> spam@mydomain.com
  redirect_recipient spam                   # -> spam@openfusion.com.au
  redirect_recipient spam-                  # -> spam-gavin@openfusion.com.au
  redirect_recipient -spam                  # -> gavin-spam@openfusion.com.au

munge_threshold <threshold>[-<max_threshold>]

The score above which the mail becomes a candidate for munging in various ways (or a range within which the score must fall if max_threshold is specified). See the 'munge_subject' parameter below. Default: do not munge.

munge_subject <tag>

The tag (default: '***SPAM***') to prepend to the Subject header (if not already present) if the score exceeds munge_threshold above.

per_recipient <boolean>

(only via config/plugins) Allow per-recipient 'handler' config files to be used. Note that because handler is a post_data plugin, it is required and assumed that all recipients are using the same config definitions (see e.g. the denysoft_multi_rcpt plugin).

NOTES

Might be other actions that could usefully be included here, such as adding to blacklists or greylists or tarpits (e.g. Spam Cannibal).

Currently only tests transaction notes. Should probably extend this to connection notes to as well, to allow connection plugins to be handled too.

AUTHOR

Gavin Carr <gavin@openfusion.com.au>.

---