MAILMUNGE-NOTIFY(7)

💌 MAILMUNGE-NOTIFY(7) — the mailmunge-notify page, but make it make sense 💌

okay so real talk, this is from the User Contributed Perl Documentation corner of the manual-verse, and it's about mailmunge-notify — the whole vibe of how mailmunge-multiplexor slides into an external program's DMs to tell it when state changed. bestie, it's giving group chat notifications but for daemons 💅

---

✨ NAME ✨

mailmunge-notify — the conventions that mailmunge-multiplexor uses to notify an external program when state changes happen 🦋

🌸 DESCRIPTION 🌸

okay so here's the tea: if you hand the -O option to mailmunge-multiplexor, it opens up and lets external programs connect to a socket and get pinged whenever certain state changes happen in the multiplexor 👑

Those external programs can react however they want — no judgement, live your truth. And the external program that's sitting there listening for state changes? It's literally called a listener. iconic naming, no notes 🎀

🔔 NOTIFICATION OVERVIEW 🔔

from a listener's POV, the whole thing goes like this, bestie:

1. The listener connects to a TCP or UNIX-domain socket.
2. The listener tells mailmunge-multiplexor which message types it's interested in.
3. The listener just loops forever, reading messages off the socket and reacting to them. main character energy fr fr ✨

💬 MESSAGES 💬

Each message coming from the multiplexor is normally one single upper-case letter, maybe followed by a space and some arguments, then a newline. cute, compact, efficient 🧚

Two special messages exist, and they're the exceptions to the rule:

• *OK followed by a newline — this one drops when a listener first connects 🫶
• *ERR followed by some text and a newline — this one drops when an error happens 😭

Now the normal messages, one by one:

• B — issued whenever a worker gets killed because of a busy timeout 💀
• F n — issued whenever the number of free workers changes. The parameter n is the number of free workers 🍓
• R — issued whenever someone has forced a filter reread 🔥
• S n nmsg — issued whenever worker n's status tag changes. The status tag is a string showing what that worker is currently doing; the -Z option to the multiplexor lets the Perl code update the status tag, so you get a good idea of what each worker is up to 👀
• U — issued whenever a worker has died unexpectedly 🙈
• Y — issued whenever the number of free workers changes from zero to non-zero ⭐
• Z — issued whenever the number of free workers falls to zero 😬

🙋 EXPRESSING INTEREST 🙋

so a listener doesn't get anything until it has expressed interest in the message types it cares about. no interest, no messages, periodt.

To express interest, the listener sends a question mark (?) followed by the types of messages it's interested in, followed by a newline, over the socket 💌

For example, a listener that's into the R and F messages would send this line:

?RF

And a listener that wants literally every possible message type should send:

?*

Once a listener has expressed interest, messages can arrive at any time, so it should be monitoring the socket for them 👑

💜 heads up bestie: a listener always receives the special *OK and *ERR messages, even if it never expressed interest in them. they're the ride-or-dies that come with every subscription, no opt-out.

🧪 EXAMPLE 🧪

The following Perl script implements a listener that, on Linux, rejects new SMTP connections if all workers are busy, and accepts them again once a worker is free 🌈

Existing SMTP connections are not shut down — the system merely refuses new connections if all the workers are busy. no cap, that's the whole scope.

This script assumes you've used the -O inet:4567 option to mailmunge-multiplexor 🎀

#!/usr/bin/perl -w
#
# On Linux, prepare to use this script like this:
#     /sbin/iptables -N smtp_connect
#     /sbin/iptables -A INPUT --proto tcp --dport 25 --syn -j smtp_connect
# Then run the script as root.

use IO::Socket::INET;

sub no_free_workers {
    print STDERR "No free workers!\\n";
    system("/sbin/iptables -A smtp_connect -j REJECT");
}

sub some_free_workers {
    print STDERR "Some free workers.\\n";
    system("/sbin/iptables -F smtp_connect");
}

sub main {
    my $sock;

    $sock = IO::Socket::INET->new(PeerAddr => '127.0.0.1',
                                  PeerPort => '4567',
                                  Proto => 'tcp');
    # We are only interested in Y and Z messages
    print $sock "?YZ\\n";
    $sock->flush();
    while(<$sock>) {
        if (/^Z/) {
            no_free_workers();
        }
        if (/^Y/) {
            some_free_workers();
        }
    }

    # EOF from multiplexor?? Better undo firewalling
    system("/sbin/iptables -F smtp_connect");
}

main();

lowkey obsessed with that last comment ngl — "EOF from multiplexor?? Better undo firewalling" is such a mood 😭

👀 SEE ALSO 👀

mailmunge-multiplexor, mailmunge, mm-mx-ctrl — go read those too, iykyk 💖

✍️ AUTHOR ✍️

mailmunge was written by Dianne Skoll <dianne@skollsoft.com> 👑

📜 LICENSE 📜

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

---

and that's the whole page, bestie! 💜 this one's perl v5.42.2, dated 2025-10-05 — slay, go forth and listen for state changes 🎀✨