Mailmunge::Action::Stream - stream mail by domain or recipient
NAME ABSTRACT SYNOPSIS METHODS Mailmunge::Action::Stream−>new($filter) stream_by_domain($ctx) stream_by_recipient($ctx) stream_recipients($ctx, $groups) STREAMING MECHANISM AUTHOR LICENSENAME
Mailmunge::Action::Stream − stream mail by domain or recipient
ABSTRACT
This class implements methods that let you "stream" mail. This lets you apply different filtering rules per−recipient or per−domain.
SYNOPSIS
package
MyFilter;
use base qw(Mailmunge::Filter);
use Mailmunge::Action::Stream;
sub filter_message {
my ($self, $ctx) = @_;
my $action = Mailmunge::Action::Stream−>new($self);
if ($action−>stream_by_domain($ctx)) {
$self−>action_discard($ctx);
return;
}
# Now all recipients are guaranteed to be in the same domain
}
my $filter = MyFilter−>new();
$filter−>run();
1;
METHODS
Mailmunge::Action::Stream−>new($filter)
Constructor. Typically used within a filter file as follows:
my $action = Mailmunge::Action::Stream−>new($self);
stream_by_domain($ctx)
If all recipients are in the same domain, returns 0. Otherwise, remails copies of the message with each copy going to a group of recipients in the same domain, and returns 1.
You typically want to discard the original message and skip the rest of your filter processing if "stream_by_domain" returns 1; the usual idiom is:
if
($action−>stream_by_domain($ctx)) {
$self−>action_discard($ctx);
return;
}
The remailed messages will be filtered in a subsequent set of milter calls.
Returns undef if something went wrong.
stream_by_recipient($ctx)
If there is only one recipient, returns 0. Otherwise, remails copies of the message with each copy going to a single recipient.
As with "stream_by_domain", you typically want to discard the original message and skip the rest of your filter processing if "stream_by_recipient" returns 1.
Returns undef if something went wrong.
stream_recipients($ctx, $groups)
This is the most general streaming function. $groups is an arrayref; each element must be an arrayref of recipients. Each recipient in "$ctx−>recipients" must appear in exactly one member of $groups and no additional recipients may appear.
If $groups has only one element, this function does nothing and returns 0. Otherwise, it emails one copy of the message to each group of recipients in $groups and returns 1.
Returns undef if something went wrong.
STREAMING MECHANISM
When Mailmunge streams a message, it remails copies of it so the copies can be re−scanned.
If your MTA is Sendmail, the copies are put in the Sendmail submission queue and they appear in a subsequent set of filter callbacks in an SMTP session originating from the localhost.
If your MTA is Postfix, the copies are re−injected, but are not sent via SMTP. Instead, Postfix simulates an SMTP session. If you want to stream messages and are using Postfix, you must set the "non_smtpd_milters" Postfix configuration variable to match "smtpd_milters". Otherwise, streamed messages will not be filtered!
When "Mailmunge::Action::Stream" remails a message, it adds a header of the form:
X−Mailmunge−Remailed: original_ip original_qid
where "original_ip" is the value of "$ctx−>hostip" and "original_qid" is "$ctx−>qid" when the streaming function is invoked.
"Mailmunge::Filter" looks for this header. If the connecting IP is the local host, the filter trusts the header and sets "$ctx−>hostip" and "$ctx−>hostname" based on "original_ip" from the header. It also logs a message:
Resent from queue−ID: original_qid; original IP: original_ip
so the streamed messages can be correlated with the original message.
If the connecting host is not the localhost, then "Mailmunge::Filter" ignores the X−Mailmunge−Remailed header. Regardless of where a message origintates, "Mailmunge::Filter" deletes all X−Mailmunge−Remailed headers so they don't show up downstream.
AUTHOR
Dianne Skoll <[email protected]>
LICENSE
This code is licensed under the terms of the GNU General Public License, version 2.