Mail::M...Complete(3)

📦
version 4.04 · 11 versions
, in fedora 44

🎀 NAME 🎀

Mail::Message::Head::Complete — it's the header of one message. That's the whole vibe. One message, one header, fully known. 💌

(also hi bestie, you're in section 3 of the User Contributed Perl Documentation, and this page is literally titled Mail::Message::Head::Complete(3) — welcome to the group chat 🫶)

🦋 INHERITANCE 🦋

okay so the family tree here is giving royal lineage, let's unpack it:

  • Mail::Message::Head::Complete is a Mail::Message::Head
  • Mail::Message::Head::Complete is a Mail::Reporter
  • Mail::Message::Head::Complete is extended by Mail::Message::Head::Partial
  • Mail::Message::Head::Complete is extended by Mail::Message::Replace::MailHeader
  • Mail::Message::Head::Complete is realized by Mail::Message::Head::Delayed
  • Mail::Message::Head::Complete is realized by Mail::Message::Head::Subset

✨ SYNOPSIS ✨

  my $head = Mail::Message::Head::Complete->new;
  See Mail::Message::Head

💜 DESCRIPTION 💜

so message headers can be in a bunch of different states, right? unread, partially read, and fully read. This class right here? It's the glow-up final form: a header where all the fields are known for sure. The complete set. No mystery, no crumbs, no "hmm was there a Bcc". 💅

Extends "DESCRIPTION" in Mail::Message::Head.

🌈 OVERLOADED 🌈

Extends "OVERLOADED" in Mail::Message::Head.

  • overload: "" stringification — inherited, see "OVERLOADED" in Mail::Message::Head
  • overload: bool true/false — inherited, see "OVERLOADED" in Mail::Message::Head

🔥 METHODS 🔥

Extends "METHODS" in Mail::Message::Head.

🌸 Constructors 🌸

Extends "Constructors" in Mail::Message::Head.

  • $class->build( [PAIR|$field], ... ) — undefined values get interpreted as empty field values, and therefore get skipped entirely (not the vibe, bye 👋). Improves the base class, see "Constructors" in Mail::Message::Head.
  • $obj->clone( [@names|ARRAY|Regexps] ) — makes a copy of the header, optionally limited to only the header lines you name with @names. Wanna know how those field names can be used? See grepNames().
example:
  my $newhead = $head->clone('Subject', 'Received');
  • $class->new(%options) — inherited, see "Constructors" in Mail::Message::Head.

🎀 Attributes 🎀

Extends "Attributes" in Mail::Message::Head.

🧚 The header 🧚

Extends "The header" in Mail::Message::Head.

  • $obj->isDelayed() — inherited, see "The header" in Mail::Message::Head
  • $obj->isEmpty() — inherited, see "The header" in Mail::Message::Head
  • $obj->isModified() — inherited, see "The header" in Mail::Message::Head
  • $obj->knownNames() — inherited, see "The header" in Mail::Message::Head
  • $obj->message( [$message] ) — inherited, see "The header" in Mail::Message::Head
  • $obj->modified( [BOOLEAN] ) — inherited, see "The header" in Mail::Message::Head
  • $obj->nrLines() — returns the number of lines needed to display this header (and yes, that includes the trailing newline, we count everything in this house 🫶)
  • $obj->orderedFields() — inherited, see "The header" in Mail::Message::Head
  • $obj->size() — returns the number of bytes needed to display this header (trailing newline included, obviously). heads up tho: on systems which use CRLF as line separator, you have to add the number of lines in the header (see nrLines()) to find the actual size in the file.
  • $obj->wrap($integer) — re-folds all the fields in the header so they contain at most $integer number of characters per line. Glow-up for line lengths, periodt.
example: re-folding a header
  $msg->head->wrap(78);

💖 Access to the header 💖

Extends "Access to the header" in Mail::Message::Head.

  • $obj->add( $field | $line | <$name, $body, [$attrs]> ) — adds a field to the header. And bestie, if a field gets added more than once, all the values are stored in the header, in the order they were added. No deduping, no drama.

When you specify a $field object (some Mail::Message::Field instance), that's what gets added. Another option: hand over a raw header $line, or a header line all nicely split up into $name and $body, and the field constructor gets called for you. 🪄

Now listen: $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 get folded when needed — new-lines will be added wherever required. It is strongly advised to let MailBox do the folding for you. (not you folding it manually, we don't do that here 🙈)

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

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');
  • $obj->addListGroup($object) — a list group is a set of header fields which contain data about a mailing list which was used to transmit the message. See Mail::Message::Head::ListGroup for details about how the $object is implemented.

Once you've got a list group all prepared, you can add it later with this method. And you get your own private copy of the list group data back in return, because the same group can be used for multiple messages. sharing is caring but copies are safer 💅

example: of adding a list group to a header
  my $lg = Mail::Message::Head::ListGroup->new(...);
  my $own_lg = $msg->head->addListGroup($lg);
  • $obj->addResentGroup($resent_group|$data) — adds a $resent_group (a Mail::Message::Head::ResentGroup object) to the header. If you specify $data, that's used to create such a group first. And if no "Received" line is specified, it will be created for you. no notes, it just does it ✨

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. different thing entirely, don't get it twisted.

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

  my $rg = $head->addResentGroup(From => 'me');
  • $obj->addSpamGroup($object) — a spam fighting group is a set of header fields which contains data used to fight spam. See Mail::Message::Head::SpamGroup for details about how the $object is implemented.

When you've got a spam group prepared, you can add it later using this method. You get your private copy of the spam group data in return, because the same group can be used for multiple messages. (same deal as the list group, we love a consistent queen 👑)

example: of adding a spam group to a header
  my $sg = Mail::Message::Head::SpamGroup->new(...);
  my $own_sg = $msg->head->addSpamGroup($sg);
  • $obj->count($name) — counts the number of fields with this $name. Most fields will return 1, because there's only one occurrence in the header. But as an example, "Received" fields are usually present more than once. it's giving overachiever 📬
  • $obj->delete($name) — removes the field with the specified name. If the header contained multiple lines with the same name, they will all be replaced together. This method simply calls reset() without replacement fields. READ THE IMPORTANT WARNING IN removeField() — fr fr, go read it.
  • $obj->get( $name, [$index] ) — inherited, see "Access to the header" in Mail::Message::Head
  • $obj->grepNames( [@names|ARRAY|Regexps] ) — filters from all header fields those with names which start with any of the specified list. When no names are specified, all fields get returned. The list is ordered as they were read from file, or added later.

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
  • $obj->listGroup() — returns a list group description: the set of headers which form the information about mailing list software used to transport the message. See also addListGroup() and removeListGroup().
example: use of listGroup()
  if(my $lg = $msg->head->listGroup)
  {  $lg->print(\*STDERR);
     $lg->delete;
  }

  $msg->head->removeListGroup;
  • $obj->names() — returns a full ordered list of known field names, as defined in the header. And yes, fields which were reset() to be empty will still be listed here. they're still in the group chat, just muted 💀
  • $obj->print( [$fh] ) — prints all headers to the specified $fh, by default the selected filehandle. See printUndisclosed() to limit the headers to include only the public headers.
example:
  $head->print(\*OUT);
  $head->print;         # to selected file

  open my ($fh), '>:raw', $filename;
  $head->print($fh);
  • $obj->printSelected($fh, <STRING|Regexp>, ...) — like the usual print(), the header lines are printed to the specified $fh. In this case, however, only the fields with names as specified by "STRING" (case insensitive) or Regexp are printed. They will stay in the in-order of the source header. 🌈
example: printing only a subset of the fields
  $head->printSelected(STDOUT, qw/Subject From To/, qr/^x\-(spam|xyz)\-/i)
  • $obj->printUndisclosed( [$fh] ) — like the usual print(), the header lines are printed to the specified $fh, by default the selected filehandle. In this case, however, "Bcc" and "Resent-Bcc" lines are included. 👀 yes, those ones.
  • $obj->removeContentInfo() — removes all body related fields from the header. The header will become partial. bye bye body info 🫡
  • $obj->removeField($field) — removes the specified $field object from the header. This is useful when there are possibly more than one fields with the same name, and you need to remove exactly one of them. Also have a look at delete(), reset(), and set().

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. one little 's', huge difference bestie.

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 ✨ plot twist ✨ — because of how ref-counting works, deleting a field while you're still holding a reference to the field object means the clean-up does not happen:

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 dodge that whole mess, do not catch the field object — only catch the field <em>content</em>. SAVE is every method that hands you back 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;

🧹 $obj->removeFields( <STRING|Regexp>, ... )

This one turns the header object into a Mail::Message::Head::Partial object that's had a whole set of fields removed. The full tea on the implications and the possibilities lives in Mail::Message::Head::Partial::removeFields(). 💅

🧹 $obj->removeFieldsExcept( <STRING|Regexp>, ... )

Same energy: the header object becomes a Mail::Message::Head::Partial object with a set of fields removed. Read all about the implications and the possibilities in Mail::Message::Head::Partial::removeFieldsExcept().

🗑️ $obj->removeListGroup()

Yeets every field related to mailing list administration, all at once. The header object becomes a Mail::Message::Head::Partial object. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeListGroup().

🗑️ $obj->removeResentGroups()

Removes all resent groups in one go. The header object becomes a Mail::Message::Head::Partial object. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeResentGroups().

🗑️ $obj->removeSpamGroups()

Deletes every field that various spam detection software tacked on, all at once. The header object becomes a Mail::Message::Head::Partial object. Read about the implications and the possibilities in Mail::Message::Head::Partial::removeSpamGroups().

🔁 $obj->resentGroups()

Hands you a list of Mail::Message::Head::ResentGroup objects, each one representing a single intermediate hop in the message's transmission journey, in the order they show up in the header: most recent one first. Peep addResentGroup() and removeResentGroups() too.

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

♻️ $obj->reset($name, @fields)

Swaps out the values in the header fields named by $name for the values you pass in the @fields list. One single name can map to multiple repeated fields, iykyk. READ THE IMPORTANT WARNING IN removeField() 😭

Removing fields that belong to one of the predefined field groups is not a smart idea, bestie. You're way better off removing those fields as a group, all together. For instance, the 'Received' lines are part of resent groups, 'X-Spam' is part 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 the methods that Mail::Message::Head::Partial provides.

If FIELDS is empty, the corresponding $name fields get removed. The location of the removed fields in the header order is remembered, and fields with the same name added later will pop up at that remembered position. This is the same thing as 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;

✍️ $obj->set( $field | $line | <$name, $body, [$attrs]> )

The set method is basically add()'s twin and takes the same options. However, existing values for fields get removed before a new value is added. READ THE IMPORTANT WARNING IN removeField() 💀

🚨 $obj->spamDetected()

Tells you whether one of the spam groups has a report about spam. If there are no header fields in the message related to spam-detection software, undef comes back. The spamgroups that report spam are what get returned.

» example:

$message->delete if $message->spamDetected;

defined $message->spamDetected
   or call_spamassassin($message);

🕵️ $obj->spamGroups( [$names] )

Returns a list of Mail::Message::Head::SpamGroup objects, each one collecting some lines holding spam fighting info. If you pass any $names, then only those groups come back. See also addSpamGroup() and removeSpamGroups().

In scalar context, with exactly one NAME specified, that group is what you get. With more $names or with no $names at all, you get a list (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');

📜 $obj->string()

Returns the entire header as one scalar (in scalar context) or as a list of lines (list context). This triggers completion ✨

📚 $obj->study( $name, [$index] )

Inherited, see "Access to the header" in Mail::Message::Head

🦋 About the body 🦋

Extends "About the body" in Mail::Message::Head.

📏 $obj->guessBodySize()

Inherited, see "About the body" in Mail::Message::Head

🕰️ $obj->guessTimeStamp()

Makes a lil guess about when the message was originally posted, based on the info it finds in the header's Date field.

For some kinds of folders, Mail::Message::guessTimestamp() might give you a better result — for instance by peeking at the modification time of the file where the message is stored. Some protocols, like POP, can supply that info too. 💫

🧩 $obj->isMultipart()

Inherited, see "About the body" in Mail::Message::Head

📬 $obj->recvstamp()

Gives you an indication of when the message was <em>sent</em>, but only using the Date field in the header as a last resort — because we do not trust the sender of the message to specify the correct date, periodt. Check timestamp() when you do trust the sender.

So many spam producers fake a date, which absolutely wrecks the order of receiving things. The timestamp that comes out is derived from the Received headers if they're present, and undef otherwise.

The timestamp is encoded the way time is on your system (see perldoc -f time), which makes it 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;

⏰ $obj->timestamp()

Gives you an indication of when the message was sent, with as little guessing as possible. In this case, the date as specified by the sender is trusted. Check recvstamp() when you do not want to trust the sender.

The timestamp is encoded the way time is on your system (see perldoc -f time), which makes it usable for the gmtime and localtime methods.

🔧 Internals 🔧

Extends "Internals" in Mail::Message::Head.

🧱 $obj->addNoRealize($field)

Inherited, see "Internals" in Mail::Message::Head

📥 $obj->addOrderedFields($fields)

Inherited, see "Internals" in Mail::Message::Head

✂️ $obj->createFromLine()

Some mail-folder types separate messages with a line that starts with "From ". If a message gets moved into such a folder from a folder-type that doesn't support these separators, this method is called to produce one.

🆔 $obj->createMessageId()

Creates a message-id for this message. This method runs when a new message is created, or when a message is discovered without the message-id header field. Message-ids are required for detecting message-threads, no cap. See messageIdPrefix().

📂 $obj->fileLocation()

Inherited, see "Internals" in Mail::Message::Head

📖 $obj->load()

Inherited, see "Internals" in Mail::Message::Head

🏷️ $any->messageIdPrefix( [$prefix, [$hostname]|CODE] )

When you hand it options, it sets a brand-new way to create message-ids, as used by createMessageId(). You've got two choices: either give a $prefix and optionally a $hostname, or hand over a CODE reference.

The CODE reference gets called with the header as its first argument. You have to make sure yourself that the returned value is RFC compliant. 👑

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

Either way, a subroutine gets created to be used, and a reference to it is what comes back. When the method is called without arguments, but no subroutine is defined yet, one gets 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);

🚚 $obj->moveLocation($distance)

Inherited, see "Internals" in Mail::Message::Head

  • $obj->read($parser) — inherited bestie, so go read "Internals" in Mail::Message::Head for the tea 💖
  • $obj->setNoRealize($field) — also inherited, same deal, "Internals" in Mail::Message::Head has the details 🫶

😭 Error handling 😭

It extends "Error handling" in Mail::Message::Head, so like, there's more where this came from.

  • $obj->AUTOLOAD() — inherited, see "Error handling" in Mail::Reporter 💅
  • $obj->notImplemented() — inherited, see "Error handling" in Mail::Reporter ✨

🧹 Cleanup 🧹

Extends "Cleanup" in Mail::Message::Head. Yeah it's giving responsible adult energy.

  • $obj->DESTROY() — inherited, see "Cleanup" in Mail::Reporter 💀

🔍 DETAILS 🔍

Extends "DETAILS" in Mail::Message::Head. That's the whole vibe, no notes 💜

🚨 DIAGNOSTICS 🚨

Warning: cannot remove field $name from header: not found.

You tried to remove a field that this header literally does not have, bestie. But here's the thing — if you use delete(), reset(), or set() to do the job, you will not get a warning, because those methods check whether the field exists first. So it's only this path that yells at you. Cast by removeField() 🫠

Error: class $package does not implement method $method.

Fatal, no coming back from this one 😭 The specific $package (or one of its superclasses) just does not implement this method where it's supposed to. Which means... some other related classes do implement it, but the class in your hands simply does not. So yeah, you should probably go investigate that, and honestly probably tell the author of the package about it too. Cast by notImplemented() 💀

Warning: field objects have an implied name ($name)

Cast by build() ✨

👀 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 the 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. Periodt 💅

And that's a wrap on part 3, bestie 🎀 This page was served up by perl v5.42.0, dated 2026-02-05, and it lives under the name Mail::M...Complete(3). Go forth and slay your headers 👑✨💖

📦 where this page comes from