Mail::M...ge::Head(3)

📦

version 4.04 · 11 versions

🎀 NAME 🎀

okay bestie, welcome to Mail::M...ge::Head(3) 💖 — that's the User Contributed Perl Documentation version, and this whole page is about the header of one message. Yeah. The top part. The receipts. 👑

🌈 INHERITANCE 🌈

Mail::Message::Head
  is a Mail::Reporter

Mail::Message::Head is extended by
  Mail::Box::IMAP4::Head
  Mail::Message::Head::Complete
  Mail::Message::Head::Delayed
  Mail::Message::Head::Subset

✨ SYNOPSIS ✨

my $head = Mail::Message::Head->new;
$head->add('From: me@localhost');
$head->add(From => 'me@localhost');
$head->add(Mail::Message::Field->new(From => 'me'));
my $subject = $head->get('subject');
my @rec = $head->get('received');
$head->delete('From');

💅 DESCRIPTION 💅

"Mail::Message::Head" MIME headers are part of Mail::Message messages, which are grouped in Mail::Box folders.

A long list of standard MIME header fields with definitions can be found in RFC4021 (https://www.rfc-editor.org/rfc/rfc4021.html) and its updates RFC5322 and RFC6854.

ATTENTION!!! most functionality about e-mail headers is described in Mail::Message::Head::Complete, which is a matured header object. Other kinds of headers will be translated to that type when time comes. 🕐

On this page, the general methods which are available on any header are described. Read about differences in the sub-class specific pages. iykyk 🫶

Extends "DESCRIPTION" in Mail::Reporter.

🦋 OVERLOADED 🦋

overload: "" stringifaction — the header, when used as a string, will format as if Mail::Message::Head::Complete::string() was called, so it returns a nicely folder full header ✨. An exception is made for Carp, which will get a simplified string to avoid unreadible messages from "croak" and "confess".

» example: using a header object as string

print $head;     # implicit stringification by print
$head->print;    # the same

print "$head";   # explicit stringication

overload: bool true/false — when the header does not contain any lines (which is illegal, according to the RFCs 😭), "false" is returned. In all other cases, a "true" value is produced. slay.

👑 METHODS 👑

Extends "METHODS" in Mail::Reporter.

🧚 Constructors 🧚

Extends "Constructors" in Mail::Reporter.

`$class->build( [PAIR|$field]-LIST )`

A fast way to construct a header with many lines. The PAIRs are (name, content) pairs of the header, but it is also possible to pass Mail::Message::Field objects. A Mail::Message::Head::Complete header is created by simply calling Mail::Message::Head::Complete::build(), and then each field is added. Double field names are permitted. 💖

» example:

my $subject = Mail::Message::Field->new(Subject => 'xyz');

my $head = Mail::Message::Head->build(
  From     => 'me@example.com',
  To       => 'you@anywhere.aq',
  $subject,
  Received => 'one',
  Received => 'two',
);

print ref $head;
 # -->  Mail::Message::Head::Complete

`$class->new(%options)`

Create a new message header object. The object will store all the fields of a header. When you get information from the header, it will be returned to you as Mail::Message::Field objects, although the fields may be stored differently internally. ✨

If you try to instantiate a Mail::Message::Head, you will automatically be upgraded to a Mail::Message::Head::Complete --a full head. Improves base, see "Constructors" in Mail::Reporter

 -Option    --Default
  field_type  Mail::Message::Field::Fast
  message     undef
  modified    false

field_type => CLASS — the type of objects that all the fields will have. This must be an extension of Mail::Message::Field. no cap.
message => $message — the $message where this header belongs to. Usually, this is not known at creation of the header, but sometimes it is. If not, call the message() method later to set it. 💌
modified => BOOLEAN — that's it, that's the whole line. 🙈

🌸 Attributes 🌸

Extends "Attributes" in Mail::Reporter.

🎀 The header 🎀

`$obj->isDelayed()`

Headers may only be partially read, in which case they are called delayed. This method returns "true" if some header information still needs to be read. Returns "false" if all header data has been read. Will never trigger completion. periodt. 💅

`$obj->isEmpty()`

Are there any fields defined in the current header? Be warned that the header will not be loaded for this: delayed headers will return "true" in any case. 😭

`$obj->isModified()`

Returns whether the header has been modified after being read.

» example:

if($head->isModified) { ... }

`$obj->knownNames()`

Like Mail::Message::Head::Complete::names(), but only returns the known header fields, which may be less than "names" for header types which are partial. names() will trigger completion, where knownNames() does not. 🫶

`$obj->message( [$message] )`

Get (after setting) the message where this header belongs to. This does not trigger completion.

`$obj->modified( [BOOLEAN] )`

Sets the modified flag to "BOOLEAN". Without value, the current setting is returned, but in that case you can better use isModified(). Changing this flag will not trigger header completion.

» example:

$head->modified(1);
if($head->modified) { ... }
if($head->isModified) { ... }

`$obj->orderedFields()`

Returns the fields ordered the way they were read or added. main character energy, honestly. 🌟

💜 Access to the header 💜

`$obj->get( $name, [$index] )`

Get the data which is related to the field with the $name. The case of the characters in $name does not matter. 🔥

If there is only one data element defined for the $name, or if there is an $index specified as the second argument, only the specified element will be returned. If the field $name matches more than one header the return value depends on the context. In LIST context, all values will be returned in the order they are read. In SCALAR context, only the last value will be returned.

» example:

my $head = Mail::Message::Head->new;
$head->add('Received: abc');
$head->add('Received: xyz');
$head->add('Subject: greetings');

my @rec_list   = $head->get('Received');
my $rec_scalar = $head->get('Received');
print ",@rec_list,$rec_scalar,"     # ,abc xyz, xyz,
print $head->get('Received', 0);    # abc
my @sub_list   = $head->get('Subject');
my $sub_scalar = $head->get('Subject');
print ",@sub_list,$sub_scalar,"     # ,greetings, greetings,

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

Like get(), but puts more effort in understanding the contents of the field. Mail::Message::Field::study() will be called for the field with the specified FIELDNAME, which returns Mail::Message::Field::Full objects. In scalar context only the last field with that name is returned. When an $index is specified, that element is returned. 🧠✨

🍓 About the body 🍓

`$obj->guessBodySize()`

Try to estimate the size of the body of this message, but without parsing the header or body. The result might be "undef" or a few percent of the real size. It may even be very far of the real value, that's why this is a guess. 🙈 it's giving vibes, not facts.

`$obj->isMultipart()`

Returns whether the body of the related message is a multipart body. May trigger completion, when the "Content-Type" field is not defined.

⭐ Internals ⭐

`$obj->addNoRealize($field)`

Add a field, like Mail::Message::Head::Complete::add() does, but avoid the loading of a possibly partial header. This method does not test the validity of the argument, nor flag the header as changed. This does not trigger completion. 💀

`$obj->addOrderedFields($fields)`

`$obj->fileLocation()`

Returns the location of the header in the file, as a pair begin and end. The begin is the first byte of the header. The end is the first byte after the header. 📍

`$obj->load()`

Be sure that the header is loaded. This returns the loaded header object.

`$obj->moveLocation($distance)`

Move the registration of the header in the file.

`$obj->read($parser)`

Read the header information of one message into this header structure. This method is called by the folder object (some Mail::Box sub-class), which passes the $parser as an argument.

`$obj->setNoRealize($field)`

Set a field, but avoid the loading of a possibly partial header as set() does. This method does not test the validity of the argument, nor flag the header as changed. This does not trigger completion.

🌈 Error handling 🌈

Extends "Error handling" in Mail::Reporter.

`$obj->AUTOLOAD()`

Inherited, see "Error handling" in Mail::Reporter

`$obj->notImplemented()`

Inherited, see "Error handling" in Mail::Reporter

🧼 Cleanup 🧼

Extends "Cleanup" in Mail::Reporter.

`$obj->DESTROY()`

Inherited, see "Cleanup" in Mail::Reporter

💖 DETAILS 💖

🎀 Ordered header fields

ngl bestie, a lot of Perl implementations fumble this one hard — they mess with the order of header fields and it's giving chaos. For some fields the order genuinely has to stay put (especially the resent groups, check Mail::Message::Head::ResentGroup).

MailBox keeps the fields in the exact order they showed up in the source. Add a new field? It goes at the end, no cutting the line. Replace a field with a new value? It stays in its original spot, periodt. 👑

🌸 Head class implementation

So the header of a MIME message object is basically a set of lines, and those lines are called fields (by default they're Mail::Message::Field objects, iykyk). Depending on the situation, the knowledge about those fields can be in one of three situations, and each one gets its own sub-class of this module:

Mail::Message::Head::Complete — here it's a sure thing, all the knowledge about the header is available. So when you get() info from the header and it's not there, bestie, it will never be there. It's not hiding, it's just not there. 💀
Mail::Message::Head::Subset — there's no certainty whether all header lines are known (probably not, fr fr). This can happen when you read a fast index file, like it says in Mail::Box::MH::Index. The object automatically transforms itself into a Mail::Message::Head::Complete the moment all header lines must be known. Glow-up, honestly. ✨
Mail::Message::Head::Partial — a partial header is like a subset header: probably incomplete. Which means you can't be sure whether a get() for a field failed because the field isn't part of the message, or because it's just not known to the program yet. Here's the difference though: the subset header knows where to go get the other fields, and the partial header does not. It cannot hide its imperfection. It's giving "I'm a mystery even to myself" energy. 😭
Mail::Message::Head::Delayed — in this case, there is not a single field known. Access to this header will always trigger loading of the full header. Zero chill, all trigger. 🌈

🦋 Subsets of header fields

Message headers can get large, and that's exactly why MailBox hands you simplified access to some subsets of the info. You can grab these sets of fields together, and create and delete them as a group. Group project but make it slay. 💅

Right now, these are the sets that are defined:

Mail::Message::Head::ResentGroup — a resent group is a set of fields used to log one step in the transmission of the message from the original sender to the destination. Each step adds a set of headers to indicate when the message was received and how it was forwarded (without modification). Pro tip: these fields are best created using Mail::Message::bounce(). 🫶
Mail::Message::Head::ListGroup — fields used to administer and log mailing list activity. Mailing list software has to play trics with the original message to be able to get the reply on that message back to the mailing list. Usually a large number of lines get added. (Yes, "trics" — that's how the original spells it, I'm not fixing it, it's iconic. 🎀)
Mail::Message::Head::SpamGroup — a set of fields containing header fields produced by spam detection software. You may want to remove these fields when you store a message for a longer period of time. Declutter era. 🧹

🚨 DIAGNOSTICS 🚨

Error: class $package does not implement method $method. — Fatal error: the specific $package (or one of its superclasses) does not implement this method where it should. This message means that some other related classes do implement this method, however the class at hand does not. Probably you should investigate this and probably inform the author of the package. Cast by notImplemented(). Not me getting called out by a diagnostic 😭

👀 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 is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

okay that's the whole page bestie, you ate that 🍓 this was perl v5.42.0, dated 2026-02-05, and it's the Mail::M...ge::Head(3) page — go forth and handle your headers with main character energy 💜✨

📦 where this page comes from

fedora 44: perl-Mail-Message 4.04-1.fc44 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms