man > Mail::Message::Field

📛 NAME

Mail::Message::Field - one line of a message header

🚀 Quick Reference

Use CaseCommandDescription
Create a fieldMail::Message::Field->new(From => 'user@example.com')🔧 Create a new header field object
Get field name (lowercase)$field->name🏷️ Returns the field name in lowercase
Get unfolded body$field->unfoldedBody📝 Returns the body as a single line (no folding)
Print field to filehandle$field->print(\*OUT)🖨️ Print the folded header line
Get attribute value$field->attribute('charset')🔑 Get an attribute (e.g., charset from Content-Type)
Get addresses$field->addresses📧 Returns list of Mail::Address objects
Stringify field"$field"🔤 Overloaded to return unfolded body
Study field (full parsing)$field->study🔬 Turn into Mail::Message::Field::Full for detailed access

🧬 INHERITANCE

Mail::Message::Field
  is a Mail::Reporter

Mail::Message::Field is extended by
  Mail::Message::Field::Fast
  Mail::Message::Field::Flex
  Mail::Message::Field::Full

📝 SYNOPSIS

my $field = Mail::Message::Field->new(From => 'fish AT tux.aq');
print $field->name;
print $field->body;
print $field->comment;
print $field->content;  # body & comment
$field->print(\*OUT);
print $field->string;
print "$field\n";
print $field->attribute('charset') || 'us-ascii';

📖 DESCRIPTION

This implementation follows the guidelines of rfc2822 as close as possible, and may there produce a different output than implementations based on the obsolete rfc822. However, the old output will still be accepted.

These objects each store one header line, and facilitates access routines to the information hidden in it. Also, you may want to have a look at the added methods of a message:

my @from    = $message->from;
my $sender  = $message->sender;
my $subject = $message->subject;
my $msgid   = $message->messageId;

my @to      = $message->to;
my @cc      = $message->cc;
my @bcc     = $message->bcc;
my @dest    = $message->destinations;

my $other   = $message->get('Reply-To');

Extends "DESCRIPTION" in Mail::Reporter.

⚡ OVERLOADED

🔤 overload: ""

(stringification) produces the unfolded body of the field, which may be what you expect. This is what makes what the field object seems to be a simple string. The string is produced by unfoldedBody().

example:

print $msg->get('subject');  # via overloading
print $msg->get('subject')->unfoldedBody; # same

my $subject = $msg->get('subject') || 'your mail';
print "Re: $subject\n";

🔢 overload: 0+

(numification) When the field is numeric, the value will be returned. The result is produced by toInt(). If the value is not correct, a 0 is produced, to simplify calculations.

⚖️ overload: <=>

(numeric comparison) Compare the integer field contents with something else.

example:

if($msg->get('Content-Length') > 10000) ...
if($msg->size > 10000) ... ; # same, but better

✅ overload: bool

Always true, to make it possible to say "if($field)".

🔤 overload: cmp

(string comparison) Compare the unfolded body of a field with another field or a string, using the buildin "cmp".

🛠️ METHODS

Extends "METHODS" in Mail::Reporter.

🏗️ Constructors

Extends "Constructors" in Mail::Reporter.

📇 The field

🏷️ Access to the name

📝 Access to the body

📦 Access to the content

🔧 Other methods

🔬 Internals

🚨 Error handling

Extends "Error handling" in Mail::Reporter.

🧹 Cleanup

Extends "Cleanup" in Mail::Reporter.

🔍 DETAILS

📐 Field syntax

Fields are stored in the header of a message, which are represented by Mail::Message::Head objects. A field is a combination of a name, body, and attributes. Especially the term "body" is cause for confusion: sometimes the attributes are considered to be part of the body.

The name of the field is followed by a colon (":""," not preceded by blanks, but followed by one blank). Each attribute is preceded by a separate semi-colon ("";""). Names of fields are case-insensitive and cannot contain blanks.

💡 Example: of fields

Correct fields:

Field: hi!
Content-Type: text/html; charset=latin1

Incorrect fields, but accepted:

Field : wrong, blank before colon
Field:                 # wrong, empty
Field:not nice, blank preferred after colon
One Two: wrong, blank in name

📐 Folding fields

Fields which are long can be folded to span more than one line. The real limit for lines in messages is only at 998 characters, however such long lines are not easy to read without support of an application. Therefore rfc2822 (which defines the message syntax) specifies explicitly that field lines can be re-formatted into multiple sorter lines without change of meaning, by adding new-line characters to any field before any blank or tab.

Usually, the lines are reformatted to create lines which are 78 characters maximum. Some applications try harder to fold on nice spots, like before attributes. Especially the "Received" field is often manually folded into some nice layout. In most cases however, it is preferred to produce lines which are as long as possible but max 78.

BE WARNED that all fields can be subjected to folding, and that you usually want the unfolded value.

💡 Example: of field folding

Subject: this is a short line, and not folded

Subject: this subject field is much longer, and therefore
 folded into multiple
 lines, although one more than needed.

📐 Structured fields

The rfc2822 describes a large number of header fields explicitly. These fields have a defined meaning. For some of the fields, like the "Subject" field, the meaning is straight forward the contents itself. These fields are the Unstructured Fields.

Other fields have a well defined internal syntax because their content is needed by e-mail applications. For instance, the "To" field contains addresses which must be understood by all applications in the same way. These are the Structured Fields, see isStructured().

📐 Comments in fields

Stuctured fields can contain comments, which are pieces of text enclosed in parenthesis. These comments can be placed close to anywhere in the line and must be ignored be the application. Not all applications are capable of handling comments correctly in all circumstances.

💡 Example: of field comments

To: mailbox (Mail::Box mailinglist) 
Date: Thu, 13 Sep 2001 09:40:48 +0200 (CEST)
Subject: goodbye (was: hi!)

On the first line, the text "Mail::Box mailinglist" is used as comment. Be warned that rfc2822 explicitly states that comments in e-mail address specifications should not be considered to contain any usable information.

On the second line, the timezone is specified as comment. The "Date" field format has no way to indicate the timezone of the sender, but only contains the timezone difference to UTC, however one could decide to add this as comment. Application must ignore this data because the "Date" field is structured.

The last field is unstructured. The text between parentheses is an integral part of the subject line.

🔍 Getting a field

As many programs as there are handling e-mail, as many variations on accessing the header information are requested. Be careful which way you access the data: read the variations described here and decide which solution suites your needs best.

🔍 Using get() field

The "get()" interface is copied from other Perl modules which can handle e-mail messages. Many applications which simply replace Mail::Internet objects by Mail::Message objects will work without modification.

There is more than one get method. The exact results depend on which get you use. When Mail::Message::get() is called, you will get the unfolded, stripped from comments, stripped from attributes contents of the field as string. Character-set encodings will still be in the string. If the same fieldname appears more than once in the header, only the last value is returned.

When Mail::Message::Head::get() is called in scalar context, the last field with the specified name is returned as field object. This object strinigfies into the unfolded contents of the field, including attributes and comments. In list context, all appearances of the field in the header are returned as objects.

BE WARNED that some lines seem unique, but are not according to the official rfc. For instance, "To" fields can appear more than once. If your program calls "get('to')" in scalar context, some information is lost.

💡 Example: of using get()

print $msg->get('subject') || 'no subject';
print $msg->head->get('subject') || 'no subject';

my @to = $msg->head->get('to');

🔍 Using study() field

As the name "study" already implies, this way of accessing the fields is much more thorough but also slower. The "study" of a field is like a "get", but provides easy access to the content of the field and handles character-set decoding correctly.

The Mail::Message::study() method will only return the last field with that name as object. Mail::Message::Head::study() and Mail::Message::Field::study() return all fields when used in list context.

💡 Example: of using study()

print $msg->study('subject') || 'no subject';
my @rec  = $msg->head->study('Received');

my $from = $msg->head->get('From')->study;
my $from = $msg->head->study('From');  # same
my @addr = $from->addresses;

🔍 Using resent groups

Some fields belong together in a group of fields. For instance, a set of lines is used to define one step in the mail transport process. Each step adds a "Received" line, and optionally some "Resent-*" lines and "Return-Path". These groups of lines shall stay together and in order when the message header is processed.

The "Mail::Message::Head::ResentGroup" object simplifies the access to these related fields. These resent groups can be deleted as a whole, or correctly constructed.

💡 Example: of using resent groups

my $rgs = $msg->head->resentGroups;
$rgs[0]->delete if @rgs;

$msg->head->removeResentGroups;

📊 The field's data

There are many ways to get the fields info as object, and there are also many ways to process this data within the field.

📊 Access to the field

📊 Using simplified field access

Some fields are accessed that often that there are support methods to provide simplified access. All these methods are called upon a message directly.

💡 Example: of simplified field access

print $message->subject;
print $message->get('subject') || '';  # same

my @from = $message->from; # returns addresses
$message->reply->send if $message->sender;

The "sender" method will return the address specified in the "Sender" field, or the first named in the "From" field. It will return "undef" in case no address is known.

📊 Specifying field data

Field data can be anything, strongly dependent on the type of field at hand. If you decide to construct the fields very carefully via some Mail::Message::Field::Full extension (like via Mail::Message::Field::Addresses objects), then you will have protection build-in. However, you can bluntly create any Mail::Message::Field object based on some data.

When you create a field, you may specify a string, object, or an array of strings and objects. On the moment, objects are only used to help the construction on e-mail addresses, however you may add some of your own.

The following rules (implemented in stringifyData()) are obeyed given the argument is:

💡 Example: specifying simple field data

my $f = Mail::Message::Field->new(Subject => 'hi!');
my $b = Mail::Message->build(Subject => 'monkey');

💡 Example: specifying e-mail addresses for a field

use Mail::Address;
my $fish = Mail::Address->new('Mail::Box', 'fish AT tux.aq');
print $fish->format;   # ==> Mail::Box 
my $exa  = Mail::Address->new(undef, 'me AT example.com');
print $exa->format;    # ==> me AT example.com

my $b = $msg->build(To => "you AT example.com");
my $b = $msg->build(To => $fish);
my $b = $msg->build(To => [ $fish, $exa ]);

my @all = ($fish, "you AT example.com", $exa);
my $b = $msg->build(To => \@all);
my $b = $msg->build(To => [ "xyz", @all ]);

💡 Example: specifying identities for a field

use User::Identity;
my $patrik = User::Identity->new
 ( name      => 'patrik'
 , full_name => "Patrik Fältström"  # from rfc
 , charset   => "ISO-8859-1"
 );
$patrik->add
 ( email    => "him AT home.net"
 );

my $b = $msg->build(To => $patrik);

$b->get('To')->print;
  # ==> =?ISO-8859-1?Q?Patrik_F=E4ltstr=F6m?=
  #

🏛️ Field class implementation

For performance reasons only, there are three types of fields: the fast, the flexible, and the full understander:

⚠️ DIAGNOSTICS

📚 SEE ALSO

This module is part of Mail-Message distribution version 3.012, built on February 11, 2022. Website: http://perl.overmeer.net/CPAN/

📄 LICENSE

Copyrights 2001-2022 by [Mark Overmeer <markov AT 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/

Mail::Message::Field □✕
📛 NAME 🚀 Quick Reference 🧬 INHERITANCE 📝 SYNOPSIS 📖 DESCRIPTION ⚡ OVERLOADED
🔤 overload: "" 🔢 overload: 0+ ⚖️ overload: <=> ✅ overload: bool 🔤 overload: cmp
🛠️ METHODS
🏗️ Constructors 📇 The field 🏷️ Access to the name 📝 Access to the body 📦 Access to the content 🔧 Other methods 🔬 Internals 🚨 Error handling 🧹 Cleanup
🔍 DETAILS
📐 Field syntax 🔍 Getting a field 📊 The field's data 🏛️ Field class implementation
⚠️ DIAGNOSTICS 📚 SEE ALSO 📄 LICENSE

Generated by phpman v4.9.26-1-g511901d · Markdown · JSON · MCP Author: Che Dong Under GNU General Public License
2026-07-28 07:21 @216.73.217.46
CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Valid XHTML 1.0 Transitional!Valid CSS!
Enhanced by LLM: deepseek-v4-flash / taotoken.net / www.chedong.com - original format

^_top_^