Mail::...Handler(3pm)

🌸 Mail::...Handler(3pm) 🌸

okay bestie, welcome to the User Contributed Perl Documentation corner of the universe, where today's main character is Mail::SpamAssassin::Handler — yes the whole thing, the (3pm) and all. sit down, hydrate, let's get into it 🫶

✨ NAME ✨

Mail::SpamAssassin::Handler — the superclass for MIME-part handlers. like, the parent class. the blueprint. the mother of all part-handlers 💅

✨ SYNOPSIS ✨

package MyHandler;
use Mail::SpamAssassin::Handler;
our @ISA = qw(Mail::SpamAssassin::Handler);

sub new {
  my ($class, $mailsaobject) = @_;
  $class = ref($class) || $class;
  my $self = $class->SUPER::new($mailsaobject);
  bless ($self, $class);
  $self->register_handler('image/jpeg', 'handle_jpeg');
  return $self;
}

sub handle_jpeg {
  my ($self, $node, $permsgstatus) = @_;
  # ... analyse the part, optionally return synthetic child parts ...
  return [];
}

that's the whole vibe right there, no cap 👑

✨ DESCRIPTION ✨

so a handler is a plugin that processes individual MIME parts. it signs itself up for one or more content types using register_handler, and then it gets invoked once per matching part while the message metadata is being extracted. one part, one call. respectful. punctual. we love that for it 🎀

Mail::SpamAssassin::Handler is a thin subclass of Mail::SpamAssassin::Plugin. handlers get loaded, configured and dispatched through exactly the same machinery as plugins do — same pipeline, same drama. but inheriting from this class instead of from Mail::SpamAssassin::Plugin gives handlers a distinct identity (so you can tell them apart with $obj->isa('Mail::SpamAssassin::Handler')) plus a place for handler-specific behaviour to live in the future. it's giving "your own locker in the hallway" energy 🔥

handlers get loaded with the loadhandler / tryhandler configuration directives, and you can make a whole block of configuration conditional on a handler using ifhandler. yes. conditional config. iconic behaviour honestly ✨

everything in Mail::SpamAssassin::Plugin is available to handlers too — the whole inheritance bag, no gatekeeping. the only thing added here is the one handler-specific method below 👇

🦋 $handler->register_handler ($mime_pattern, $nameofsub) 🦋

registers one of this handler's methods as the MIME-part handler for a content-type pattern.

• $mime_pattern is either an exact type (image/jpeg) or a major-type glob (image/*). and here's the rule: the most specific match wins. so no fighting in the group chat, the algorithm already decided 🫶
• $nameofsub is the name of a method on this handler. it'll get called as $handler->$nameofsub($node, $permsgstatus) for every matching MIME part, during message metadata extraction — which is before body rules run and before the URI list is frozen. timing matters, bestie ⏰

so what can that method actually do? glad you asked:

• it can inject extracted text into the part with $node->set_rendered($text, $type) 💖
• it can accumulate per-message findings over on $permsgstatus 🌸
• and it can return an arrayref of synthetic child-part specs — { type => ..., data => $bytes, name => ... } — which get dispatched recursively 👑

or, if it has nothing to hand over, it returns undef or [] for none. that's it. that's the whole method. slay.

✨ SEE ALSO ✨

• Mail::SpamAssassin::Plugin — the parent, the blueprint, the og 💜

okay and that's the page, bestie!! this one was written by the very mysterious and humble perl v5.40.1 on 2026-07-23, and it's signed off with every bit of Mail::...Handler(3pm) energy it deserved 🎀✨ bye, go write a handler, i believe in you 💖