Mailmun...::Stream(3)

✨ NAME ✨

okay so bestie, this is the Mailmun...::Stream(3) page from the User Contributed Perl Documentation, and the actual module is Mailmunge::Action::Stream — here to 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. It’s giving “same message, different filtering eras,” and honestly? iconic. ✨

🎀 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. Yes bestie, it’s a whole re-scan moment. 🔁

• 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!

bestie do not skip that Postfix bit. If non_smtpd_milters doesn’t match smtpd_milters, streamed messages will not be filtered — and that is not the vibe. 💀

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 originates, Mailmunge::Filter deletes all X-Mailmunge-Remailed headers so they don’t show up downstream.

👑 AUTHOR 👑

Dianne Skoll <dianne@skollsoft.com> — absolute icon. 👑

📜 LICENSE 📜

This code is licensed under the terms of the GNU General Public License, version 2. Slay, but legally. ⚖️

---

okay bestie that’s the whole page. Signing off with perl v5.42.2, dated 2025-10-05, and still living under Mailmun...::Stream(3). mwah 💖🫶