Mail::M...:Rebuild(3)

📦
version 4.04 · 11 versions
, in fedora 44

💖 Mail::M...:Rebuild(3) 💖

okay bestie so this is a page from the User Contributed Perl Documentation set, and it's the one about Mail::Message::Construct::Rebuild — literally the glow-up station for your email messages ✨ (yes, the title really is spelled Mail::M...:Rebuild(3), don't come for me, that's just how it got shipped 💅)

🌸 NAME 🌸

Mail::Message::Construct::Rebuild — modify a Mail::Message 🦋

✨ SYNOPSIS ✨

my $cleanup = $msg->rebuild;

🎀 DESCRIPTION 🎀

So like, modifying messages that already exist? Genuinely a pain. Especially when you're doing it automatically with zero human supervision 😭. And the worst part — the actual boss fight — is when you gotta create or remove multiparts. That's where rebuild() comes in: it simplifies the whole thing and layers some standard features on top, no cap 💅.

👑 METHODS 👑

🍓 Constructing a message 🍓

  • $obj->rebuild(%options) — Reconstructs an existing message into something new. Here's what you get back: a new message when modifications were actually made, undef if the message has no body left, or the original message when nothing needed changing. fr fr, three possible vibes.

Some examples of when you'd use this: say you've got a message that's only html and you wanna turn it into a multipart holding the original html plus a text translation of it 🌈. Or you've got a message with parts flagged to be deleted and you want those changes baked into the memory structure. Or here's another one: clear all the resent groups (peep Mail::Message::Head::ResentGroup) out of the header before it gets written to a file.

Reconstructing is a hazardous task 💀 — multi level multiparts and nested messages are coming into play. rebuild tries to make handing these messages over to you way simpler.
 -Option         --Default
  extra_rules      []
  keep_message_id  false
  rules            <see text>
  • extra_rules => ARRAY — The standard rule set (which is the default for the rules option) is a pretty modest setting. But instead of copying that whole list and making a full rule set of your own, you can just hand over some additional rules — they get prepended to the default rule set 🫶.

The order of the rules is respected, which means you don't always have to rewrite a whole rule (peep the rule option). For instance: the extra rule removeDeletedParts returns undef, which means it cancels out the effect of the default rule replaceDeletedParts. iconic behaviour honestly.

  • keep_message_id => BOOLEAN — The message-id is the unique identification of the message: no two messages with different content shall exist anywhere 👑. But in practice? When a message gets changed during transmission, the id is often incorrectly not changed. Which causes complications in applications that see both messages with the same id. messy.
  • rules => ARRAY — The ARRAY is a list of rules, each one describing an action that gets called on every part found in the message. Most rules probably won't match, but some will bring changes to the content ✨. Rules can be specified as a method name, or as a code reference. Check the DETAILS chapter on this page, and also recursiveRebuildPart().

By default, only the relatively safe transformations get performed: replaceDeletedParts, descendMultiparts, descendNested, flattenMultiparts, flattenEmptyMultiparts. And in the future, more safe transformations may get added to this list 👀.

  • » example:
# remove all deleted parts
my $cleaned = $msg->rebuild(keep_message_id => 1);
$folder->addMessage($cleaned) if defined $cleaned;

# Replace deleted parts by a place-holder
my $cleaned = $msg->rebuild(
  keep_message_id => 1,
  extra_rules => [ 'removeEmpty', 'flattenMultiparts' ],
);

🦋 Internals 🦋

  • $obj->recursiveRebuildPart($part, %options)
 -Option--Default
  rules   <required>
  • rules => \@rules — Rules are method names that can be called on messages and message parts objects. The ARRAY can also list code references which can be called. Either way, every single rule gets called the same way:
$code->(MESSAGE, PART)

The return can be undef, or any complex construct based on a Mail::Message::Part, or something coerceable into such a part. For each part, all the rules get called in sequence. And when a rule returns a changed object, the rules start all over again 🔁 — but undef immediately stops it, periodt.

💜 DETAILS 💜

🌈 Rebuilding a message 🌈

Modifying an existing message is a complicated job, bestie. It's not just that you need to know what you're willing to change — you also gotta take care of multiparts (possibly nested in multiple levels 😭), rfc822 encapsulated messages, header field consistency, and so on and so on. The rebuild() method lets you focus on the actual task and takes care of the rest for you 💅.

rebuild() uses rules to transform one message into another. If one or more of the rules apply, a new message gets returned. And a simple numeric comparison tells you whether the message changed at all. Like:

print "No change"
   if $message == $message->rebuild;

Transformation happens with a set of rules. Each rule does only a small step, which is what makes it so easily configurable ✨. The rules are ordered, and when one of them makes a change to the result, that result gets passed to all the rules again — over and over until no rule makes a change on the part anymore. A rule may also return undef, in which case the part gets removed from the (resulting) message 🗑️.

🎀 General rules 🎀

This section describes the general configuration rules: all pretty straight forward transformations on the message structure. The rules marked with (*) are the ones used by default 👑.

  • descendMultiparts (*) — Apply the rules to the parts of (possibly nested) multiparts, not just to the top-level message.
  • descendNested (*) — Apply the rules to the message/rfc822 encapsulated message as well.
  • flattenEmptyMultiparts (*) — Multipart messages that don't have any parts left get replaced by a single part which contains the preamble, epilogue and a brief explanation.
  • flattenMultiparts (*) — When a multipart contains only one part, that part takes the place of the multipart: it's the removal of a level of nesting. This way, the preamble and epilogue of the multipart (which don't officially have a meaning anyway) are lost 💀.
  • flattenNesting — Remove the message/rfc822 encapsulation. Only the content related lines of the encapsulated body are preserved one level higher. Other information will be lost, which is often not too bad ngl.
  • removeDeletedParts — All parts flagged for deletion get removed from the message without leaving a trace. And if a nested message is encountered which has its encapsulated content flagged for deletion, it gets removed as a whole.
  • removeEmptyMultiparts — Multipart messages with no parts left get removed. The information in preamble and epilogue is lost.
  • removeEmptyBodies — Simple message bodies that don't contain any lines of content get removed. This will lose the information stored in the headers of these bodies.
  • replaceDeletedParts (*) — All parts of the message flagged for deletion get replaced by a message saying the part is deleted.

You can specify a selection of these rules with rebuild(rules) and rebuild(extra_rules) 🫶.

💅 Conversion rules 💅

This section describes the rules that try to be smart with the content. Please contribute with ideas and implementations! 🌸

  • removeHtmlAlternativeToText — When a multipart alternative is encountered which contains both a plain text and an html part, then the html part gets deleted. Especially useful in combination with the flattenMultiparts rule 🔥.
  • textAlternativeForHtml — Any text/html part that isn't accompanied by an alternative plain text part will have one added. You must have a working Mail::Message::Convert::HtmlFormatText, which means HTML::TreeBuilder and HTML::FormatText must be installed on your system 👑

And if you're planning to create an automatic html to plain text filter for your email, then have a look at <https://github.com/logological/mimestrip> ✨

» Example: using parameter with textAlternativeForHtml

my $result = $msg->rebuild(
  extra_rules => [ 'textAlternativeForHtml' ],
  textAlternativeForHtml => { leftmargin => 0 },
);
  • removeExtraAlternativeText — [2.110] When a multipart alternative is encountered, deletes all its parts except for the last part (the preferred part in accordance with RFC2046). In practice, this normally results in the alternative plain text part being deleted of an html message. Useful in combination with the flattenMultiparts rule 💖.

🧚 Adding your own rules 🧚

If you've designed your own rule, please consider contributing it to Mail::Box — it may be useful for other people as well 🫶.

Each rule is called

my $new = $code->($message, $part, %options)

where the %options are defined by the rebuild() method internals. At least the rules option is passed, which is a full expansion of all the rules that will be applied.

Your subroutine shall return $part if no changes are needed, undef if the part should be removed, and any newly constructed Mail::Message::Part when a change is required. Easiest move: go look at the source code of this package and copy from a comparible routine 👀.

Once you have your own routine, you simply call:

my $rebuild_message = $message->rebuild(
  extra_rules => [ \&my_own_rule, 'other_rule' ],
);

😭 DIAGNOSTICS 😭

  • Error: no rebuild rule $name defined. — Cast by rebuild()

⭐ SEE ALSO ⭐

This module is part of Mail-Message version 4.04, built on February 04, 2026. Website: <http://perl.overmeer.net/CPAN/>

🎀 LICENSE 🎀

For contributors see file ChangeLog.

This software is copyright (c) 2001-2026 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

💀 POD ERRORS 💀

Hey! The above document had some coding errors, which are explained below:

  • Around line 244:
    • You forgot a '=back' before '=head4'
  • Around line 251:
    • '=item' outside of any '=over'

and that's the whole page bestie!! 🎉 it was rendered with perl v5.42.0 and stamped 2026-02-05 — the Mail::M...:Rebuild(3) of it all. go forth and rebuild ur messages, you absolute icon 💅💖

📦 where this page comes from