/ 
Mail-Qmail-Filter-1.32
River stage one • 1 direct dependent • 1 total dependent
/ Mail::Qmail::Filter

NAME

Mail::Qmail::Filter - filter e-mails in qmail-queue context

SYNOPSIS

use Mail::Qmail::Filter;

Mail::Qmail::Filter->new->add_filter(
    '::LogEnvelope',
    '::DMARC' => {
        skip_if_relayclient => 1,
    },
    '::CheckDeliverability' => {
        match               => qr{/ezmlm-(?:checksub|reject)\b},
        skip_if_relayclient => 1,
    },
    '::SpamAssassin' => {
        skip_if_relayclient => 1,
        reject_score        => 5.2,
        reject_text         => 'I think your message is spam.',
    },
    '::Queue',
)->run;

DESCRIPTION

Mail::Qmail::Filter and its submodules are designed to help you filter incoming e-mails when using qmail as MTA.

You should use it like so:

  1. Write a frontend script to configure your filters, like the one in the "SYNOPSIS".

  2. In the run file for your qmail-smtpd instance, e.g. /var/qmail/supervise/qmail-smtpd/run,

    export QMAILQUEUE=path_to_your_frontend_script

In each filter, you may do various things:

  • examine and change envelope data (RFC5321.MailFrom and recipients)

  • examine and modify the e-mail message (header and/or body)

  • "reject" e-mails (or defer them)

FILTERS INCLUDED

This distribution ships with the following predefined filters:

Queueing the message

Usually you want to use Mail::Qmail::Filter::Queue as the last filter in your chain to pass the message on to qmail-queue, because if you don't, the message will be discarded.

Rejecting filters

Mail::Qmail::Filter::CheckDeliverability

check deliverability according to .qmail files

Mail::Qmail::Filter::DMARC

validate message against DMARC policy of the sender domain

Mail::Qmail::Filter::RequireFrom

only allow certain RFC322.From addresses

Mail::Qmail::Filter::SpamAssassin

spam-check message

Mail::Qmail::Filter::ClamAV

scan message for viruses

Mail::Qmail::Filter::ValidateFrom

validate RFC5322.From

Mail::Qmail::Filter::ValidateSender

validate RFC5321.MailFrom

Envelope modifying filters

Mail::Qmail::Filter::RewriteSender

Header modifying filters

Mail::Qmail::Filter::RewriteFrom

Logging-only filters

Mail::Qmail::Filter::Dump
Mail::Qmail::Filter::LogEnvelope

Experimental filters

Mail::Qmail::Filter::SkipQueue

COMMON PARAMETERS FOR ALL FILTERS

skip_if

When given a sub routine as an argument, executes this sub routine, passing the filter as only parameter. If the sub routine returns a true value, the rest of the filter is skipped.

skip_if_relayclient

When set to a true value, the "run" method will skip the filter when the environment variable RELAYCLIENT exists.

skip_for_sender

Takes an e-mail address or a reference to a list of such. The "run" method will then skip the filter if the RFC5321.MailFrom address of the "message" is one of these.

skip_for_from

Takes an e-mail address or a reference to a list of such. The "run" method will then skip the filter if the RFC5322.From address of the "message" is one of these.

skip_for_rcpt

Takes an e-mail address or a reference to a list of such. The "run" method will then skip the filter if at least one of the recipients in the envelope of the "message" is one of these.

defer_only

When set to a true value, calls to the "reject" method will result in status code 451, that is, the message should only be deferred on the sender side.

METHODS

add_filters

Configure the filters you want to use. Takes a list of filter packages to run in order.

You may pass instances of filter objects here, but usually it is more convenient to specify filters using their package name, optionally followed by a hash of options. add_filters will then construct the filter object for you. If your filter lives below the Mail::Qmail::Filter:: namespace, you may abbreviate this prefix with ::. Please see example in the "SYNOPSIS" above.

add_filters may be called several times to add more and more filters, but you can also just specify them all in one call.

add_filters will return the main Mail::Qmail::Filter object, so you may chain other methods, like "run".

run

checks if the filter should be skipped by evaluating the "OPTIONS COMMON TO ALL FILTERS". If not, runs it by calling its "filter" method.

filter

Does the actual work: Reads the message from qmail-smtpd, runs the filters which where added and if has not been "reject"ed, forwards the message to qmail-queue.

When "WRITING YOUR OWN FILTERS", overwrite this method with what your filter is supposed to do.

message

returns the MailX::Qmail::Queue::Message to be filtered

reject

rejects the message with status 554 (default) or with 451 when "defer_only" is set. Stops the execution of the script; no further filters will be run, and the message will not be passed on to qmail-queue.

As first argument, expects the reply text the server should send to the client or a subroutine which returns this reply text. Additional arguments will be passed to this subroutine, which is handy if you for example want to include an e-mail address which caused the rejection.

Please note that you should only use ASCII characters for the reply text and that qmail-smtpd usually limits its length to 254 characters.

defer

defers the message with status 451, just like "reject" would when "defer_only" is set. Everything else that is said above about "reject" also applies to "defer".

debug

collects logging messages. When the script finishes, these will be automatically written to standard error, separated with ; s. You should then find them in the log file of your qmail-smtpd, prefixed with the name of your frontend script.

When passing several arguments, these will be joined with : .

WRITING YOUR OWN FILTERS

For the "COMMON OPTIONS FOR ALL FILTERS" to work properly, your package has to:

use Mo 'coerce';
extends 'Mail::Qmail::Filter';

Apart from that, you only have to define a filter method which does the actual work.

For further insight, please have a look at the source code of the various "FILTERS INCLUDED" in this distribution.

SEE ALSO

MailX::Qmail::Queue::Message and the "FILTERS INCLUDED".

LICENSE AND COPYRIGHT

Copyright 2019 Martin Sluka.

This module is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.