Mail::Qmail::Filter - filter e-mails in qmail-queue context
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;
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:
Write a frontend script to configure your filters, like the one in the "SYNOPSIS".
In the run file for your qmail-smtpd instance, e.g. /var/qmail/supervise/qmail-smtpd/run,
qmail-smtpd
/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)
This distribution ships with the following predefined filters:
check deliverability according to .qmail files
validate message against DMARC policy of the sender domain
only allow certain RFC322.From addresses
spam-check message
validate RFC5322.From
validate RFC5321.MailFrom
When set to a true calue, the "run" method will skip the filter when the environment variable RELAYCLIENT exists.
RELAYCLIENT
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.
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.
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.
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.
451
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
Mail::Qmail::Filter::
::
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".
checks if the filter should be skipped by evaluating the "OPTIONS COMMON TO ALL FILTERS". If not, runs it by calling its "filter" method.
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.
qmail-queue
When "WRITING YOUR OWN FILTERS", overwrite this method with what your filter is supposed to do.
returns the MailX::Qmail::Queue::Message to be filtered
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.
554
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.
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 : .
:
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.
MailX::Qmail::Queue::Message and the "FILTERS INCLUDED".
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.
To install Mail::Qmail::Filter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mail::Qmail::Filter
CPAN shell
perl -MCPAN -e shell install Mail::Qmail::Filter
For more information on module installation, please visit the detailed CPAN module installation guide.