example:

 my $newhead = $head->clone('Subject', 'Received');
    

example: re-folding a header

 $msg->head->wrap(78);
    

When a $field object is specified (some Mail::Message::Field instance), that will be added. Another possibility is to specify a raw header $line, or a header line nicely split-up in $name and $body, in which case the field constructor is called for you.

$line or $body specifications which are terminated by a new-line are considered to be correctly folded. Lines which are not terminated by a new-line will be folded when needed: new-lines will be added where required. It is strongly advised to let MailBox do the folding for you.

The return value of this method is the Mail::Message::Field object which is created (or was specified).

example:

 my $head  = Mail::Message::Head->new;
 $head->add('Subject: hi!');
 $head->add(From => 'me@home');
 my $field = Mail::Message::Field->new('To: you@there');
 $head->add($field);
 my Mail::Message::Field $s = $head->add(Sender => 'I');
    

When you have a list group prepared, you can add it later using this method. You will get your private copy of the list group data in return, because the same group can be used for multiple messages.

example: of adding a list group to a header

 my $lg = Mail::Message::Head::ListGroup->new(...);
 my $own_lg = $msg->head->addListGroup($lg);
    

These header lines have nothing to do with the user's sense of "reply" or "forward" actions: these lines trace the e-mail transport mechanism.

example:

 my $rg = Mail::Message::Head::ResentGroup->new(head => $head, ...);
 $head->addResentGroup($rg);
 my $rg = $head->addResentGroup(From => 'me');
    

When you have a spam group prepared, you can add it later using this method. You will get your private copy of the spam group data in return, because the same group can be used for multiple messages.

example: of adding a spam group to a header

 my $sg = Mail::Message::Head::SpamGroup->new(...);
 my $own_sg = $msg->head->addSpamGroup($sg);
    

The @names are considered regular expressions, and will all be matched case insensitive and attached to the front of the string only. You may also specify one or more prepared regexes.

example:

 my @f  = $head->grepNames();       # same as $head->orderedFields
 my @f  = $head->grepNames('X-', 'Subject', ');
 my @to = $head->grepNames('To\b'); # will only select To
    

example: use of listGroup()

 if(my $lg = $msg->head->listGroup)
 {  $lg->print(\*STDERR);
    $lg->delete;
 }
 $msg->head->removeListGroup;
    

example:

 $head->print(\*OUT);
 $head->print;
 my $fh = IO::File->new(...);
 $head->print($fh);
    

example: printing only a subset of the fields

 $head->printSelected(STDOUT, qw/Subject From To/, qr/^x\-(spam|xyz)\-/i)
    

See also Mail::Message::Head::Partial::removeFields() (mind the 's' at the end of the name), which accepts a string or regular expression as argument to select the fields to be removed.

WARNING WARNING WARNING: for performance reasons, the header administration uses weak references (see Scalar::Util method weaken()> to figure-out which fields have been removed. A header is a hash of field for fast search and an array of weak references to remember the order of the fields, required for printing. If the field is removed from the hash, the weak-ref is set to undef and the field not printed.

However... it is easy to disturb this process. Example:
my $msg = ....; # subject ref-count = 1 + 0 = 1
$msg->head->delete('Subject'); # subject ref-count = 0 = 0: clean-up
$msg->print; # subject doesn't show: ok

But
my $msg = ....; # subject ref-count = 1 + 0 = 1
my $s = $msg->head->get('subject'); # ref-count = 1 + 1 + 0 = 2
$msg->head->delete('Subject'); # subject ref-count = 1 + 0 = 1: no clean-up
$msg->print; # subject DOES show: not ok
undef $s; # ref-count becomes 0: clean-up
$msg->print; # subject doesn't show: ok

To avoid the latter situation, do not catch the field object, but only the field content. SAVE are all methods which return the text:
my $s = $msg->head->get('subject')->body;
my $s = $msg->head->get('subject')->unfoldedBody;
my $s = $msg->head->get('subject')->foldedBody;
my $s = $msg->head->get('subject')->foldedBody;
my $s = $msg->get('subject');
my $s = $msg->subject;
my $s = $msg->string;

A resent group contains a set of header fields whose names start with "Resent-*". Before the first "Resent" line is trace information, which is composed of an optional "Return-Path" field and an required "Received" field.

Removing fields which are part of one of the predefined field groups is not a smart idea. You can better remove these fields as group, all together. For instance, the 'Received' lines are part of resent groups, 'X-Spam' is past of a spam group, and "List-Post" belongs to a list group. You can delete a whole group with Mail::Message::Head::FieldGroup::delete(), or with methods which are provided by Mail::Message::Head::Partial.

If FIELDS is empty, the corresponding $name fields will be removed. The location of removed fields in the header order will be remembered. Fields with the same name which are added later will appear at the remembered position. This is equivalent to the delete() method.

example:

 # reduce number of 'Keywords' lines to last 5)
 my @keywords = $head->get('Keywords');
 $head->reset('Keywords', @keywords[-5..-1]) if @keywords > 5;
 # Reduce the number of Received lines to only the last added one.
 my @rgs = $head->resentGroups;
 shift @rgs;     # keep this one (later is added in front)
 $_->delete foreach @rgs;
    

example:

 $message->delete if $message->spamDetected;
 call_spamassassin($message)
    unless defined $message->spamDetected;
    

In scalar context, with exactly one NAME specified, that group will be returned. With more $names or without $names, a list will be returned (which defaults to the length of the list in scalar context).

example: use of listGroup()

 my @sg = $msg->head->spamGroups;
 $sg[0]->print(\*STDERR);
 $sg[-1]->delete;
 my $sg = $msg->head->spamGroups('SpamAssassin');
    

For some kinds of folders, Mail::Message::guessTimestamp() may produce a better result, for instance by looking at the modification time of the file in which the message is stored. Also some protocols, like POP can supply that information.

Many spam producers fake a date, which mess up the order of receiving things. The timestamp which is produced is derived from the Received headers, if they are present, and "undef" otherwise.

The timestamp is encoded as "time" is on your system (see perldoc -f time), and as such usable for the "gmtime" and "localtime" methods.

example: of time-sorting folders with received messages

 my $folder = $mgr->open('InBox');
 my @messages = sort {$a->recvstamp <=> $b->recvstamp}
                   $folder->messages;
    

example: of time-sorting messages of mixed origin

 my $folder = $mgr->open('MyFolder');
 # Pre-calculate timestamps to be sorted (for speed)
 my @stamps = map { [ ($_->timestamp || 0), $_ ] }
                     $folder->messages;
 my @sorted
   = map { $_->[1] }      # get the message for the stamp
       sort {$a->[0] <=> $b->[0]}   # stamps are numerics
          @stamps;
    

The timestamp is encoded as "time" is on your system (see perldoc -f time), and as such usable for the "gmtime" and "localtime" methods.

The CODE reference will be called with the header as first argument. You must ensure yourself that the returned value is RFC compliant.

The $prefix defaults to "mailbox-$$", the $hostname defaults to the return of Net::Domains's function hostfqdn(), or when not installed, the Sys::Hostname's function hostname(). Inbetween the two, a nano-second time provided by Time::HiRes is used. If that module is not available, "time" is called at the start of the program, and incremented for each newly created id.

In any case, a subroutine will be created to be used. A reference to that will be returned. When the method is called without arguments, but no subroutine is defined yet, one will be created.

example: setting a message prefix

  $head->messageIdPrefix('prefix');
  Mail::Message::Head::Complete->messageIdPrefix('prefix');
  my $code = $head->messageIdPrefix('mailbox', 'nohost');
  sub new_msgid()
  {   my $head = shift;
      "myid-$$-${(rand 10000)}@example.com";
  }
  $many_msg->messageIdPrefix(\&new_msgid);
  Mail::Message::Head::Complete->messageIdPrefix(&new_msgid);