| Mail::Message::Head(3pm) | User Contributed Perl Documentation | Mail::Message::Head(3pm) |
Mail::Message::Head - the header of one message
Mail::Message::Head is a Mail::Reporter Mail::Message::Head is extended by Mail::Message::Head::Complete Mail::Message::Head::Delayed Mail::Message::Head::Subset
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');
"Mail::Message::Head" MIME headers are part of Mail::Message messages, which are grouped in Mail::Box folders.
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.
Extends "DESCRIPTION" in Mail::Reporter.
example: using a header object as string
print $head; # implicit stringification by print
$head->print; # the same
print "$head"; # explicit stringication
Extends "METHODS" in Mail::Reporter.
Extends "Constructors" in Mail::Reporter.
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
If you try to instantiate a Mail::Message::Head, you will automatically be upgraded to a Mail::Message::Head::Complete --a full head.
-Option --Defined in --Default
field_type Mail::Message::Field::Fast
log Mail::Reporter 'WARNINGS'
message undef
modified <false>
trace Mail::Reporter 'WARNINGS'
example:
if($head->isModified) { ... }
example:
$head->modified(1); if($head->modified) { ... } if($head->isModified) { ... }
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,
Extends "Error handling" in Mail::Reporter.
Extends "Cleanup" in Mail::Reporter.
Many Perl implementations make a big mistake by disturbing the order of header fields. For some fields (especially the resent groups, see Mail::Message::Head::ResentGroup) the order shall be maintained.
MailBox will keep the order of the fields as they were found in the source. When your add a new field, it will be added at the end. If your replace a field with a new value, it will stay in the original order.
The header of a MIME message object contains a set of lines, which are called fields (by default represented by Mail::Message::Field objects). Dependent on the situation, the knowledge about the fields can be in one of three situations, each represented by a sub-class of this module:
In this case, it is sure that all knowledge about the header is available. When you get() information from the header and it is not there, it will never be there.
There is no certainty whether all header lines are known (probably not). This may be caused as result of reading a fast index file, as described in Mail::Box::MH::Index. The object is automatically transformed into a Mail::Message::Head::Complete when all header lines must be known.
A partial header is like a subset header: probably the header is incomplete. The means that you are not sure whether a get() for a field fails because the field is not a part of the message or that it fails because it is not yet known to the program. Where the subset header knows where to get the other fields, the partial header does not know it. It cannot hide its imperfection.
In this case, there is no single field known. Access to this header will always trigger the loading of the full header.
Message headers can be quite large, and therefore MailBox provides simplified access to some subsets of information. You can grab these sets of fields together, create and delete them as group.
On the moment, the following sets are defined:
A resent group is a set of fields which is 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). These fields are best created using Mail::Message::bounce().
Fields which are 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 are added.
A set of fields which contains header fields which are produced by spam detection software. You may want to remove these fields when you store a message for a longer period of time.
This module is part of Mail-Message distribution version 3.012, built on February 11, 2022. Website: http://perl.overmeer.net/CPAN/
Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.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/
| 2022-02-14 | perl v5.34.0 |