Mail::Message::Construct::Rebuild - modify a Mail::Message
my $cleanup = $msg->rebuild;
Modifying existing messages is a pain, certainly if this has to be done in an
automated fashion. The problems are especially had when multiparts have to be
created or removed. The rebuild()
method tries to simplify this task
and add some standard features.
- Reconstruct an existing message into something new. Returned is a new
message when there were modifications made, "undef" if the
message has no body left, or the original message when no modifications
had to be made.
Examples of use: you have a message which only contains html, and you want
to translate it into a multipart which contains the original html and the
textual translation of it. Or, you have a message with parts flagged to be
deleted, and you want those changes be incorparted in the memory
structure. Another possibility: clear all the resent groups (see
Mail::Message::Head::ResentGroup) from the header, before it is written to
Reconstructing is a hazardous task, where multi level multiparts and nested
messages come into play. The rebuild method tries to simplify handing
these messages for you.
rules <see text>
- extra_rules => ARRAY
- The standard set of rules, which is the default for the "rules"
option, is a moderest setting. In stead of copying that list into a full
set of rules of your own, you can also specify only some additional rules
which will be prependend to the default rule set.
The order of the rules is respected, which means that you do not always need
to rewrite the whole rule is (see "rule" option). For instance,
the extra rule of "removeDeletedParts" returns an
"undef", which means that it cancels the effect of the default
- keep_message_id => BOOLEAN
- The message-id is an unique identification of the message: no two messages
with different content shall exist anywhere. However in practice, when a
message is changed during transmission, the id is often incorrectly not
changed. This may lead to complications in application which see both
messages with the same id.
- rules => ARRAY
- The ARRAY is a list of rules, which each describe an action which will be
called on each part which is found in the message. Most rules probably
won't match, but some will bring changes to the content. Rules can be
specified as method name, or as code reference. See the
"DETAILS" chapter in this manual page, and
By default, only the relatively safe transformations are performed:
"flattenEmptyMultiparts". In the future, more safe
transformations may be added to this list.
# 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' ]
- $obj->recursiveRebuildPart($part, %options)
- rules => ARRAY-OF-RULES
- Rules are method names which can be called on messages and message parts
objects. The ARRAY can also list code references which can be called. In
any case, each rule will be called the same way:
The return can be "undef" or any complex construct based on a
Mail::Message::Part or coerceable into such a part. For each part, all
rules are called in sequence. When a rule returns a changed object, the
rules will start all over again, however "undef" will
immediately stop it.
Modifying an existing message is a complicated job. Not only do you need to know
what you are willing to change, but you have to take care about multiparts
(possibly nested in multiple levels), rfc822 encapsulated messages, header
field consistency, and so on. The rebuild()
method let you focus on the
task, and takes care of the rest.
method uses rules to transform the one message into an
other. If one or more of the rules apply, a new message will be returned. A
simple numeric comparison tells whether the message has changed. For example
print "No change"
if $message == $message->rebuild;
Transformation is made with a set of rules. Each rule performs only a small
step, which makes is easily configurable. The rules are ordered, and when one
makes a change to the result, the result will be passed to all the rules again
until no rule makes a change on the part anymore. A rule may also return
"undef" in which case the part will be removed from the (resulting)
This sections describes the general configuration rules: all quite straight
forward transformations on the message structure. The rules marked with (*)
are used by default.
- descendMultiparts (*)
Apply the rules to the parts of (possibly nested) multiparts, not only to
the top-level message.
- descendNested (*)
Apply the rules to the "message/rfc822" encapsulated message as
- flattenEmptyMultiparts (*)
Multipart messages which do not have any parts left are replaced by a single
part which contains the preamble, epilogue and a brief explanation.
- flattenMultiparts (*)
When a multipart contains only one part, that part will take the place of
the multipart: the removal of a level of nesting. This way, the preamble
and epilogue of the multipart (which do not have a meaning, officially)
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.
All parts which are flagged for deletion are removed from the message
without leaving a trace. If a nested message is encountered which has its
encapsulated content flagged for deletion, it will be removed as a
Multipart messages which do not have any parts left are removed. The
information in preamble and epiloge is lost.
Simple message bodies which do not contain any lines of content are removed.
This will loose the information which is stored in the headers of these
- replaceDeletedParts (*)
All parts of the message which are flagged for deletion are replace by a
message which says that the part is deleted.
You can specify a selection of these rules with rebuild(rules) and
This section describes the rules which try to be smart with the content. Please
contribute with ideas and implementations.
When a multipart alternative is encountered, which contains both a plain
text and an html part, then the html part is deleted. Especially useful in
combination with the "flattenMultiparts" rule.
Any "text/html" part which is not accompanied by an alternative
plain text part will have one added. You must have a working
Mail::Message::Convert::HtmlFormatText, which means that HTML::TreeBuilder
and HTML::FormatText must be installed on your system.
Adding your own rules
[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
If you have designed your own rule, please consider contributing this 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 which 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. It is easiest to
start looking at the source code of this package, and copy from a comparible
When you have your own routine, you simply call:
my $rebuild_message = $message->rebuild
( extra_rules => [ \&my_own_rule, 'other_rule' ] );
- Error: No rebuild rule $name defined.
This module is part of Mail-Message distribution version 3.007, built on
September 03, 2018. Website: http://perl.overmeer.net/CPAN/
Copyrights 2001-2018 by [Mark Overmeer <firstname.lastname@example.org>]. For other
contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself. See http://dev.perl.org/licenses/