Yes, there is little info in the docs -- and I have to maintain that MailTools code :-( -- Anyway, after playing around with it, I decided that the structure chosen is not sufficient for the current complex messages. Have you thought of multi-level multiparts? Anyway: there came MailBox

Example to show that it works easy (although installation has too many dependencies, I know):

 use File::Temp;
 my $dir = tempdir; mkdir $dir or die;
 
 use Mail::Message;
 my $msg = Mail::Message->read(\*STDIN);
 foreach my $part ($msg->parts('RECURSE'))
 {  next if $part->isBinary;
    my $fn  = $message->body->dispositionFilename($dir);

    $message->decoded->write(filename => $fn)
        or die "Couldn't write to $fn: $!\n";
 }

See Mail::Box in HTML. Have a look at rebuild(), which may be able to do for you what you had planned. Just an alternative to MIME::* and MailTools to keep in mind.