{
    "mode": "perldoc",
    "parameter": "Mail::Message::Head",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3AMessage%3A%3AHead/json",
    "generated": "2026-06-10T13:42:46Z",
    "synopsis": "my $head = Mail::Message::Head->new;\n$head->add('From: me@localhost');\n$head->add(From => 'me@localhost');\n$head->add(Mail::Message::Field->new(From => 'me'));\nmy $subject = $head->get('subject');\nmy @rec = $head->get('received');\n$head->delete('From');",
    "sections": {
        "NAME": {
            "content": "Mail::Message::Head - the header of one message\n",
            "subsections": []
        },
        "INHERITANCE": {
            "content": "Mail::Message::Head\nis a Mail::Reporter\n\nMail::Message::Head is extended by\nMail::Message::Head::Complete\nMail::Message::Head::Delayed\nMail::Message::Head::Subset\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "my $head = Mail::Message::Head->new;\n$head->add('From: me@localhost');\n$head->add(From => 'me@localhost');\n$head->add(Mail::Message::Field->new(From => 'me'));\nmy $subject = $head->get('subject');\nmy @rec = $head->get('received');\n$head->delete('From');\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "\"Mail::Message::Head\" MIME headers are part of Mail::Message messages, which are grouped in\nMail::Box folders.\n\nATTENTION!!! most functionality about e-mail headers is described in\nMail::Message::Head::Complete, which is a matured header object. Other kinds of headers will be\ntranslated to that type when time comes.\n\nOn this page, the general methods which are available on any header are described. Read about\ndifferences in the sub-class specific pages.\n\nExtends \"DESCRIPTION\" in Mail::Reporter.\n",
            "subsections": []
        },
        "OVERLOADED": {
            "content": "overload: \"\"\n(stringifaction) The header, when used as string, will format as if\nMail::Message::Head::Complete::string() was called, so return a nicely folder full header.\nAn exception is made for Carp, which will get a simplified string to avoid unreadible\nmessages from \"croak\" and \"confess\".\n\nexample: using a header object as string\n\nprint $head;     # implicit stringification by print\n$head->print;    # the same\n\nprint \"$head\";   # explicit stringication\n\noverload: bool\nWhen the header does not contain any lines (which is illegal, according to the RFCs), false\nis returned. In all other cases, a true value is produced.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Extends \"METHODS\" in Mail::Reporter.\n",
            "subsections": [
                {
                    "name": "Constructors",
                    "content": "Extends \"Constructors\" in Mail::Reporter.\n\nMail::Message::Head->build( [PAIR|$field]-LIST )\nA fast way to construct a header with many lines. The PAIRs are \"(name, content)\" pairs of\nthe header, but it is also possible to pass Mail::Message::Field objects. A\nMail::Message::Head::Complete header is created by simply calling\nMail::Message::Head::Complete::build(), and then each field is added. Double field names are\npermitted.\n\nexample:\n\nmy $subject = Mail::Message::Field->new(Subject => 'xyz');\n\nmy $head = Mail::Message::Head->build\n( From     => 'me@example.com'\n, To       => 'you@anywhere.aq'\n, $subject\n, Received => 'one'\n, Received => 'two'\n);\n\nprint ref $head;\n# -->  Mail::Message::Head::Complete\n\nMail::Message::Head->new(%options)\nCreate a new message header object. The object will store all the fields of a header. When\nyou get information from the header, it will be returned to you as Mail::Message::Field\nobjects, although the fields may be stored differently internally.\n\nIf you try to instantiate a Mail::Message::Head, you will automatically be upgraded to a\nMail::Message::Head::Complete --a full head.\n\n-Option    --Defined in     --Default\nfieldtype                   Mail::Message::Field::Fast\nlog         Mail::Reporter   'WARNINGS'\nmessage                      undef\nmodified                     <false>\ntrace       Mail::Reporter   'WARNINGS'\n\nfieldtype => CLASS\nThe type of objects that all the fields will have. This must be an extension of\nMail::Message::Field.\n\nlog => LEVEL\nmessage => MESSAGE\nThe MESSAGE where this header belongs to. Usually, this is not known at creation of the\nheader, but sometimes it is. If not, call the message() method later to set it.\n\nmodified => BOOLEAN\ntrace => LEVEL\n"
                },
                {
                    "name": "The header",
                    "content": "$obj->isDelayed()\nHeaders may only be partially read, in which case they are called delayed. This method\nreturns true if some header information still needs to be read. Returns false if all header\ndata has been read. Will never trigger completion.\n\n$obj->isEmpty()\nAre there any fields defined in the current header? Be warned that the header will not be\nloaded for this: delayed headers will return true in any case.\n\n$obj->isModified()\nReturns whether the header has been modified after being read.\n\nexample:\n\nif($head->isModified) { ... }\n\n$obj->knownNames()\nLike Mail::Message::Head::Complete::names(), but only returns the known header fields, which\nmay be less than \"names\" for header types which are partial. \"names()\" will trigger\ncompletion, where \"knownNames()\" does not.\n\n$obj->message( [$message] )\nGet (after setting) the message where this header belongs to. This does not trigger\ncompletion.\n\n$obj->modified( [BOOLEAN] )\nSets the modified flag to BOOLEAN. Without value, the current setting is returned, but in\nthat case you can better use isModified(). Changing this flag will not trigger header\ncompletion.\n\nexample:\n\n$head->modified(1);\nif($head->modified) { ... }\nif($head->isModified) { ... }\n\n$obj->orderedFields()\nReturns the fields ordered the way they were read or added.\n"
                },
                {
                    "name": "Access to the header",
                    "content": "$obj->get( $name, [$index] )\nGet the data which is related to the field with the $name. The case of the characters in\n$name does not matter.\n\nIf there is only one data element defined for the $name, or if there is an $index specified\nas the second argument, only the specified element will be returned. If the field $name\nmatches more than one header the return value depends on the context. In LIST context, all\nvalues will be returned in the order they are read. In SCALAR context, only the last value\nwill be returned.\n\nexample:\n\nmy $head = Mail::Message::Head->new;\n$head->add('Received: abc');\n$head->add('Received: xyz');\n$head->add('Subject: greetings');\n\nmy @reclist   = $head->get('Received');\nmy $recscalar = $head->get('Received');\nprint \",@reclist,$recscalar,\"     # ,abc xyz, xyz,\nprint $head->get('Received', 0);    # abc\nmy @sublist   = $head->get('Subject');\nmy $subscalar = $head->get('Subject');\nprint \",@sublist,$subscalar,\"     # ,greetings, greetings,\n\n$obj->study( $name, [$index] )\nLike get(), but puts more effort in understanding the contents of the field.\nMail::Message::Field::study() will be called for the field with the specified FIELDNAME,\nwhich returns Mail::Message::Field::Full objects. In scalar context only the last field with\nthat name is returned. When an $index is specified, that element is returned.\n"
                },
                {
                    "name": "About the body",
                    "content": "$obj->guessBodySize()\nTry to estimate the size of the body of this message, but without parsing the header or\nbody. The result might be \"undef\" or a few percent of the real size. It may even be very far\nof the real value, that's why this is a guess.\n\n$obj->isMultipart()\nReturns whether the body of the related message is a multipart body. May trigger completion,\nwhen the \"Content-Type\" field is not defined.\n"
                },
                {
                    "name": "Internals",
                    "content": "$obj->addNoRealize($field)\nAdd a field, like Mail::Message::Head::Complete::add() does, but avoid the loading of a\npossibly partial header. This method does not test the validity of the argument, nor flag\nthe header as changed. This does not trigger completion.\n\n$obj->addOrderedFields($fields)\n$obj->fileLocation()\nReturns the location of the header in the file, as a pair begin and end. The begin is the\nfirst byte of the header. The end is the first byte after the header.\n\n$obj->load()\nBe sure that the header is loaded. This returns the loaded header object.\n\n$obj->moveLocation($distance)\nMove the registration of the header in the file.\n\n$obj->read($parser)\nRead the header information of one message into this header structure. This method is called\nby the folder object (some Mail::Box sub-class), which passes the $parser as an argument.\n\n$obj->setNoRealize($field)\nSet a field, but avoid the loading of a possibly partial header as set() does. This method\ndoes not test the validity of the argument, nor flag the header as changed. This does not\ntrigger completion.\n"
                },
                {
                    "name": "Error handling",
                    "content": "Extends \"Error handling\" in Mail::Reporter.\n\n$obj->AUTOLOAD()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->addReport($object)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nMail::Message::Head->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level, $callback] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->errors()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->log( [$level, [$strings]] )\nMail::Message::Head->log( [$level, [$strings]] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logPriority($level)\nMail::Message::Head->logPriority($level)\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->logSettings()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->notImplemented()\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->report( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->reportAll( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->trace( [$level] )\nInherited, see \"Error handling\" in Mail::Reporter\n\n$obj->warnings()\nInherited, see \"Error handling\" in Mail::Reporter\n"
                },
                {
                    "name": "Cleanup",
                    "content": "Extends \"Cleanup\" in Mail::Reporter.\n\n$obj->DESTROY()\nInherited, see \"Cleanup\" in Mail::Reporter\n"
                }
            ]
        },
        "DETAILS": {
            "content": "",
            "subsections": [
                {
                    "name": "Ordered header fields",
                    "content": "Many Perl implementations make a big mistake by disturbing the order of header fields. For some\nfields (especially the *resent groups*, see Mail::Message::Head::ResentGroup) the order shall be\nmaintained.\n\nMailBox will keep the order of the fields as they were found in the source. When your add a new\nfield, it will be added at the end. If your replace a field with a new value, it will stay in\nthe original order.\n"
                },
                {
                    "name": "Head class implementation",
                    "content": "The header of a MIME message object contains a set of lines, which are called *fields* (by\ndefault represented by Mail::Message::Field objects). Dependent on the situation, the knowledge\nabout the fields can be in one of three situations, each represented by a sub-class of this\nmodule:\n\n*   Mail::Message::Head::Complete\n\nIn this case, it is sure that all knowledge about the header is available. When you get()\ninformation from the header and it is not there, it will never be there.\n\n*   Mail::Message::Head::Subset\n\nThere is no certainty whether all header lines are known (probably not). This may be caused\nas result of reading a fast index file, as described in Mail::Box::MH::Index. The object is\nautomatically transformed into a Mail::Message::Head::Complete when all header lines must be\nknown.\n\n*   Mail::Message::Head::Partial\n\nA partial header is like a subset header: probably the header is incomplete. The means that\nyou are not sure whether a get() for a field fails because the field is not a part of the\nmessage or that it fails because it is not yet known to the program. Where the subset header\nknows where to get the other fields, the partial header does not know it. It cannot hide its\nimperfection.\n\n*   Mail::Message::Head::Delayed\n\nIn this case, there is no single field known. Access to this header will always trigger the\nloading of the full header.\n"
                },
                {
                    "name": "Subsets of header fields",
                    "content": "Message headers can be quite large, and therefore MailBox provides simplified access to some\nsubsets of information. You can grab these sets of fields together, create and delete them as\ngroup.\n\nOn the moment, the following sets are defined:\n\n*   Mail::Message::Head::ResentGroup\n\nA *resent group* is a set of fields which is used to log one step in the transmission of the\nmessage from the original sender to the destination.\n\nEach step adds a set of headers to indicate when the message was received and how it was\nforwarded (without modification). These fields are best created using\nMail::Message::bounce().\n\n*   Mail::Message::Head::ListGroup\n\nFields which are used to administer and log mailing list activity. Mailing list software has\nto play trics with the original message to be able to get the reply on that message back to\nthe mailing list. Usually a large number of lines are added.\n\n*   Mail::Message::Head::SpamGroup\n\nA set of fields which contains header fields which are produced by spam detection software.\nYou may want to remove these fields when you store a message for a longer period of time.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Error: Package $package does not implement $method.\nFatal error: the specific package (or one of its superclasses) does not implement this\nmethod where it should. This message means that some other related classes do implement this\nmethod however the class at hand does not. Probably you should investigate this and probably\ninform the author of the package.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "This module is part of Mail-Message distribution version 3.012, built on February 11, 2022.\nWebsite: http://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "Mail::Message::Head - the header of one message",
    "flags": [],
    "examples": [],
    "see_also": []
}