NAME

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 <dianne@skollsoft.com>

LICENSE

This code is licensed under the terms of the GNU General Public License, version 2.